@lengmoxxl/sdk 0.1.5 → 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)。
 
 ## 插件上下文
 
@@ -13,7 +12,7 @@
 | `ui.publish(topic, data)` | 后端向本插件 UI 发事件，对应前端 `ui.subscribe` |
 | `ui.subscribe<T>(topic, callback)` | 前端订阅本插件后端事件，返回取消订阅的函数 |
 | `ui.request<T>(method, params?)` | 前端调用本插件后端方法，返回 `Promise<T>` |
-| `connect(machine, signal?)` | 后端借用机器连接：`{ host?: string }`，可带 `AbortSignal` |
+| `connect(machine, signal?)` | 后端借用机器连接：`{ host?, env? }`，可带 `AbortSignal` |
 | `host.dataDirectory` / `host.config` | 插件私有数据目录 / 本插件设置 |
 | `host.tabs(options)` / `host.open(url)` | 前端开侧栏标签页 / 用系统浏览器打开 http、https |
 | `host.preview` | `{ url, message }`，HTML 预览 frame 的地址与握手消息 |
@@ -23,7 +22,7 @@
 `ui.handle` 注册的方法名不能含 `:`；`ui.publish` 与 `ui.subscribe` 的主题由宿主加插件 id 前缀，
 `global` 用原始主题，自定义主题要自己加命名空间（如 `directory-demo:opened`）。
 
-`connect({})` 连接本机，`connect({ host })` 连接 SSH。
+`connect({})` 连接本机，`connect({ host })` 连接 SSH；`env` 是那台机器上节点启动时的环境。
 
 宿主为相同机器复用连接并计数，每次取得连接对应一次 `disconnect()`。
 
@@ -65,6 +64,7 @@
 放入 init.ts `workspaces` 的插件用 `ui.handle` 提供：`workspaces()`（`WorkspaceRow[]`，
 按显示顺序）、`workspace-menu()`（`WorkspaceMenuItem[]`）、`workspace-create({ key })`
 （返回 `{ id }`）、`workspace-select({ id })`、`workspace-close({ id })`、
+`workspace-rename({ id, name })`（名字为空表示交回 provider 自己跟随的名字）、
 `workspace-move({ id, before? })`（`before` 是目标工作区 id，不是索引；省略为末尾，且只
 允许同一 provider 内拖动）。
 
@@ -86,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 与后台子孙进程）。
@@ -109,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 }`。非零退出码仍返回结果，无法启动、
@@ -118,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)`。
 
@@ -146,7 +153,9 @@ connection.disconnect();
 
 `openMachine` 返回 `Promise<MachineConnection>`。`type` 为 `'local'` 或 `'ssh'`；local 可给
 `binary`，ssh 必须给 `host`（系统 ssh 目标或别名）与可选 `agent`（`InstallAgent`），两者
-都可给 `signal`。不传 `agent` 时 SDK 不下载二进制；连接用 BatchMode SSH。
+都可给 `env`（节点启动时带上的环境，值里的 `$NAME` 用运行节点那台机器的环境展开）与 `signal`。
+不传 `agent` 时 SDK 不下载二进制；连接用 BatchMode SSH。
 
-`agentCommand(command)` 返回拼接后的 shell 命令：在 PATH 前加入远端 `$HOME/.local/bin`，
-并携带当前进程的 WANGCAI_HOME（会转义；command 本身不转义，只传可信命令）。
+`agentCommand(command, env)` 返回拼接后的 shell 命令：在 PATH 前加入远端 `$HOME/.local/bin`，
+再带上当前进程的 WANGCAI_HOME 与配置要求的环境；值里的 `$NAME` 留给远端 shell 展开。命令本身
+不转义，只传可信内容。

package/dist/agent.d.ts

@@ -1 +1,2 @@
-export declare function agentCommand(command: string): string;
+export declare function exportableEnvironment(env?: Record<string, string>): Record<string, string>;
+export declare function agentCommand(command: string, env?: Record<string, string>): string;

package/dist/channel.d.ts

@@ -1,4 +1,5 @@
 import type { MachineConnection } from './connection';
