@lengmoxxl/sdk 0.1.4 → 0.1.5

package/README.md

@@ -1,54 +1,152 @@
-# @lengmoxxl/sdk
-The client SDK for [WangCai](https://github.com/lengmoXXL/WangCai), the terminal app. It reaches a machine, the one
-the app runs on or one over SSH, and drives its terminals, files and subprocesses through a single connection.
+# @lengmoxxl/sdk：接口参考
 
-A WangCai plugin compiles against this package for the types it uses; the machines belong to the app, which keeps
-one connection per machine and hands it to every plugin that asks for one.
+本参考对应 SDK `0.1.5`：连接本机或 SSH 机器上的旺财后台进程，提供终端、文件与子进程
+操作。插件入口与生命周期见 [插件开发手册](../docs/plugins.md)，进程关系见
+[架构说明](../docs/architecture.md)。
 
-## Install
+## 插件上下文
 
-```
-npm install @lengmoxxl/sdk
-```
+| 成员 | 说明 |
+| --- | --- |
+| `global` | 公共 `Bus`，跨插件与前后端通信 |
+| `ui.handle<T>(method, handler)` | 后端注册方法，返回取消注册的 `Dispose` |
+| `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` |
+| `host.dataDirectory` / `host.config` | 插件私有数据目录 / 本插件设置 |
+| `host.tabs(options)` / `host.open(url)` | 前端开侧栏标签页 / 用系统浏览器打开 http、https |
+| `host.preview` | `{ url, message }`，HTML 预览 frame 的地址与握手消息 |
 
-`ws` is the only runtime dependency. The bundled `dist/index.cjs` reads it at require time.
+请求与事件传可结构化克隆的数据，不传函数、DOM、Pty 或连接实例。
 
-## Use
+`ui.handle` 注册的方法名不能含 `:`；`ui.publish` 与 `ui.subscribe` 的主题由宿主加插件 id 前缀，
+`global` 用原始主题，自定义主题要自己加命名空间（如 `directory-demo:opened`）。
 
-```ts
-import { openMachine } from '@lengmoxxl/sdk';
+`connect({})` 连接本机，`connect({ host })` 连接 SSH。
 
-const connection = await openMachine({ type: 'local', binary: '/path/to/wangcai' });
+宿主为相同机器复用连接并计数，每次取得连接对应一次 `disconnect()`。
 
-const sessions = await connection.pty.list();
-const session = await connection.pty.create({ rows: 24, cols: 80 }, '/repo');
-const terminal = await connection.pty.attach(session.id);
-terminal.onData(({ data }) => process.stdout.write(data));
-await terminal.write('git status\n');
+`Dispose = () => void | Promise<void>`，卸载时清理资源，不要关闭用户仍要保留的 PTY。
 
-const { stdout } = await connection.subprocess.exec('git', ['status'], { cwd: '/repo' });
-connection.disconnect();
-```
+`Bus`：`publish(topic, data): Promise<void>`、`subscribe<T>(topic, callback): () => void`。
 
-`openMachine` returns a `MachineConnection`; every call opens its own. Sharing one belongs to the caller: a
-connection is reference counted, so callers that hand the same one around keep it alive until the last
-`disconnect()`. `openMachine({ type: 'ssh', host, agent })` calls `agent(host)` before it connects: putting
-the carrier agent on the host belongs to the app that embeds the SDK.
+`host.dataDirectory` 默认 `~/.local/share/wangcai/data/<plugin-id>`。
 
-- `connection.pty` - `list`, `cwd`, `create`, `attach`, `close`
-- `connection.fs` - `stat`, `readDirectory`, `readFile`
-- `connection.subprocess` - `exec`, which returns `{ stdout, stderr, code }` as `Uint8Array`
-- `connection.onState` - connection status and the sessions it can see
+`host.config` 是浅合并，避免把自定义字段命名为 `theme`，配色键见
+[README 主题参数](../README.md#主题参数)。
 
-The host-side context a plugin is activated with (`MainContext`, `UiContext`, `Bus`, and the workspace protocol
-types) lives in the `@lengmoxxl/sdk/channel` entry. That entry is types only.
+## 标签页
 
-## Build
+`host.tabs({ id, title, tooltip?, workspaceId?, onClose?, mount })`：`id`、`title` 必填，
+`tooltip?` 是标签上的悬停提示（缺省用 `title`），`workspaceId` 缺省用当前工作区；
+`mount(container)` 返回的 `TabContent.dispose` 必填，`onSelect?` 在选中、工作区刷新或侧栏重新显示时
+都可能调用，`onClose?` 在移除标签页时先于 `dispose` 调用。
 
+相同插件 id、工作区 id、标签 id 再次调用 `host.tabs` 会复用并选中；尚无工作区时打开的标签页
+会在第一个工作区激活时绑定到它。
+
+`TabRecord = { plugin, id, workspaceId? }` 只保存身份，插件的 `open(context, record)` 据此恢复
+内容，资源必须仍在。
+
+## 预览
+
+用 `host.preview.url` 建 iframe，设 `sandbox="allow-scripts"`，不要加
+`allow-same-origin`；收到来源为该 frame、`event.data === host.preview.message` 的消息后
+`postMessage(html, '*')`。预览会执行其中脚本。
+
+## 插件配置
+
+插件 `config` 是嵌套对象，叶子声明 `type` 与可选 `default`；宿主只保留 schema 声明的键，
+缺失或类型不符时取 default，`array` 内部条目由插件自己验证。
+
+## 工作区协议
+
+放入 init.ts `workspaces` 的插件用 `ui.handle` 提供：`workspaces()`（`WorkspaceRow[]`，
+按显示顺序）、`workspace-menu()`（`WorkspaceMenuItem[]`）、`workspace-create({ key })`
+（返回 `{ id }`）、`workspace-select({ id })`、`workspace-close({ id })`、
+`workspace-move({ id, before? })`（`before` 是目标工作区 id，不是索引；省略为末尾，且只
+允许同一 provider 内拖动）。
+
+provider 要保证工作区 id 在所有 provider 的行中唯一识别；`error` 由 provider 给出并在重试成功后清除，
+宿主不禁用带 `error` 的菜单项。
+
+约定的公共主题：`workspaces`（行变化，App 重新请求列表）、`workspace:active`
+（`WorkspaceActive | null`，provider 发布）、`workspace:query`（视图请求 provider 再发布
+当前工作区）、`onclick`（`FileClick`）。
+
+字段类型见 SDK 导出的 `WorkspaceRow`、`WorkspaceMenuItem`、`Machine`、`WorkspaceActive`
+与 `FileClick`，定义在 `sdk/types.ts`。
+
+## 机器、终端与子进程
+
+`MachineConnection`：`ready`（首次连接就绪）、`state`、`port`（本地 loopback 端口，SSH 时
+为转发端口）、`onState(callback)`、`retain()`（连接层使用）、`disconnect()`，以及 `pty`、`fs`、
+`subprocess`。
+
+`MachineState` 含 `status`、`error?`、`sessions`、`generation`。
+
+断线会自动重连并重新 attach 已挂载的终端与进程，失败的请求与输入不自动重放，后台进程重启时旧 Pty 与进程失效。
+
+`connection.pty`：`list()`、`cwd(id)`、`create(size?, cwd?)`（默认 24 行 80 列；cwd 用绝对目录，
+省略时在后台进程的 HOME 下启动）、`attach(id)`（复用句柄）、`close(id)`（结束 shell 与后台子孙进程）。
+
+`Size` 用整数：rows 2–300，cols 2–500。
+
+`Session` 有 `id, title`、`pid, rows, cols`、`exit_code: number | null`。
+
+`Pty`：`id`、`onSnapshot(callback)`、`onData(callback)`、`write(data)`、`resize(size)`、
+`detach()`（停止挂载，不关闭 shell）。
+
+`Output = { data: Uint8Array; seq: number }`，`Snapshot` 额外有 `rows, cols`。
+
+字节含终端控制序列，交给终端模拟器，不要把快照当键盘输入重发。
+
+`receive` 与 `release(error?)` 由连接层使用。
+
+`connection.fs`：`stat(path)` 返回 `{ isDirectory: boolean } | null`、`readDirectory(path)` 返回
+`DirectoryEntry[]`（`{ name, isDirectory }`）、`readFile(path)` 返回原始字节。
+
+路径为绝对路径，`readFile` 上限 16 MiB；SDK 不提供写入、删除或上传接口。
+
+`connection.subprocess.exec(program, args, options)`：`args` 是独立 argv（不经 shell 展开），
+`options.cwd` 是绝对工作目录，`options.env` 覆盖继承的环境变量；返回
+`{ stdout: Uint8Array; stderr: Uint8Array; code: number }`。非零退出码仍返回结果，无法启动、
+超时、输出超限或被信号终止时 reject；stdin 关闭，长时间或交互用 `subprocess.spawn` 或 PTY。
+
+执行上限 15 秒，SDK 等待响应上限 20 秒，stdout 与 stderr 各最多 8 MiB，断线取消未完成的 exec。
+
+`connection.subprocess.spawn(program, args, options)`（`options` 同 `exec`）启动一个
+长期存活的进程，stdin、stdout、stderr 都是管道，返回 `ProcessInfo = { id, pid, exit_code }`；
+`attach(id)` 复用句柄（未 attach 前不接收输出），`close(id)` 结束进程及其进程组；进程归后台进程所有，不 `close` 就一直留着。
+
+`Process`：`id`、`onData(callback)`、`onExit(callback)`、`write(data)`。
+
+`ProcessOutput = { data: Uint8Array; seq: number; stream: 'stdout' | 'stderr' }`，两路输出各自按序到达，
+`seq` 单调递增，跨两路的先后以 `seq` 为准。
+
+`onExit` 给出退出码（被信号结束时按 shell 的 128+signal），节点来不及投递时给出 `undefined`，此时
+输出流已不可信，进程可能仍在运行，请重新 `spawn`。
+
+`write` 按 32 KiB 分片、按序应用，进程退出后 reject；先 `attach` 再写。
+
+`receive` 与 `release(error?)` 由连接层使用。
+
+## 独立 Node 客户端
+
+App 插件用 `context.connect`；插件之外才调用 `openMachine`：
+
+```ts
+import { openMachine } from '@lengmoxxl/sdk';
+
+const connection = await openMachine({ type: 'local', binary: '/path/to/wangcai' });
+await connection.fs.readDirectory('/');
+connection.disconnect();
 ```
-npm run build
-```
 
-From the repository root (the TypeScript and esbuild devDependencies live in the workspace root): esbuild bundles
-`index.ts` into `dist/index.cjs` with `ws` left external, then `tsc` emits the declarations. `npm publish` and
-`npm pack` run it for you.
+`openMachine` 返回 `Promise<MachineConnection>`。`type` 为 `'local'` 或 `'ssh'`；local 可给
+`binary`，ssh 必须给 `host`（系统 ssh 目标或别名）与可选 `agent`（`InstallAgent`），两者
+都可给 `signal`。不传 `agent` 时 SDK 不下载二进制；连接用 BatchMode SSH。
+
+`agentCommand(command)` 返回拼接后的 shell 命令：在 PATH 前加入远端 `$HOME/.local/bin`，
+并携带当前进程的 WANGCAI_HOME（会转义；command 本身不转义，只传可信命令）。

package/dist/connection.d.ts

@@ -1,9 +1,11 @@
-import type { ConnectionOptions, MachineState, Session, Size, DirectoryEntry, ExecOptions, ExecResult } from './types';
+import type { ConnectionOptions, MachineState, Session, Size, DirectoryEntry, ExecOptions, ExecResult, ProcessInfo } from './types';
+import { Process } from './process';
 import { Pty } from './pty';
 export declare class MachineConnection {
     private options;
     private listeners;
     private terminals;
+    private processes;
     port?: number;
     private instance?;
     readonly ready: Promise<void>;
@@ -42,6 +44,9 @@ export declare class MachineConnection {
     };
     subprocess: {
         exec: (program: string, args: string[], options: ExecOptions) => Promise<ExecResult>;
+        spawn: (program: string, args: string[], options: ExecOptions) => Promise<ProcessInfo>;
+        attach: (id: string) => Promise<Process>;
+        close: (id: string) => Promise<void>;
     };
     private cleanup;
     private fail;

package/dist/index.cjs

@@ -41,6 +41,68 @@ var import_node_net = require("node:net");
 var import_node_util = require("node:util");
 var import_ws = __toESM(require("ws"));
 
+// process.ts
+var CHUNK = 32 * 1024;
+var Process = class {
+  constructor(id, request) {
+    this.id = id;
+    this.request = request;
+  }
+  sequence = -1;
+  error;
+  ended = false;
+  code;
+  buffered = [];
+  outputs = /* @__PURE__ */ new Set();
+  exits = /* @__PURE__ */ new Set();
+  receive(event) {
+    if (this.error) return;
+    if (event.event === "exit" || event.event === "lost") {
+      this.ended = true;
+      this.code = event.event === "exit" ? event.code : void 0;
+      for (const callback of this.exits) callback(this.code);
+      this.exits.clear();
+      return;
+    }
+    if (event.seq <= this.sequence) return;
+    this.sequence = event.seq;
+    const output = { data: event.data, seq: event.seq, stream: event.event };
+    if (!this.outputs.size) this.buffered.push(output);
+    for (const callback of this.outputs) callback(output);
+  }
+  onData(callback) {
+    this.outputs.add(callback);
+    for (const event of this.buffered) callback(event);
+    this.buffered = [];
+    return () => {
+      this.outputs.delete(callback);
+    };
+  }
+  /** Its exit code, or nothing when the node lost the stream and the process may still be running. */
+  onExit(callback) {
+    this.exits.add(callback);
+    if (this.ended) callback(this.code);
+    return () => {
+      this.exits.delete(callback);
+    };
+  }
+  async write(data) {
+    if (this.error) throw this.error;
+    const requests = [];
+    for (let offset = 0; offset < data.length; offset += CHUNK) {
+      const chunk = Buffer.from(data.subarray(offset, offset + CHUNK)).toString("base64");
+      requests.push(this.request("process_write", { session_id: this.id, data: chunk }));
+    }
+    await Promise.all(requests);
+  }
+  release(error = new Error("Process detached")) {
+    this.error = error;
+    this.outputs.clear();
+    this.exits.clear();
+    this.buffered = [];
+  }
+};
+
 // pty.ts
 var Pty = class {
   constructor(id, request, remove) {
@@ -132,6 +194,7 @@ var MachineConnection = class {
   }
   listeners = /* @__PURE__ */ new Set();
   terminals = /* @__PURE__ */ new Map();
+  processes = /* @__PURE__ */ new Map();
   // Where the daemon listens: the window reaches it with this.
   port;
   instance;
@@ -174,6 +237,8 @@ var MachineConnection = class {
     this.rejectReady(new Error("Connection cancelled"));
     for (const terminal of this.terminals.values()) terminal.release();
     this.terminals.clear();
+    for (const process2 of this.processes.values()) process2.release();
+    this.processes.clear();
     this.state.status = "disconnected";
     this.state.error = void 0;
     this.publish();
@@ -217,6 +282,26 @@ var MachineConnection = class {
     exec: async (program, args, options) => {
       const result = await this.request("exec", { program, args, ...options }, 2e4);
       return { stdout: Buffer.from(result.stdout, "base64"), stderr: Buffer.from(result.stderr, "base64"), code: result.code };
+    },
+    spawn: (program, args, options) => this.request("spawn", { program, args, ...options }),
+    attach: async (id) => {
+      const existing = this.processes.get(id);
+      if (existing) return existing;
+      const process2 = new Process(id, (op, params) => this.request(op, params));
+      this.processes.set(id, process2);
+      try {
+        await this.request("process_attach", { session_id: id });
+      } catch (error) {
+        this.processes.delete(id);
+        process2.release();
+        throw error;
+      }
+      return process2;
+    },
+    close: async (id) => {
+      await this.request("process_close", { session_id: id });
+      this.processes.get(id)?.release();
+      this.processes.delete(id);
     }
   };
   cleanup() {
@@ -285,9 +370,12 @@ var MachineConnection = class {
           if (binary) {
             const bytes = data;
             const length = bytes.readUInt32BE(0);
-            if (length > bytes.length - 4) throw new Error("Invalid terminal packet");
+            if (length > bytes.length - 4) throw new Error("Invalid packet");
             const header = JSON.parse(bytes.subarray(4, 4 + length).toString());
-            this.terminals.get(header.session_id)?.receive({ ...header, data: bytes.subarray(4 + length) });
+            const event = { ...header, data: bytes.subarray(4 + length) };
+            const terminal = this.terminals.get(header.session_id);
+            if (terminal) terminal.receive(event);
+            else this.processes.get(header.session_id)?.receive(event);
           } else {
             const message = JSON.parse(data.toString());
             if (message.id) {
@@ -326,6 +414,8 @@ var MachineConnection = class {
       if (this.instance && this.instance !== actual.instance_id) {
         for (const terminal of this.terminals.values()) terminal.release(new Error("Node restarted; terminal no longer exists"));
         this.terminals.clear();
+        for (const process2 of this.processes.values()) process2.release(new Error("Node restarted; process no longer exists"));
+        this.processes.clear();
       }
       this.instance = actual.instance_id;
       for (const [id, terminal] of this.terminals) {
@@ -337,6 +427,15 @@ var MachineConnection = class {
           this.terminals.delete(id);
         }
       }
+      for (const [id, process2] of this.processes) {
+        try {
+          await this.request("process_attach", { session_id: id });
+        } catch (error) {
+          if (!current()) return;
+          process2.release(error);
+          this.processes.delete(id);
+        }
+      }
       if (!current()) return;
       this.state.status = "connected";
       this.state.error = void 0;

package/dist/index.d.ts

@@ -1,8 +1,9 @@
 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, InstallAgent, Profile, Theme, WorkspaceActive, WorkspaceRow, WorkspaceMenuItem } from './types';
+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 { MachineConnection } from './connection';
+export type { Process } from './process';
 export type { Pty } from './pty';
 /** Opens one connection to a machine and waits for it to be ready. */
 export declare function openMachine(options: ConnectionOptions): Promise<MachineConnection>;

package/dist/process.d.ts

@@ -0,0 +1,19 @@
+import type { ProcessEvent, ProcessOutput } from './types';
+export declare class Process {
+    readonly id: string;
+    private request;
+    private sequence;
+    private error?;
+    private ended;
+    private code?;
+    private buffered;
+    private outputs;
+    private exits;
+    constructor(id: string, request: (op: string, params: Record<string, unknown>) => Promise<unknown>);
+    receive(event: ProcessEvent): void;
+    onData(callback: (event: ProcessOutput) => void): () => void;
+    /** Its exit code, or nothing when the node lost the stream and the process may still be running. */
+    onExit(callback: (code?: number) => void): () => void;
+    write(data: Uint8Array): Promise<void>;
+    release(error?: Error): void;
+}

package/dist/types.d.ts

@@ -6,7 +6,7 @@ export type InstallAgent = (host: string, signal?: AbortSignal) => Promise<void>
  *
  *   workspaces()              -> WorkspaceRow[]        one flat row per workspace, in draw order
  *   workspace-menu()          -> WorkspaceMenuItem[]   what the menu offers to open; an entry that carries
- *                                                      an error stays listed but is not clickable
+ *                                                      an error stays listed with its reason, and a click retries it
  *   workspace-create({ key }) -> { id: string }        the id of the workspace it made
  *   workspace-select({ id })
  *   workspace-close({ id })
@@ -88,6 +88,26 @@ export type TerminalEvent = ({
 } & Output) & {
     session_id: string;
 };
+export interface ProcessInfo {
+    id: string;
+    pid: number;
+    exit_code: number | null;
+}
+/** `stream` names the pipe the bytes came from. */
+export interface ProcessOutput extends Output {
+    stream: 'stdout' | 'stderr';
+}
+export type ProcessEvent = ({
+    event: 'stdout' | 'stderr';
+} & Output | {
+    event: 'exit';
+    seq: number;
+    code: number;
+} | {
+    event: 'lost';
+}) & {
+    session_id: string;
+};
 export interface DirectoryEntry {
     name: string;
     isDirectory: boolean;

package/package.json

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