@lengmoxxl/sdk 0.1.6 → 0.1.7

package/README.md

@@ -1,8 +1,7 @@
 # @lengmoxxl/sdk：接口参考
 
-本参考对应 SDK `0.1.5`：连接本机或 SSH 机器上的旺财后台进程，提供终端、文件与子进程
-操作。插件入口与生命周期见 [插件开发手册](../docs/plugins.md)，进程关系见
-[架构说明](../docs/architecture.md)。
+SDK 连接本机或 SSH 机器上的旺财后台进程，提供终端、文件与子进程操作。插件入口与生命周期见
+[插件开发手册](../docs/plugins.md)，进程关系见 [架构说明](../docs/architecture.md)。
 
 ## 插件上下文
 
@@ -87,7 +86,8 @@ provider 要保证工作区 id 在所有 provider 的行中唯一识别；`error
 
 `MachineState` 含 `status`、`error?`、`sessions`、`generation`。
 
-断线会自动重连并重新 attach 已挂载的终端与进程，失败的请求与输入不自动重放，后台进程重启时旧 Pty 与进程失效。
+断线会自动重连并重新 attach 已挂载的终端、进程与文件订阅，失败的请求与输入不自动重放，后台进程重启时
+旧 Pty 与进程失效。
 
 `connection.pty`：`list()`、`cwd(id)`、`create(size?, cwd?)`（默认 24 行 80 列；cwd 用绝对目录，
 省略时在后台进程的 HOME 下启动）、`attach(id)`（复用句柄）、`close(id)`（结束 shell 与后台子孙进程）。
@@ -110,6 +110,12 @@ provider 要保证工作区 id 在所有 provider 的行中唯一识别；`error
 
 路径为绝对路径，`readFile` 上限 16 MiB；SDK 不提供写入、删除或上传接口。
 
+`connection.fs.watch(path, options, callback)` 订阅该路径的变化，`options.recursive` 决定是否含子目录，
+返回的 `() => void` 关闭订阅。回调收到的是 `FileChanges = { created, modified, removed }`，一个安静窗口
+（约 200ms 没新事件，最长 2 秒）一批，路径按订阅时给的根路径书写；连接彻底关闭（最后一个持有者
+`disconnect()`）时一并结束。macOS 走 FSEvents，创建与删除多数时候报成 `modified`；Linux 走 inotify，
+三类齐全。
+
 `connection.subprocess.exec(program, args, options)`：`args` 是独立 argv（不经 shell 展开），
 `options.cwd` 是绝对工作目录，`options.env` 覆盖继承的环境变量；返回
 `{ stdout: Uint8Array; stderr: Uint8Array; code: number }`。非零退出码仍返回结果，无法启动、