+import type { Machine } from './types';
 export type Dispose = () => void | Promise<void>;
 /** A sidebar tab the window opens for a plugin: what it is called, and what it draws. */
 export interface TabOptions {
@@ -31,9 +32,7 @@ export interface MainContext {
         handle<T = unknown>(method: string, handler: (params: T) => unknown): Dispose;
         publish(topic: string, data: unknown): void;
     };
-    connect(machine: {
-        host?: string;
-    }, signal?: AbortSignal): Promise<MachineConnection>;
+    connect(machine: Pick<Machine, 'host' | 'env'>, signal?: AbortSignal): Promise<MachineConnection>;
     host: {
         dataDirectory: string;
         config: any;

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

@@ -174,14 +174,25 @@ var Pty = class {
 };
 
 // agent.ts
-function agentCommand(command) {
+var quoted = (value) => value.replace(/[\\`"]/g, "\\$&");
+function exportableEnvironment(env = {}) {
+  return Object.fromEntries(Object.entries(env).filter(([name]) => /^[A-Za-z_][A-Za-z0-9_]*$/.test(name)));
+}
+function agentCommand(command, env = {}) {
   const home = process.env.WANGCAI_HOME;
   const exportHome = home ? `export WANGCAI_HOME='${home.replace(/'/g, String.raw`'\''`)}'; ` : "";
-  return `${exportHome}export PATH="$HOME/.local/bin:$PATH"; ${command}`;
+  const exports2 = Object.entries(exportableEnvironment(env)).map(([name, value]) => `export ${name}="${quoted(value)}"; `).join("");
+  return `${exportHome}export PATH="$HOME/.local/bin:$PATH"; ${exports2}${command}`;
 }
 
 // connection.ts
 var exec = (0, import_node_util.promisify)(import_node_child_process.execFile);
+function expandedEnvironment(env) {
+  return Object.fromEntries(Object.entries(env).map(([name, value]) => [
+    name,
+    value.replace(/\$\{?([A-Za-z_][A-Za-z0-9_]*)\}?/g, (_, variable) => process.env[variable] ?? "")
+  ]));
+}
 var MachineConnection = class {
   constructor(options) {
     this.options = options;
@@ -195,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;
@@ -239,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();
@@ -276,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 = {
@@ -340,8 +369,12 @@ var MachineConnection = class {
     try {
       let info;
       let port;
+      const env = exportableEnvironment(this.options.env);
       if (this.options.type === "local") {
-        const { stdout } = await exec(this.options.binary ?? "wangcai", ["server", "start", "--json"], { timeout: 15e3 });
+        const { stdout } = await exec(this.options.binary ?? "wangcai", ["server", "start", "--json"], {
+          timeout: 15e3,
+          env: { ...process.env, ...expandedEnvironment(env) }
+        });
         info = JSON.parse(stdout);
         port = info.port;
       } else {
@@ -353,7 +386,7 @@ var MachineConnection = class {
           "-o",
           "ConnectTimeout=8",
           this.options.host,
-          agentCommand("wangcai server start --json")
+          agentCommand("wangcai server start --json", env)
         ], { timeout: 15e3, maxBuffer: 64 * 1024 });
         info = JSON.parse(stdout);
         if (!Number.isInteger(info.port) || info.port < 1 || info.port > 65535) throw new Error("Node returned an invalid port.");
@@ -388,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) {
@@ -436,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

@@ -10,6 +10,7 @@ export type InstallAgent = (host: string, signal?: AbortSignal) => Promise<void>
  *   workspace-create({ key }) -> { id: string }        the id of the workspace it made
  *   workspace-select({ id })
  *   workspace-close({ id })
+ *   workspace-rename({ id, name })                     an empty name gives the workspace back to the name it followed
  *   workspace-move({ id, before? })
  *
  * Every view that follows the workspace in front shares these channel topics, whatever the provider
@@ -35,6 +36,7 @@ export interface Machine {
     id: string;
     name: string;
     host?: string;
+    env?: Record<string, string>;
 }
 export interface WorkspaceActive {
     machine: Machine;
@@ -52,11 +54,13 @@ export interface FileClick {
 export type ConnectionOptions = {
     type: 'local';
     binary?: string;
+    env?: Record<string, string>;
     signal?: AbortSignal;
 } | {
     type: 'ssh';
     host: string;
     agent?: InstallAgent;
+    env?: Record<string, string>;
     signal?: AbortSignal;
 };
 export interface Size {
@@ -112,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.5",
+  "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": {