glimpse-sdk 0.3.0 → 0.5.0

package/README.md

@@ -10,6 +10,18 @@ Requires Node.js 20+.
 npm install glimpse-sdk
 ```
 
+## Develop
+
+Create and live-run a TypeScript applet project with the Glimpse tooling:
+
+```sh
+glimpse-applet new counter --lang typescript
+cd counter
+glimpse-applet dev
+```
+
+Read `docs/custom-applets/tooling.md` for project layout, `applet.toml`, dev applets, linking, and diagnostics.
+
 ## Goals
 
 - typed protocol models
@@ -92,3 +104,23 @@ Use explicit registration helpers instead of decorators:
 
 The SDK owns the line transport. `status(state)` produces the panel items;
 `popover(state)` produces the popover tree; both are pure functions of state.
+
+## IPC client
+
+Talk to a running Glimpse daemon: subscribe to event channels and dispatch
+actions. `ipc(service)` only resolves the socket path — the connection is
+opened lazily.
+
+```ts
+import { ipc } from "glimpse-sdk";
+
+const sub = ipc("shell"); // "shell" | "wallpaper" | "idle" | "lock"
+
+// Fire an action; awaits the ack, throws IpcError if the server rejects it.
+const ack = await sub.dispatch("open_uri", { uri: "https://example.com" });
+
+// Stream events until the socket closes.
+for await (const ev of sub.listen("audio.*")) {
+  console.log(ev.name, ev.fields);
+}
+```

package/dist/src/app.d.ts

@@ -7,6 +7,20 @@ interface OutgoingMessage {
     data: unknown;
     line: string;
 }
+interface ShowNotificationArgs {
+    summary: string;
+    body?: string;
+    urgency?: string;
+}
+interface OpenUriArgs {
+    uri: string;
+}
+interface CopyToClipboardArgs {
+    text: string;
+}
+interface DismissNotificationArgs {
+    id: number;
+}
 export declare abstract class Applet<State extends object> {
     state: State;
     private readonly handlerMap;
@@ -30,6 +44,11 @@ export declare abstract class Applet<State extends object> {
     onChange(id: string, handler: Handler<ChangeEvent>): void;
     onToggle(id: string, handler: Handler<ToggleEvent>): void;
     isPopoverOpen(): boolean;
+    protected showNotification(args: ShowNotificationArgs): void;
+    protected openUri(args: OpenUriArgs): void;
+    protected copyToClipboard(args: CopyToClipboardArgs): void;
+    protected dismissNotification(args: DismissNotificationArgs): void;
+    protected closePopover(): void;
     run(): Promise<void>;
     protected drainOutgoingForTest(): Promise<OutgoingMessage[]>;
     private register;
@@ -38,5 +57,6 @@ export declare abstract class Applet<State extends object> {
     private scheduleRender;
     private flushRender;
     private emit;
+    private emitAction;
 }
 export {};

package/dist/src/app.js

@@ -43,6 +43,21 @@ export class Applet {
     isPopoverOpen() {
         return this.popoverOpen;
     }
+    showNotification(args) {
+        this.emitAction("show_notification", args);
+    }
+    openUri(args) {
+        this.emitAction("open_uri", args);
+    }
+    copyToClipboard(args) {
+        this.emitAction("copy_to_clipboard", args);
+    }
+    dismissNotification(args) {
+        this.emitAction("dismiss_notification", args);
+    }
+    closePopover() {
+        this.emitAction("close_popover", {});
+    }
     async run() {
         process.stdout.on("error", (err) => {
             if (err.code === "EPIPE") {
@@ -137,9 +152,7 @@ export class Applet {
         }
         const widget = await this.popover(this.state);
         const tree = { root: widget?.toProtocol() ?? null };
-        // Emit only when popover open, or first render, or clearing.
-        const shouldEmit = this.popoverOpen || this.lastTree === null || tree.root === null;
-        if (shouldEmit && !deepEqual(tree, this.lastTree)) {
+        if (!deepEqual(tree, this.lastTree)) {
             this.lastTree = tree;
             this.emit("popover", tree);
         }
@@ -157,6 +170,9 @@ export class Applet {
             }
         }
     }
+    emitAction(type, args) {
+        this.emit("action", { type, arguments: args });
+    }
 }
 function parseLine(line) {
     const trimmed = line.trim();

package/dist/src/index.d.ts

@@ -1,4 +1,5 @@
 export { Applet } from "./app.js";
 export { type CallbackEvent, type ChangeEvent, type ClickEvent, type InitEvent, type InputEvent, type PopoverEvent, type ScrollEvent, type ToggleEvent, parseCallbackEvent, parseInitEvent, } from "./events.js";
 export { Icon, StatusItem } from "./protocol.js";
+export { type Event, IpcError, Subscriber, ipc } from "./ipc.js";
 export { ActionItem, type Align, Badge, Box, Button, type ButtonVariant, Card, Checkbox, Column, type ContentFit, Copyable, EmptyState, Expander, Grid, GridChild, Hero, Image, Item, Label, LevelBar, type LevelBarMode, LinkButton, ListBox, MenuButton, Meter, Overlay, type Orientation, type PagerAppearance, PagerItem, PagerStrip, Picture, Progress, type Properties, PropertyList, Row, Scroll, Section, Select, SelectOption, Separator, Slider, Spinner, StatusDot, Switch, ToggleButton, TreeExpander, type TreeNode, type Variant, } from "./widgets.js";

package/dist/src/index.js

@@ -1,4 +1,5 @@
 export { Applet } from "./app.js";
 export { parseCallbackEvent, parseInitEvent, } from "./events.js";
 export { Icon, StatusItem } from "./protocol.js";
+export { IpcError, Subscriber, ipc } from "./ipc.js";
 export { ActionItem, Badge, Box, Button, Card, Checkbox, Column, Copyable, EmptyState, Expander, Grid, GridChild, Hero, Image, Item, Label, LevelBar, LinkButton, ListBox, MenuButton, Meter, Overlay, PagerItem, PagerStrip, Picture, Progress, PropertyList, Row, Scroll, Section, Select, SelectOption, Separator, Slider, Spinner, StatusDot, Switch, ToggleButton, TreeExpander, } from "./widgets.js";

package/dist/src/ipc.d.ts

@@ -0,0 +1,28 @@
+/** One decoded event line; `fields` values are unescaped. */
+export interface Event {
+    name: string;
+    ts: number;
+    fields: Record<string, string>;
+}
+/** Thrown on connection failure or a rejected dispatch (`ok=false`). */
+export declare class IpcError extends Error {
+}
+/** A resolved IPC endpoint. Cheap to create; holds only the socket path. */
+export declare class Subscriber {
+    private readonly socketPath;
+    constructor(socketPath: string);
+    /** Subscribe to `channel` (an exact name, `prefix.*`, or `*`) and yield
+     * events until the server closes the connection. */
+    listen(channel: string): AsyncGenerator<Event>;
+    /** Dispatch `action` with `params` on a fresh connection and await the
+     * ack. Resolves with the extra ack fields; rejects with `IpcError` if the
+     * server replies `ok=false`. */
+    dispatch(action: string, params?: Record<string, string>): Promise<Record<string, string>>;
+    private connect;
+}
+/** Resolve the {@link Subscriber} for `service` (`"shell"` for the panel).
+ *
+ * The socket is `<dir>/<service>.sock` (`shell` maps to `ipc.sock`) where
+ * `<dir>` is `$GLIMPSE_IPC_DIR`, else `$XDG_RUNTIME_DIR/glimpse`. No
+ * connection is made here. */
+export declare function ipc(service?: string): Subscriber;

package/dist/src/ipc.js

@@ -0,0 +1,214 @@
+// Minimal client for the Glimpse IPC socket.
+//
+// `ipc(service)` resolves a `Subscriber` (no I/O — the connection is opened
+// lazily). `Subscriber.listen` subscribes to an event channel and yields
+// decoded `Event`s; `Subscriber.dispatch` sends an action and awaits the
+// server ack on a one-shot connection. The wire protocol matches the
+// `glimpse-shell watch` / `dispatch` CLIs.
+import { createConnection } from "node:net";
+import { createInterface } from "node:readline";
+import { join } from "node:path";
+/** Thrown on connection failure or a rejected dispatch (`ok=false`). */
+export class IpcError extends Error {
+}
+/** A resolved IPC endpoint. Cheap to create; holds only the socket path. */
+export class Subscriber {
+    socketPath;
+    constructor(socketPath) {
+        this.socketPath = socketPath;
+    }
+    /** Subscribe to `channel` (an exact name, `prefix.*`, or `*`) and yield
+     * events until the server closes the connection. */
+    async *listen(channel) {
+        const conn = await this.connect();
+        try {
+            conn.socket.write(`subscribe ${channel}\n`);
+            for (;;) {
+                const next = await conn.lines.next();
+                if (next.done)
+                    return;
+                const line = next.value.trim();
+                if (line)
+                    yield parseEvent(line);
+            }
+        }
+        finally {
+            close(conn);
+        }
+    }
+    /** Dispatch `action` with `params` on a fresh connection and await the
+     * ack. Resolves with the extra ack fields; rejects with `IpcError` if the
+     * server replies `ok=false`. */
+    async dispatch(action, params = {}) {
+        validateToken("action", action, false);
+        const entries = Object.entries(params);
+        for (const [k] of entries)
+            validateToken("param key", k, true);
+        const conn = await this.connect();
+        try {
+            let line = action;
+            for (const [k, v] of entries) {
+                line += ` ${k}=${escape(v)}`;
+            }
+            conn.socket.write(line + "\n");
+            const next = await conn.lines.next();
+            if (next.done) {
+                throw new IpcError("IPC server closed connection without ack");
+            }
+            return parseAck(next.value.trim());
+        }
+        finally {
+            close(conn);
+        }
+    }
+    connect() {
+        return new Promise((resolve, reject) => {
+            const socket = createConnection({ path: this.socketPath });
+            let connected = false;
+            // This handler stays attached for the socket's whole lifetime. Never
+            // remove it: an unhandled 'error' event on a Socket throws and crashes
+            // the process. `close()` only destroys the socket, it does not detach.
+            socket.on("error", (err) => {
+                if (connected) {
+                    // Post-connect transport error: end the stream cleanly so the
+                    // line iterator completes instead of crashing the process.
+                    socket.destroy();
+                }
+                else {
+                    reject(new IpcError(`cannot connect to IPC socket at ${this.socketPath}: ${err.message}`));
+                }
+            });
+            socket.once("connect", () => {
+                connected = true;
+                const rl = createInterface({ input: socket, crlfDelay: Infinity });
+                const lines = rl[Symbol.asyncIterator]();
+                void (async () => {
+                    const hello = await lines.next();
+                    if (hello.done || !hello.value.startsWith("hello")) {
+                        rl.close();
+                        socket.destroy();
+                        reject(new IpcError(hello.done
+                            ? "IPC server closed connection before hello"
+                            : `unexpected IPC greeting: ${hello.value}`));
+                        return;
+                    }
+                    resolve({ socket, rl, lines });
+                })();
+            });
+        });
+    }
+}
+/** Resolve the {@link Subscriber} for `service` (`"shell"` for the panel).
+ *
+ * The socket is `<dir>/<service>.sock` (`shell` maps to `ipc.sock`) where
+ * `<dir>` is `$GLIMPSE_IPC_DIR`, else `$XDG_RUNTIME_DIR/glimpse`. No
+ * connection is made here. */
+export function ipc(service = "shell") {
+    return new Subscriber(socketPath(service));
+}
+function socketPath(service) {
+    const override = process.env.GLIMPSE_IPC_DIR;
+    let dir;
+    if (override) {
+        dir = override;
+    }
+    else {
+        const runtime = process.env.XDG_RUNTIME_DIR;
+        if (!runtime) {
+            throw new IpcError("neither GLIMPSE_IPC_DIR nor XDG_RUNTIME_DIR is set; " +
+                "cannot locate the Glimpse IPC socket");
+        }
+        dir = join(runtime, "glimpse");
+    }
+    return join(dir, service === "shell" ? "ipc.sock" : `${service}.sock`);
+}
+function close(conn) {
+    conn.rl.close();
+    conn.socket.destroy();
+}
+// The wire protocol splits client lines on whitespace and never unescapes
+// the command name or a field key, so an `action`/key with whitespace would
+// forge extra tokens or whole client lines. Values are safe (escaped).
+function validateToken(label, token, forbidEq) {
+    if (token.length === 0) {
+        throw new IpcError(`IPC ${label} must not be empty`);
+    }
+    if (/\s/.test(token)) {
+        throw new IpcError(`IPC ${label} "${token}" must not contain whitespace`);
+    }
+    if (forbidEq && token.includes("=")) {
+        throw new IpcError(`IPC param key "${token}" must not contain '='`);
+    }
+}
+function escape(s) {
+    return s
+        .replaceAll("\\", "\\\\")
+        .replaceAll("\n", "\\n")
+        .replaceAll("\t", "\\t")
+        .replaceAll(" ", "\\s");
+}
+function unescape(s) {
+    let out = "";
+    for (let i = 0; i < s.length; i++) {
+        if (s[i] !== "\\") {
+            out += s[i];
+            continue;
+        }
+        const next = s[++i];
+        if (next === "s")
+            out += " ";
+        else if (next === "n")
+            out += "\n";
+        else if (next === "t")
+            out += "\t";
+        else if (next === "\\")
+            out += "\\";
+        else if (next === undefined)
+            out += "\\";
+        else
+            out += "\\" + next;
+    }
+    return out;
+}
+function parseEvent(line) {
+    const tokens = line.split(/\s+/);
+    const name = tokens[0] ?? "";
+    let ts = 0;
+    const fields = {};
+    for (const token of tokens.slice(1)) {
+        const eq = token.indexOf("=");
+        if (eq < 0)
+            continue;
+        const key = token.slice(0, eq);
+        const value = unescape(token.slice(eq + 1));
+        if (key === "ts" && /^\d+$/.test(value)) {
+            ts = Number(value);
+            continue;
+        }
+        fields[key] = value;
+    }
+    return { name, ts, fields };
+}
+function parseAck(line) {
+    const tokens = line.split(/\s+/);
+    if (tokens[0] !== "ack") {
+        throw new IpcError(`expected an ack, got: ${line}`);
+    }
+    let ok = false;
+    const fields = {};
+    for (const token of tokens.slice(1)) {
+        const eq = token.indexOf("=");
+        if (eq < 0)
+            continue;
+        const key = token.slice(0, eq);
+        const value = unescape(token.slice(eq + 1));
+        if (key === "ok")
+            ok = value === "true";
+        else
+            fields[key] = value;
+    }
+    if (!ok) {
+        throw new IpcError(fields.error ?? "command failed");
+    }
+    return fields;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "glimpse-sdk",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Typed async framework for building Glimpse exec applets",
   "type": "module",
   "main": "dist/src/index.js",

package/src/app.ts

@@ -23,6 +23,24 @@ interface OutgoingMessage {
   line: string;
 }
 
+interface ShowNotificationArgs {
+  summary: string;
+  body?: string;
+  urgency?: string;
+}
+
+interface OpenUriArgs {
+  uri: string;
+}
+
+interface CopyToClipboardArgs {
+  text: string;
+}
+
+interface DismissNotificationArgs {
+  id: number;
+}
+
 export abstract class Applet<State extends object> {
   state: State;
 
@@ -83,6 +101,26 @@ export abstract class Applet<State extends object> {
     return this.popoverOpen;
   }
 
+  protected showNotification(args: ShowNotificationArgs): void {
+    this.emitAction("show_notification", args);
+  }
+
+  protected openUri(args: OpenUriArgs): void {
+    this.emitAction("open_uri", args);
+  }
+
+  protected copyToClipboard(args: CopyToClipboardArgs): void {
+    this.emitAction("copy_to_clipboard", args);
+  }
+
+  protected dismissNotification(args: DismissNotificationArgs): void {
+    this.emitAction("dismiss_notification", args);
+  }
+
+  protected closePopover(): void {
+    this.emitAction("close_popover", {});
+  }
+
   async run(): Promise<void> {
     process.stdout.on("error", (err: NodeJS.ErrnoException) => {
       if (err.code === "EPIPE") {
@@ -184,9 +222,7 @@ export abstract class Applet<State extends object> {
 
     const widget = await this.popover(this.state);
     const tree = { root: widget?.toProtocol() ?? null };
-    // Emit only when popover open, or first render, or clearing.
-    const shouldEmit = this.popoverOpen || this.lastTree === null || tree.root === null;
-    if (shouldEmit && !deepEqual(tree, this.lastTree)) {
+    if (!deepEqual(tree, this.lastTree)) {
       this.lastTree = tree;
       this.emit("popover", tree);
     }
@@ -204,6 +240,10 @@ export abstract class Applet<State extends object> {
       }
     }
   }
+
+  private emitAction(type: string, args: object): void {
+    this.emit("action", { type, arguments: args });
+  }
 }
 
 function parseLine(line: string): { command: string; data: unknown } | null {

package/src/index.ts

@@ -12,6 +12,7 @@ export {
   parseInitEvent,
 } from "./events.js";
 export { Icon, StatusItem } from "./protocol.js";
+export { type Event, IpcError, Subscriber, ipc } from "./ipc.js";
 export {
   ActionItem,
   type Align,

package/src/ipc.ts

@@ -0,0 +1,233 @@
+// Minimal client for the Glimpse IPC socket.
+//
+// `ipc(service)` resolves a `Subscriber` (no I/O — the connection is opened
+// lazily). `Subscriber.listen` subscribes to an event channel and yields
+// decoded `Event`s; `Subscriber.dispatch` sends an action and awaits the
+// server ack on a one-shot connection. The wire protocol matches the
+// `glimpse-shell watch` / `dispatch` CLIs.
+
+import { createConnection, type Socket } from "node:net";
+import { createInterface, type Interface } from "node:readline";
+import { join } from "node:path";
+
+/** One decoded event line; `fields` values are unescaped. */
+export interface Event {
+  name: string;
+  ts: number;
+  fields: Record<string, string>;
+}
+
+/** Thrown on connection failure or a rejected dispatch (`ok=false`). */
+export class IpcError extends Error {}
+
+interface Conn {
+  socket: Socket;
+  rl: Interface;
+  lines: AsyncIterator<string>;
+}
+
+/** A resolved IPC endpoint. Cheap to create; holds only the socket path. */
+export class Subscriber {
+  constructor(private readonly socketPath: string) {}
+
+  /** Subscribe to `channel` (an exact name, `prefix.*`, or `*`) and yield
+   * events until the server closes the connection. */
+  async *listen(channel: string): AsyncGenerator<Event> {
+    const conn = await this.connect();
+    try {
+      conn.socket.write(`subscribe ${channel}\n`);
+      for (;;) {
+        const next = await conn.lines.next();
+        if (next.done) return;
+        const line = next.value.trim();
+        if (line) yield parseEvent(line);
+      }
+    } finally {
+      close(conn);
+    }
+  }
+
+  /** Dispatch `action` with `params` on a fresh connection and await the
+   * ack. Resolves with the extra ack fields; rejects with `IpcError` if the
+   * server replies `ok=false`. */
+  async dispatch(
+    action: string,
+    params: Record<string, string> = {},
+  ): Promise<Record<string, string>> {
+    validateToken("action", action, false);
+    const entries = Object.entries(params);
+    for (const [k] of entries) validateToken("param key", k, true);
+    const conn = await this.connect();
+    try {
+      let line = action;
+      for (const [k, v] of entries) {
+        line += ` ${k}=${escape(v)}`;
+      }
+      conn.socket.write(line + "\n");
+      const next = await conn.lines.next();
+      if (next.done) {
+        throw new IpcError("IPC server closed connection without ack");
+      }
+      return parseAck(next.value.trim());
+    } finally {
+      close(conn);
+    }
+  }
+
+  private connect(): Promise<Conn> {
+    return new Promise<Conn>((resolve, reject) => {
+      const socket = createConnection({ path: this.socketPath });
+      let connected = false;
+      // This handler stays attached for the socket's whole lifetime. Never
+      // remove it: an unhandled 'error' event on a Socket throws and crashes
+      // the process. `close()` only destroys the socket, it does not detach.
+      socket.on("error", (err: Error) => {
+        if (connected) {
+          // Post-connect transport error: end the stream cleanly so the
+          // line iterator completes instead of crashing the process.
+          socket.destroy();
+        } else {
+          reject(
+            new IpcError(
+              `cannot connect to IPC socket at ${this.socketPath}: ${err.message}`,
+            ),
+          );
+        }
+      });
+      socket.once("connect", () => {
+        connected = true;
+        const rl = createInterface({ input: socket, crlfDelay: Infinity });
+        const lines = rl[Symbol.asyncIterator]();
+        void (async () => {
+          const hello = await lines.next();
+          if (hello.done || !hello.value.startsWith("hello")) {
+            rl.close();
+            socket.destroy();
+            reject(
+              new IpcError(
+                hello.done
+                  ? "IPC server closed connection before hello"
+                  : `unexpected IPC greeting: ${hello.value}`,
+              ),
+            );
+            return;
+          }
+          resolve({ socket, rl, lines });
+        })();
+      });
+    });
+  }
+}
+
+/** Resolve the {@link Subscriber} for `service` (`"shell"` for the panel).
+ *
+ * The socket is `<dir>/<service>.sock` (`shell` maps to `ipc.sock`) where
+ * `<dir>` is `$GLIMPSE_IPC_DIR`, else `$XDG_RUNTIME_DIR/glimpse`. No
+ * connection is made here. */
+export function ipc(service = "shell"): Subscriber {
+  return new Subscriber(socketPath(service));
+}
+
+function socketPath(service: string): string {
+  const override = process.env.GLIMPSE_IPC_DIR;
+  let dir: string;
+  if (override) {
+    dir = override;
+  } else {
+    const runtime = process.env.XDG_RUNTIME_DIR;
+    if (!runtime) {
+      throw new IpcError(
+        "neither GLIMPSE_IPC_DIR nor XDG_RUNTIME_DIR is set; " +
+          "cannot locate the Glimpse IPC socket",
+      );
+    }
+    dir = join(runtime, "glimpse");
+  }
+  return join(dir, service === "shell" ? "ipc.sock" : `${service}.sock`);
+}
+
+function close(conn: Conn): void {
+  conn.rl.close();
+  conn.socket.destroy();
+}
+
+// The wire protocol splits client lines on whitespace and never unescapes
+// the command name or a field key, so an `action`/key with whitespace would
+// forge extra tokens or whole client lines. Values are safe (escaped).
+function validateToken(label: string, token: string, forbidEq: boolean): void {
+  if (token.length === 0) {
+    throw new IpcError(`IPC ${label} must not be empty`);
+  }
+  if (/\s/.test(token)) {
+    throw new IpcError(`IPC ${label} "${token}" must not contain whitespace`);
+  }
+  if (forbidEq && token.includes("=")) {
+    throw new IpcError(`IPC param key "${token}" must not contain '='`);
+  }
+}
+
+function escape(s: string): string {
+  return s
+    .replaceAll("\\", "\\\\")
+    .replaceAll("\n", "\\n")
+    .replaceAll("\t", "\\t")
+    .replaceAll(" ", "\\s");
+}
+
+function unescape(s: string): string {
+  let out = "";
+  for (let i = 0; i < s.length; i++) {
+    if (s[i] !== "\\") {
+      out += s[i];
+      continue;
+    }
+    const next = s[++i];
+    if (next === "s") out += " ";
+    else if (next === "n") out += "\n";
+    else if (next === "t") out += "\t";
+    else if (next === "\\") out += "\\";
+    else if (next === undefined) out += "\\";
+    else out += "\\" + next;
+  }
+  return out;
+}
+
+function parseEvent(line: string): Event {
+  const tokens = line.split(/\s+/);
+  const name = tokens[0] ?? "";
+  let ts = 0;
+  const fields: Record<string, string> = {};
+  for (const token of tokens.slice(1)) {
+    const eq = token.indexOf("=");
+    if (eq < 0) continue;
+    const key = token.slice(0, eq);
+    const value = unescape(token.slice(eq + 1));
+    if (key === "ts" && /^\d+$/.test(value)) {
+      ts = Number(value);
+      continue;
+    }
+    fields[key] = value;
+  }
+  return { name, ts, fields };
+}
+
+function parseAck(line: string): Record<string, string> {
+  const tokens = line.split(/\s+/);
+  if (tokens[0] !== "ack") {
+    throw new IpcError(`expected an ack, got: ${line}`);
+  }
+  let ok = false;
+  const fields: Record<string, string> = {};
+  for (const token of tokens.slice(1)) {
+    const eq = token.indexOf("=");
+    if (eq < 0) continue;
+    const key = token.slice(0, eq);
+    const value = unescape(token.slice(eq + 1));
+    if (key === "ok") ok = value === "true";
+    else fields[key] = value;
+  }
+  if (!ok) {
+    throw new IpcError(fields.error ?? "command failed");
+  }
+  return fields;
+}