@@ -119,7 +125,7 @@ provider 要保证工作区 id 在所有 provider 的行中唯一识别；`error
 
 `connection.subprocess.spawn(program, args, options)`（`options` 同 `exec`）启动一个
 长期存活的进程，stdin、stdout、stderr 都是管道，返回 `ProcessInfo = { id, pid, exit_code }`；
-`attach(id)` 复用句柄（未 attach 前不接收输出），`close(id)` 结束进程及其进程组；进程归后台进程所有，不 `close` 就一直留着。
+`attach(id)` 复用句柄（未 attach 前不接收输出），`close(id)` 结束进程及其进程组；进程归后台进程所有，除 `close` 外，只有起它或最后 `attach` 它的那条连接断开后 60 秒内没有连接再 `attach`，节点才会自己收回。
 
 `Process`：`id`、`onData(callback)`、`onExit(callback)`、`write(data)`。
 

package/dist/connection.d.ts

@@ -1,4 +1,4 @@
-import type { ConnectionOptions, MachineState, Session, Size, DirectoryEntry, ExecOptions, ExecResult, ProcessInfo } from './types';
+import type { ConnectionOptions, MachineState, Session, Size, DirectoryEntry, ExecOptions, ExecResult, ProcessInfo, FileChanges, WatchOptions } from './types';
 import { Process } from './process';
 import { Pty } from './pty';
 export declare class MachineConnection {
@@ -6,6 +6,7 @@ export declare class MachineConnection {
     private listeners;
     private terminals;
     private processes;
+    private watchers;
     port?: number;
     private instance?;
     readonly ready: Promise<void>;
@@ -41,6 +42,7 @@ export declare class MachineConnection {
         } | null>;
         readDirectory: (path: string) => Promise<DirectoryEntry[]>;
         readFile: (path: string) => Promise<Uint8Array>;
+        watch: (path: string, options: WatchOptions, callback: (changes: FileChanges) => void) => Promise<() => void>;
     };
     subprocess: {
         exec: (program: string, args: string[], options: ExecOptions) => Promise<ExecResult>;

package/dist/index.cjs

@@ -206,6 +206,7 @@ var MachineConnection = class {
   listeners = /* @__PURE__ */ new Set();
   terminals = /* @__PURE__ */ new Map();
   processes = /* @__PURE__ */ new Map();
+  watchers = /* @__PURE__ */ new Map();
   // Where the daemon listens: the window reaches it with this.
   port;
   instance;
@@ -250,6 +251,7 @@ var MachineConnection = class {
     this.terminals.clear();
     for (const process2 of this.processes.values()) process2.release();
     this.processes.clear();
+    this.watchers.clear();
     this.state.status = "disconnected";
     this.state.error = void 0;
     this.publish();
@@ -287,6 +289,22 @@ var MachineConnection = class {
     readFile: async (path) => {
       const result = await this.request("read_file", { path });
       return Buffer.from(result.data, "base64");
+    },
+    watch: async (path, options, callback) => {
+      const watchId = `watch-${++this.serial}`;
+      const recursive = options.recursive ?? false;
+      this.watchers.set(watchId, { recursive, path, callback });
+      try {
+        await this.request("watch", { watch_id: watchId, path, recursive });
+      } catch (error) {
+        this.watchers.delete(watchId);
+        throw error;
+      }
+      return () => {
+        this.watchers.delete(watchId);
+        void this.request("unwatch", { watch_id: watchId }).catch(() => {
+        });
+      };
     }
   };
   subprocess = {
@@ -403,6 +421,9 @@ var MachineConnection = class {
             } else if (message.event === "sessions_changed") {
               void this.refresh().catch(() => {
               });
+            } else if (message.event === "fs_changed") {
+              const watcher = this.watchers.get(message.watch_id);
+              if (watcher) watcher.callback({ created: message.created, modified: message.modified, removed: message.removed });
             }
           }
         } catch (error) {
@@ -451,6 +472,13 @@ var MachineConnection = class {
           this.processes.delete(id);
         }
       }
+      for (const [watchId, watcher] of this.watchers) {
+        try {
+          await this.request("watch", { watch_id: watchId, path: watcher.path, recursive: watcher.recursive });
+        } catch {
+          if (!current()) return;
+        }
+      }
       if (!current()) return;
       this.state.status = "connected";
       this.state.error = void 0;

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { MachineConnection } from './connection';
 import type { ConnectionOptions } from './types';
 export { agentCommand } from './agent';
-export type { ConnectionOptions, FileClick, Machine, MachineState, Session, Size, Output, Snapshot, TerminalEvent, DirectoryEntry, ExecOptions, ExecResult, ProcessEvent, ProcessInfo, ProcessOutput, InstallAgent, Profile, Theme, WorkspaceActive, WorkspaceRow, WorkspaceMenuItem } from './types';
+export type { ConnectionOptions, FileClick, Machine, MachineState, Session, Size, Output, Snapshot, TerminalEvent, DirectoryEntry, FileChanges, WatchOptions, ExecOptions, ExecResult, ProcessEvent, ProcessInfo, ProcessOutput, InstallAgent, Profile, Theme, WorkspaceActive, WorkspaceRow, WorkspaceMenuItem } from './types';
 export type { MachineConnection } from './connection';
 export type { Process } from './process';
 export type { Pty } from './pty';

package/dist/types.d.ts

@@ -116,6 +116,14 @@ export interface DirectoryEntry {
     name: string;
     isDirectory: boolean;
 }
+export interface FileChanges {
+    created: string[];
+    modified: string[];
+    removed: string[];
+}
+export interface WatchOptions {
+    recursive?: boolean;
+}
 export interface ExecOptions {
     cwd: string;
     env?: Record<string, string>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lengmoxxl/sdk",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "description": "Client SDK for WangCai: connect to a local or remote machine and drive its pty, files and git",
   "license": "MIT",
   "repository": {