@metamask-previews/wallet-cli 0.0.0-preview-153490ebd → 0.0.0-preview-ed0047684

package/CHANGELOG.md

@@ -9,9 +9,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- Add a daemon transport layer: a JSON-RPC client and server over a Unix socket, plus daemon spawn/stop lifecycle helpers ([#9108](https://github.com/MetaMask/core/pull/9108))
 - Add SQLite-backed persistence for wallet controller state ([#9067](https://github.com/MetaMask/core/pull/9067))
-  - A `KeyValueStore` backed by `better-sqlite3` for synchronous reads and writes.
-  - `loadState` to rehydrate persist-flagged controller state from the store and `subscribeToChanges` to write persist-flagged controller state through to disk on every `stateChanged` event.
 - Initial package scaffold for `@metamask/wallet-cli`, an [oclif](https://oclif.io)-based `mm` CLI for `@metamask/wallet` ([#9065](https://github.com/MetaMask/core/pull/9065)).
 
+### Changed
+
+- Bump `@metamask/wallet` from `^3.0.0` to `^4.0.0` ([#9218](https://github.com/MetaMask/core/pull/9218))
+
 [Unreleased]: https://github.com/MetaMask/core/

package/dist/daemon/daemon-client.cjs

@@ -0,0 +1,140 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pingDaemon = exports.sendCommand = void 0;
+const utils_1 = require("@metamask/utils");
+const node_crypto_1 = require("node:crypto");
+const node_net_1 = require("node:net");
+const socket_line_1 = require("./socket-line.cjs");
+const utils_2 = require("./utils.cjs");
+const DEFAULT_TIMEOUT_MS = 30000;
+async function connectSocket(socketPath) {
+    return new Promise((resolve, reject) => {
+        const socket = (0, node_net_1.createConnection)(socketPath, () => {
+            socket.removeAllListeners('error');
+            resolve(socket);
+        });
+        socket.on('error', (error) => {
+            // A failed connect never reaches the caller, so destroy the socket here
+            // to avoid leaking its file descriptor.
+            socket.destroy();
+            reject(error);
+        });
+    });
+}
+/**
+ * Send a JSON-RPC request to the daemon over a Unix socket and return the
+ * response.
+ *
+ * Opens a connection, writes one JSON-RPC request line, reads one JSON-RPC
+ * response line, then closes the connection. Retries once after a short delay
+ * on transient connection errors (ECONNREFUSED, ECONNRESET). Verifies that the
+ * response `id` matches the outgoing request `id`.
+ *
+ * @param options - Command options.
+ * @param options.socketPath - The Unix socket path.
+ * @param options.method - The RPC method name.
+ * @param options.params - Optional method parameters.
+ * @param options.timeoutMs - Read timeout in milliseconds.
+ * @returns The parsed JSON-RPC response.
+ */
+async function sendCommand({ socketPath, method, params, timeoutMs, }) {
+    const id = (0, node_crypto_1.randomUUID)();
+    const request = {
+        jsonrpc: '2.0',
+        id,
+        method,
+        ...(params === undefined ? {} : { params }),
+    };
+    const effectiveTimeout = timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const attempt = async () => {
+        const socket = await connectSocket(socketPath);
+        try {
+            await (0, socket_line_1.writeLine)(socket, JSON.stringify(request));
+            const responseLine = await (0, socket_line_1.readLine)(socket, effectiveTimeout);
+            const parsed = JSON.parse(responseLine);
+            (0, utils_1.assertIsJsonRpcResponse)(parsed);
+            if (parsed.id !== id) {
+                throw new Error(`JSON-RPC response id ${JSON.stringify(parsed.id)} does not match request id ${JSON.stringify(id)}`);
+            }
+            return parsed;
+        }
+        finally {
+            socket.destroy();
+        }
+    };
+    try {
+        return await attempt();
+    }
+    catch (error) {
+        if (!(0, utils_2.isErrorWithCode)(error, 'ECONNREFUSED') &&
+            !(0, utils_2.isErrorWithCode)(error, 'ECONNRESET')) {
+            throw error;
+        }
+        await new Promise((resolve) => setTimeout(resolve, 100));
+        return attempt();
+    }
+}
+exports.sendCommand = sendCommand;
+/**
+ * Normalize an unknown throw into a real Error instance so that downstream
+ * consumers (which read `.message`) cannot crash on string/object throws.
+ *
+ * @param error - The caught value.
+ * @returns An Error mirroring the caught value.
+ */
+function toError(error) {
+    return error instanceof Error ? error : new Error(String(error));
+}
+/**
+ * Categorise an unreachable error by Node errno / message shape so callers can
+ * make decisions per failure mode rather than parsing message strings.
+ *
+ * @param error - The caught value.
+ * @returns A {@link PingUnreachableReason} label.
+ */
+function classifyUnreachable(error) {
+    if ((0, utils_2.isErrorWithCode)(error, 'ECONNREFUSED') ||
+        (0, utils_2.isErrorWithCode)(error, 'ECONNRESET')) {
+        return 'refused';
+    }
+    if ((0, utils_2.isErrorWithCode)(error, 'EACCES') || (0, utils_2.isErrorWithCode)(error, 'EPERM')) {
+        return 'permission';
+    }
+    if (error instanceof Error && error.message === 'Socket read timed out') {
+        return 'timeout';
+    }
+    if (error instanceof Error &&
+        (error.message.includes('JSON-RPC response id') ||
+            /Expected .* JSON-RPC/u.test(error.message) ||
+            error.name === 'SyntaxError')) {
+        return 'protocol';
+    }
+    return 'other';
+}
+/**
+ * Check whether the daemon is running by sending a lightweight `getStatus`
+ * RPC call. Distinguishes "no daemon present" (socket file missing) from
+ * "daemon present but unreachable" (socket file exists but the daemon is
+ * wedged, mid-shutdown, or owned by a different user).
+ *
+ * @param socketPath - The Unix socket path.
+ * @returns A {@link PingResult} describing the daemon's reachability.
+ */
+async function pingDaemon(socketPath) {
+    try {
+        await sendCommand({ socketPath, method: 'getStatus', timeoutMs: 3000 });
+        return { status: 'responsive' };
+    }
+    catch (error) {
+        if ((0, utils_2.isErrorWithCode)(error, 'ENOENT')) {
+            return { status: 'absent' };
+        }
+        return {
+            status: 'unreachable',
+            reason: classifyUnreachable(error),
+            error: toError(error),
+        };
+    }
+}
+exports.pingDaemon = pingDaemon;
+//# sourceMappingURL=daemon-client.cjs.map

package/dist/daemon/daemon-client.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"daemon-client.cjs","sourceRoot":"","sources":["../../src/daemon/daemon-client.ts"],"names":[],"mappings":"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","sourcesContent":["import type { JsonRpcParams, JsonRpcResponse } from '@metamask/utils';\nimport { assertIsJsonRpcResponse } from '@metamask/utils';\nimport { randomUUID } from 'node:crypto';\nimport { createConnection } from 'node:net';\nimport type { Socket } from 'node:net';\n\nimport { readLine, writeLine } from './socket-line';\nimport { isErrorWithCode } from './utils';\n\nconst DEFAULT_TIMEOUT_MS = 30_000;\n\n/**\n * Options for {@link sendCommand}.\n */\ntype SendCommandOptions = {\n  /** The Unix socket path. */\n  socketPath: string;\n  /** The RPC method name. */\n  method: string;\n  /** Optional method parameters (object or positional array). */\n  params?: JsonRpcParams | undefined;\n  /** Response read timeout in milliseconds (default: 30 000). */\n  timeoutMs?: number | undefined;\n};\n\nasync function connectSocket(socketPath: string): Promise<Socket> {\n  return new Promise((resolve, reject) => {\n    const socket = createConnection(socketPath, () => {\n      socket.removeAllListeners('error');\n      resolve(socket);\n    });\n    socket.on('error', (error) => {\n      // A failed connect never reaches the caller, so destroy the socket here\n      // to avoid leaking its file descriptor.\n      socket.destroy();\n      reject(error);\n    });\n  });\n}\n\n/**\n * Send a JSON-RPC request to the daemon over a Unix socket and return the\n * response.\n *\n * Opens a connection, writes one JSON-RPC request line, reads one JSON-RPC\n * response line, then closes the connection. Retries once after a short delay\n * on transient connection errors (ECONNREFUSED, ECONNRESET). Verifies that the\n * response `id` matches the outgoing request `id`.\n *\n * @param options - Command options.\n * @param options.socketPath - The Unix socket path.\n * @param options.method - The RPC method name.\n * @param options.params - Optional method parameters.\n * @param options.timeoutMs - Read timeout in milliseconds.\n * @returns The parsed JSON-RPC response.\n */\nexport async function sendCommand({\n  socketPath,\n  method,\n  params,\n  timeoutMs,\n}: SendCommandOptions): Promise<JsonRpcResponse> {\n  const id = randomUUID();\n  const request = {\n    jsonrpc: '2.0',\n    id,\n    method,\n    ...(params === undefined ? {} : { params }),\n  };\n\n  const effectiveTimeout = timeoutMs ?? DEFAULT_TIMEOUT_MS;\n\n  const attempt = async (): Promise<JsonRpcResponse> => {\n    const socket = await connectSocket(socketPath);\n    try {\n      await writeLine(socket, JSON.stringify(request));\n      const responseLine = await readLine(socket, effectiveTimeout);\n      const parsed: unknown = JSON.parse(responseLine);\n      assertIsJsonRpcResponse(parsed);\n      if (parsed.id !== id) {\n        throw new Error(\n          `JSON-RPC response id ${JSON.stringify(parsed.id)} does not match request id ${JSON.stringify(id)}`,\n        );\n      }\n      return parsed;\n    } finally {\n      socket.destroy();\n    }\n  };\n\n  try {\n    return await attempt();\n  } catch (error: unknown) {\n    if (\n      !isErrorWithCode(error, 'ECONNREFUSED') &&\n      !isErrorWithCode(error, 'ECONNRESET')\n    ) {\n      throw error;\n    }\n    await new Promise((resolve) => setTimeout(resolve, 100));\n    return attempt();\n  }\n}\n\n/**\n * Why an unreachable daemon cannot be queried.\n *\n * - `'refused'`: connection refused after retry (`ECONNREFUSED` / `ECONNRESET`).\n *   Typical of a daemon that has crashed or is mid-restart.\n * - `'timeout'`: the daemon accepted the connection but did not respond within\n *   the read timeout — most likely wedged on a long-running operation.\n * - `'permission'`: the socket exists but cannot be opened (`EACCES` / `EPERM`).\n *   The daemon almost certainly belongs to another user.\n * - `'protocol'`: the daemon responded but the response did not parse as a\n *   valid JSON-RPC response, or the response id did not match.\n * - `'other'`: anything else.\n */\nexport type PingUnreachableReason =\n  | 'refused'\n  | 'timeout'\n  | 'permission'\n  | 'protocol'\n  | 'other';\n\n/**\n * Outcome of a daemon health check.\n *\n * - `'responsive'`: the daemon answered a `getStatus` RPC.\n * - `'absent'`: the socket connect attempt failed with `ENOENT`, i.e. no\n *   socket file exists at the path. No daemon present.\n * - `'unreachable'`: any other non-success outcome. The daemon may still be\n *   alive but is not responding. Callers should not silently take over the\n *   slot or assume the daemon is dead. The `reason` field categorises the\n *   failure so callers can distinguish a wedged sibling daemon from a\n *   foreign-user daemon from a transient crash. User-initiated stop / purge\n *   flows may still escalate to signals against the recorded PID.\n */\nexport type PingResult =\n  | { status: 'responsive' }\n  | { status: 'absent' }\n  | { status: 'unreachable'; reason: PingUnreachableReason; error: Error };\n\n/**\n * Normalize an unknown throw into a real Error instance so that downstream\n * consumers (which read `.message`) cannot crash on string/object throws.\n *\n * @param error - The caught value.\n * @returns An Error mirroring the caught value.\n */\nfunction toError(error: unknown): Error {\n  return error instanceof Error ? error : new Error(String(error));\n}\n\n/**\n * Categorise an unreachable error by Node errno / message shape so callers can\n * make decisions per failure mode rather than parsing message strings.\n *\n * @param error - The caught value.\n * @returns A {@link PingUnreachableReason} label.\n */\nfunction classifyUnreachable(error: unknown): PingUnreachableReason {\n  if (\n    isErrorWithCode(error, 'ECONNREFUSED') ||\n    isErrorWithCode(error, 'ECONNRESET')\n  ) {\n    return 'refused';\n  }\n  if (isErrorWithCode(error, 'EACCES') || isErrorWithCode(error, 'EPERM')) {\n    return 'permission';\n  }\n  if (error instanceof Error && error.message === 'Socket read timed out') {\n    return 'timeout';\n  }\n  if (\n    error instanceof Error &&\n    (error.message.includes('JSON-RPC response id') ||\n      /Expected .* JSON-RPC/u.test(error.message) ||\n      error.name === 'SyntaxError')\n  ) {\n    return 'protocol';\n  }\n  return 'other';\n}\n\n/**\n * Check whether the daemon is running by sending a lightweight `getStatus`\n * RPC call. Distinguishes \"no daemon present\" (socket file missing) from\n * \"daemon present but unreachable\" (socket file exists but the daemon is\n * wedged, mid-shutdown, or owned by a different user).\n *\n * @param socketPath - The Unix socket path.\n * @returns A {@link PingResult} describing the daemon's reachability.\n */\nexport async function pingDaemon(socketPath: string): Promise<PingResult> {\n  try {\n    await sendCommand({ socketPath, method: 'getStatus', timeoutMs: 3_000 });\n    return { status: 'responsive' };\n  } catch (error: unknown) {\n    if (isErrorWithCode(error, 'ENOENT')) {\n      return { status: 'absent' };\n    }\n    return {\n      status: 'unreachable',\n      reason: classifyUnreachable(error),\n      error: toError(error),\n    };\n  }\n}\n"]}

package/dist/daemon/daemon-client.d.cts

@@ -0,0 +1,79 @@
+import type { JsonRpcParams, JsonRpcResponse } from "@metamask/utils";
+/**
+ * Options for {@link sendCommand}.
+ */
+type SendCommandOptions = {
+    /** The Unix socket path. */
+    socketPath: string;
+    /** The RPC method name. */
+    method: string;
+    /** Optional method parameters (object or positional array). */
+    params?: JsonRpcParams | undefined;
+    /** Response read timeout in milliseconds (default: 30 000). */
+    timeoutMs?: number | undefined;
+};
+/**
+ * Send a JSON-RPC request to the daemon over a Unix socket and return the
+ * response.
+ *
+ * Opens a connection, writes one JSON-RPC request line, reads one JSON-RPC
+ * response line, then closes the connection. Retries once after a short delay
+ * on transient connection errors (ECONNREFUSED, ECONNRESET). Verifies that the
+ * response `id` matches the outgoing request `id`.
+ *
+ * @param options - Command options.
+ * @param options.socketPath - The Unix socket path.
+ * @param options.method - The RPC method name.
+ * @param options.params - Optional method parameters.
+ * @param options.timeoutMs - Read timeout in milliseconds.
+ * @returns The parsed JSON-RPC response.
+ */
+export declare function sendCommand({ socketPath, method, params, timeoutMs, }: SendCommandOptions): Promise<JsonRpcResponse>;
+/**
+ * Why an unreachable daemon cannot be queried.
+ *
+ * - `'refused'`: connection refused after retry (`ECONNREFUSED` / `ECONNRESET`).
+ *   Typical of a daemon that has crashed or is mid-restart.
+ * - `'timeout'`: the daemon accepted the connection but did not respond within
+ *   the read timeout — most likely wedged on a long-running operation.
+ * - `'permission'`: the socket exists but cannot be opened (`EACCES` / `EPERM`).
+ *   The daemon almost certainly belongs to another user.
+ * - `'protocol'`: the daemon responded but the response did not parse as a
+ *   valid JSON-RPC response, or the response id did not match.
+ * - `'other'`: anything else.
+ */
+export type PingUnreachableReason = 'refused' | 'timeout' | 'permission' | 'protocol' | 'other';
+/**
+ * Outcome of a daemon health check.
+ *
+ * - `'responsive'`: the daemon answered a `getStatus` RPC.
+ * - `'absent'`: the socket connect attempt failed with `ENOENT`, i.e. no
+ *   socket file exists at the path. No daemon present.
+ * - `'unreachable'`: any other non-success outcome. The daemon may still be
+ *   alive but is not responding. Callers should not silently take over the
+ *   slot or assume the daemon is dead. The `reason` field categorises the
+ *   failure so callers can distinguish a wedged sibling daemon from a
+ *   foreign-user daemon from a transient crash. User-initiated stop / purge
+ *   flows may still escalate to signals against the recorded PID.
+ */
+export type PingResult = {
+    status: 'responsive';
+} | {
+    status: 'absent';
+} | {
+    status: 'unreachable';
+    reason: PingUnreachableReason;
+    error: Error;
+};
+/**
+ * Check whether the daemon is running by sending a lightweight `getStatus`
+ * RPC call. Distinguishes "no daemon present" (socket file missing) from
+ * "daemon present but unreachable" (socket file exists but the daemon is
+ * wedged, mid-shutdown, or owned by a different user).
+ *
+ * @param socketPath - The Unix socket path.
+ * @returns A {@link PingResult} describing the daemon's reachability.
+ */
+export declare function pingDaemon(socketPath: string): Promise<PingResult>;
+export {};
+//# sourceMappingURL=daemon-client.d.cts.map

package/dist/daemon/daemon-client.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"daemon-client.d.cts","sourceRoot":"","sources":["../../src/daemon/daemon-client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,wBAAwB;AAWtE;;GAEG;AACH,KAAK,kBAAkB,GAAG;IACxB,4BAA4B;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,2BAA2B;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,+DAA+D;IAC/D,MAAM,CAAC,EAAE,aAAa,GAAG,SAAS,CAAC;IACnC,+DAA+D;IAC/D,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAChC,CAAC;AAiBF;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,WAAW,CAAC,EAChC,UAAU,EACV,MAAM,EACN,MAAM,EACN,SAAS,GACV,EAAE,kBAAkB,GAAG,OAAO,CAAC,eAAe,CAAC,CAyC/C;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,qBAAqB,GAC7B,SAAS,GACT,SAAS,GACT,YAAY,GACZ,UAAU,GACV,OAAO,CAAC;AAEZ;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,UAAU,GAClB;IAAE,MAAM,EAAE,YAAY,CAAA;CAAE,GACxB;IAAE,MAAM,EAAE,QAAQ,CAAA;CAAE,GACpB;IAAE,MAAM,EAAE,aAAa,CAAC;IAAC,MAAM,EAAE,qBAAqB,CAAC;IAAC,KAAK,EAAE,KAAK,CAAA;CAAE,CAAC;AA4C3E;;;;;;;;GAQG;AACH,wBAAsB,UAAU,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAcxE"}

package/dist/daemon/daemon-client.d.mts

@@ -0,0 +1,79 @@
+import type { JsonRpcParams, JsonRpcResponse } from "@metamask/utils";
+/**
+ * Options for {@link sendCommand}.
+ */
+type SendCommandOptions = {
+    /** The Unix socket path. */
+    socketPath: string;
+    /** The RPC method name. */
+    method: string;
+    /** Optional method parameters (object or positional array). */
+    params?: JsonRpcParams | undefined;
+    /** Response read timeout in milliseconds (default: 30 000). */
+    timeoutMs?: number | undefined;
+};
+/**
+ * Send a JSON-RPC request to the daemon over a Unix socket and return the
+ * response.
+ *
+ * Opens a connection, writes one JSON-RPC request line, reads one JSON-RPC
+ * response line, then closes the connection. Retries once after a short delay
+ * on transient connection errors (ECONNREFUSED, ECONNRESET). Verifies that the
+ * response `id` matches the outgoing request `id`.
+ *
+ * @param options - Command options.
+ * @param options.socketPath - The Unix socket path.
+ * @param options.method - The RPC method name.
+ * @param options.params - Optional method parameters.
+ * @param options.timeoutMs - Read timeout in milliseconds.
+ * @returns The parsed JSON-RPC response.
+ */
+export declare function sendCommand({ socketPath, method, params, timeoutMs, }: SendCommandOptions): Promise<JsonRpcResponse>;
+/**
+ * Why an unreachable daemon cannot be queried.
+ *
+ * - `'refused'`: connection refused after retry (`ECONNREFUSED` / `ECONNRESET`).
+ *   Typical of a daemon that has crashed or is mid-restart.
+ * - `'timeout'`: the daemon accepted the connection but did not respond within
+ *   the read timeout — most likely wedged on a long-running operation.
+ * - `'permission'`: the socket exists but cannot be opened (`EACCES` / `EPERM`).
+ *   The daemon almost certainly belongs to another user.
+ * - `'protocol'`: the daemon responded but the response did not parse as a
+ *   valid JSON-RPC response, or the response id did not match.
+ * - `'other'`: anything else.
+ */
+export type PingUnreachableReason = 'refused' | 'timeout' | 'permission' | 'protocol' | 'other';
+/**
+ * Outcome of a daemon health check.
+ *
+ * - `'responsive'`: the daemon answered a `getStatus` RPC.
+ * - `'absent'`: the socket connect attempt failed with `ENOENT`, i.e. no
+ *   socket file exists at the path. No daemon present.
+ * - `'unreachable'`: any other non-success outcome. The daemon may still be
+ *   alive but is not responding. Callers should not silently take over the
+ *   slot or assume the daemon is dead. The `reason` field categorises the
+ *   failure so callers can distinguish a wedged sibling daemon from a
+ *   foreign-user daemon from a transient crash. User-initiated stop / purge
+ *   flows may still escalate to signals against the recorded PID.
+ */
+export type PingResult = {
+    status: 'responsive';
+} | {
+    status: 'absent';
+} | {
+    status: 'unreachable';
+    reason: PingUnreachableReason;
+    error: Error;
+};
+/**
+ * Check whether the daemon is running by sending a lightweight `getStatus`
+ * RPC call. Distinguishes "no daemon present" (socket file missing) from
+ * "daemon present but unreachable" (socket file exists but the daemon is
+ * wedged, mid-shutdown, or owned by a different user).
+ *
+ * @param socketPath - The Unix socket path.
+ * @returns A {@link PingResult} describing the daemon's reachability.
+ */
+export declare function pingDaemon(socketPath: string): Promise<PingResult>;
+export {};
+//# sourceMappingURL=daemon-client.d.mts.map

package/dist/daemon/daemon-client.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"daemon-client.d.mts","sourceRoot":"","sources":["../../src/daemon/daemon-client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,wBAAwB;AAWtE;;GAEG;AACH,KAAK,kBAAkB,GAAG;IACxB,4BAA4B;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,2BAA2B;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,+DAA+D;IAC/D,MAAM,CAAC,EAAE,aAAa,GAAG,SAAS,CAAC;IACnC,+DAA+D;IAC/D,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAChC,CAAC;AAiBF;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,WAAW,CAAC,EAChC,UAAU,EACV,MAAM,EACN,MAAM,EACN,SAAS,GACV,EAAE,kBAAkB,GAAG,OAAO,CAAC,eAAe,CAAC,CAyC/C;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,qBAAqB,GAC7B,SAAS,GACT,SAAS,GACT,YAAY,GACZ,UAAU,GACV,OAAO,CAAC;AAEZ;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,UAAU,GAClB;IAAE,MAAM,EAAE,YAAY,CAAA;CAAE,GACxB;IAAE,MAAM,EAAE,QAAQ,CAAA;CAAE,GACpB;IAAE,MAAM,EAAE,aAAa,CAAC;IAAC,MAAM,EAAE,qBAAqB,CAAC;IAAC,KAAK,EAAE,KAAK,CAAA;CAAE,CAAC;AA4C3E;;;;;;;;GAQG;AACH,wBAAsB,UAAU,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAcxE"}

package/dist/daemon/daemon-client.mjs

@@ -0,0 +1,135 @@
+import { assertIsJsonRpcResponse } from "@metamask/utils";
+import { randomUUID } from "node:crypto";
+import { createConnection } from "node:net";
+import { readLine, writeLine } from "./socket-line.mjs";
+import { isErrorWithCode } from "./utils.mjs";
+const DEFAULT_TIMEOUT_MS = 30000;
+async function connectSocket(socketPath) {
+    return new Promise((resolve, reject) => {
+        const socket = createConnection(socketPath, () => {
+            socket.removeAllListeners('error');
+            resolve(socket);
+        });
+        socket.on('error', (error) => {
+            // A failed connect never reaches the caller, so destroy the socket here
+            // to avoid leaking its file descriptor.
+            socket.destroy();
+            reject(error);
+        });
+    });
+}
+/**
+ * Send a JSON-RPC request to the daemon over a Unix socket and return the
+ * response.
+ *
+ * Opens a connection, writes one JSON-RPC request line, reads one JSON-RPC
+ * response line, then closes the connection. Retries once after a short delay
+ * on transient connection errors (ECONNREFUSED, ECONNRESET). Verifies that the
+ * response `id` matches the outgoing request `id`.
+ *
+ * @param options - Command options.
+ * @param options.socketPath - The Unix socket path.
+ * @param options.method - The RPC method name.
+ * @param options.params - Optional method parameters.
+ * @param options.timeoutMs - Read timeout in milliseconds.
+ * @returns The parsed JSON-RPC response.
+ */
+export async function sendCommand({ socketPath, method, params, timeoutMs, }) {
+    const id = randomUUID();
+    const request = {
+        jsonrpc: '2.0',
+        id,
+        method,
+        ...(params === undefined ? {} : { params }),
+    };
+    const effectiveTimeout = timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const attempt = async () => {
+        const socket = await connectSocket(socketPath);
+        try {
+            await writeLine(socket, JSON.stringify(request));
+            const responseLine = await readLine(socket, effectiveTimeout);
+            const parsed = JSON.parse(responseLine);
+            assertIsJsonRpcResponse(parsed);
+            if (parsed.id !== id) {
+                throw new Error(`JSON-RPC response id ${JSON.stringify(parsed.id)} does not match request id ${JSON.stringify(id)}`);
+            }
+            return parsed;
+        }
+        finally {
+            socket.destroy();
+        }
+    };
+    try {
+        return await attempt();
+    }
+    catch (error) {
+        if (!isErrorWithCode(error, 'ECONNREFUSED') &&
+            !isErrorWithCode(error, 'ECONNRESET')) {
+            throw error;
+        }
+        await new Promise((resolve) => setTimeout(resolve, 100));
+        return attempt();
+    }
+}
+/**
+ * Normalize an unknown throw into a real Error instance so that downstream
+ * consumers (which read `.message`) cannot crash on string/object throws.
+ *
+ * @param error - The caught value.
+ * @returns An Error mirroring the caught value.
+ */
+function toError(error) {
+    return error instanceof Error ? error : new Error(String(error));
+}
+/**
+ * Categorise an unreachable error by Node errno / message shape so callers can
+ * make decisions per failure mode rather than parsing message strings.
+ *
+ * @param error - The caught value.
+ * @returns A {@link PingUnreachableReason} label.
+ */
+function classifyUnreachable(error) {
+    if (isErrorWithCode(error, 'ECONNREFUSED') ||
+        isErrorWithCode(error, 'ECONNRESET')) {
+        return 'refused';
+    }
+    if (isErrorWithCode(error, 'EACCES') || isErrorWithCode(error, 'EPERM')) {
+        return 'permission';
+    }
+    if (error instanceof Error && error.message === 'Socket read timed out') {
+        return 'timeout';
+    }
+    if (error instanceof Error &&
+        (error.message.includes('JSON-RPC response id') ||
+            /Expected .* JSON-RPC/u.test(error.message) ||
+            error.name === 'SyntaxError')) {
+        return 'protocol';
+    }
+    return 'other';
+}
+/**
+ * Check whether the daemon is running by sending a lightweight `getStatus`
+ * RPC call. Distinguishes "no daemon present" (socket file missing) from
+ * "daemon present but unreachable" (socket file exists but the daemon is
+ * wedged, mid-shutdown, or owned by a different user).
+ *
+ * @param socketPath - The Unix socket path.
+ * @returns A {@link PingResult} describing the daemon's reachability.
+ */
+export async function pingDaemon(socketPath) {
+    try {
+        await sendCommand({ socketPath, method: 'getStatus', timeoutMs: 3000 });
+        return { status: 'responsive' };
+    }
+    catch (error) {
+        if (isErrorWithCode(error, 'ENOENT')) {
+            return { status: 'absent' };
+        }
+        return {
+            status: 'unreachable',
+            reason: classifyUnreachable(error),
+            error: toError(error),
+        };
+    }
+}
+//# sourceMappingURL=daemon-client.mjs.map

package/dist/daemon/daemon-client.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"daemon-client.mjs","sourceRoot":"","sources":["../../src/daemon/daemon-client.ts"],"names":[],"mappings":"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","sourcesContent":["import type { JsonRpcParams, JsonRpcResponse } from '@metamask/utils';\nimport { assertIsJsonRpcResponse } from '@metamask/utils';\nimport { randomUUID } from 'node:crypto';\nimport { createConnection } from 'node:net';\nimport type { Socket } from 'node:net';\n\nimport { readLine, writeLine } from './socket-line';\nimport { isErrorWithCode } from './utils';\n\nconst DEFAULT_TIMEOUT_MS = 30_000;\n\n/**\n * Options for {@link sendCommand}.\n */\ntype SendCommandOptions = {\n  /** The Unix socket path. */\n  socketPath: string;\n  /** The RPC method name. */\n  method: string;\n  /** Optional method parameters (object or positional array). */\n  params?: JsonRpcParams | undefined;\n  /** Response read timeout in milliseconds (default: 30 000). */\n  timeoutMs?: number | undefined;\n};\n\nasync function connectSocket(socketPath: string): Promise<Socket> {\n  return new Promise((resolve, reject) => {\n    const socket = createConnection(socketPath, () => {\n      socket.removeAllListeners('error');\n      resolve(socket);\n    });\n    socket.on('error', (error) => {\n      // A failed connect never reaches the caller, so destroy the socket here\n      // to avoid leaking its file descriptor.\n      socket.destroy();\n      reject(error);\n    });\n  });\n}\n\n/**\n * Send a JSON-RPC request to the daemon over a Unix socket and return the\n * response.\n *\n * Opens a connection, writes one JSON-RPC request line, reads one JSON-RPC\n * response line, then closes the connection. Retries once after a short delay\n * on transient connection errors (ECONNREFUSED, ECONNRESET). Verifies that the\n * response `id` matches the outgoing request `id`.\n *\n * @param options - Command options.\n * @param options.socketPath - The Unix socket path.\n * @param options.method - The RPC method name.\n * @param options.params - Optional method parameters.\n * @param options.timeoutMs - Read timeout in milliseconds.\n * @returns The parsed JSON-RPC response.\n */\nexport async function sendCommand({\n  socketPath,\n  method,\n  params,\n  timeoutMs,\n}: SendCommandOptions): Promise<JsonRpcResponse> {\n  const id = randomUUID();\n  const request = {\n    jsonrpc: '2.0',\n    id,\n    method,\n    ...(params === undefined ? {} : { params }),\n  };\n\n  const effectiveTimeout = timeoutMs ?? DEFAULT_TIMEOUT_MS;\n\n  const attempt = async (): Promise<JsonRpcResponse> => {\n    const socket = await connectSocket(socketPath);\n    try {\n      await writeLine(socket, JSON.stringify(request));\n      const responseLine = await readLine(socket, effectiveTimeout);\n      const parsed: unknown = JSON.parse(responseLine);\n      assertIsJsonRpcResponse(parsed);\n      if (parsed.id !== id) {\n        throw new Error(\n          `JSON-RPC response id ${JSON.stringify(parsed.id)} does not match request id ${JSON.stringify(id)}`,\n        );\n      }\n      return parsed;\n    } finally {\n      socket.destroy();\n    }\n  };\n\n  try {\n    return await attempt();\n  } catch (error: unknown) {\n    if (\n      !isErrorWithCode(error, 'ECONNREFUSED') &&\n      !isErrorWithCode(error, 'ECONNRESET')\n    ) {\n      throw error;\n    }\n    await new Promise((resolve) => setTimeout(resolve, 100));\n    return attempt();\n  }\n}\n\n/**\n * Why an unreachable daemon cannot be queried.\n *\n * - `'refused'`: connection refused after retry (`ECONNREFUSED` / `ECONNRESET`).\n *   Typical of a daemon that has crashed or is mid-restart.\n * - `'timeout'`: the daemon accepted the connection but did not respond within\n *   the read timeout — most likely wedged on a long-running operation.\n * - `'permission'`: the socket exists but cannot be opened (`EACCES` / `EPERM`).\n *   The daemon almost certainly belongs to another user.\n * - `'protocol'`: the daemon responded but the response did not parse as a\n *   valid JSON-RPC response, or the response id did not match.\n * - `'other'`: anything else.\n */\nexport type PingUnreachableReason =\n  | 'refused'\n  | 'timeout'\n  | 'permission'\n  | 'protocol'\n  | 'other';\n\n/**\n * Outcome of a daemon health check.\n *\n * - `'responsive'`: the daemon answered a `getStatus` RPC.\n * - `'absent'`: the socket connect attempt failed with `ENOENT`, i.e. no\n *   socket file exists at the path. No daemon present.\n * - `'unreachable'`: any other non-success outcome. The daemon may still be\n *   alive but is not responding. Callers should not silently take over the\n *   slot or assume the daemon is dead. The `reason` field categorises the\n *   failure so callers can distinguish a wedged sibling daemon from a\n *   foreign-user daemon from a transient crash. User-initiated stop / purge\n *   flows may still escalate to signals against the recorded PID.\n */\nexport type PingResult =\n  | { status: 'responsive' }\n  | { status: 'absent' }\n  | { status: 'unreachable'; reason: PingUnreachableReason; error: Error };\n\n/**\n * Normalize an unknown throw into a real Error instance so that downstream\n * consumers (which read `.message`) cannot crash on string/object throws.\n *\n * @param error - The caught value.\n * @returns An Error mirroring the caught value.\n */\nfunction toError(error: unknown): Error {\n  return error instanceof Error ? error : new Error(String(error));\n}\n\n/**\n * Categorise an unreachable error by Node errno / message shape so callers can\n * make decisions per failure mode rather than parsing message strings.\n *\n * @param error - The caught value.\n * @returns A {@link PingUnreachableReason} label.\n */\nfunction classifyUnreachable(error: unknown): PingUnreachableReason {\n  if (\n    isErrorWithCode(error, 'ECONNREFUSED') ||\n    isErrorWithCode(error, 'ECONNRESET')\n  ) {\n    return 'refused';\n  }\n  if (isErrorWithCode(error, 'EACCES') || isErrorWithCode(error, 'EPERM')) {\n    return 'permission';\n  }\n  if (error instanceof Error && error.message === 'Socket read timed out') {\n    return 'timeout';\n  }\n  if (\n    error instanceof Error &&\n    (error.message.includes('JSON-RPC response id') ||\n      /Expected .* JSON-RPC/u.test(error.message) ||\n      error.name === 'SyntaxError')\n  ) {\n    return 'protocol';\n  }\n  return 'other';\n}\n\n/**\n * Check whether the daemon is running by sending a lightweight `getStatus`\n * RPC call. Distinguishes \"no daemon present\" (socket file missing) from\n * \"daemon present but unreachable\" (socket file exists but the daemon is\n * wedged, mid-shutdown, or owned by a different user).\n *\n * @param socketPath - The Unix socket path.\n * @returns A {@link PingResult} describing the daemon's reachability.\n */\nexport async function pingDaemon(socketPath: string): Promise<PingResult> {\n  try {\n    await sendCommand({ socketPath, method: 'getStatus', timeoutMs: 3_000 });\n    return { status: 'responsive' };\n  } catch (error: unknown) {\n    if (isErrorWithCode(error, 'ENOENT')) {\n      return { status: 'absent' };\n    }\n    return {\n      status: 'unreachable',\n      reason: classifyUnreachable(error),\n      error: toError(error),\n    };\n  }\n}\n"]}

package/dist/daemon/daemon-spawn.cjs

@@ -0,0 +1,106 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ensureDaemon = void 0;
+const node_child_process_1 = require("node:child_process");
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const daemon_client_1 = require("./daemon-client.cjs");
+const paths_1 = require("./paths.cjs");
+const POLL_INTERVAL_MS = 100;
+const MAX_POLLS = 300; // 30 seconds
+/**
+ * Ensure the daemon is running. If a responsive daemon already exists, return
+ * `'already-running'` (caller decides how to surface that). Otherwise spawn
+ * one as a detached process and wait until the socket becomes responsive.
+ *
+ * Refuses to spawn when pinging the existing socket fails with anything other
+ * than `ENOENT` (wedged or foreign daemon) — taking over could orphan the
+ * existing process and corrupt its PID file.
+ *
+ * @param config - Spawn configuration.
+ * @returns The state of the daemon and the socket path it's listening on.
+ */
+async function ensureDaemon(config) {
+    const { socketPath } = (0, paths_1.getDaemonPaths)(config.dataDir);
+    const initialPing = await (0, daemon_client_1.pingDaemon)(socketPath);
+    if (initialPing.status === 'responsive') {
+        return { state: 'already-running', socketPath };
+    }
+    if (initialPing.status === 'unreachable') {
+        if (initialPing.reason === 'permission') {
+            throw new Error(`Refusing to start: the socket at ${socketPath} is owned by another user. ` +
+                `Choose a different data directory (MM_DAEMON_DATA_DIR) or remove the socket manually. ` +
+                `(${initialPing.error.message})`);
+        }
+        throw new Error(`Refusing to start: a daemon socket already exists at ${socketPath} but is unresponsive. ` +
+            `Run \`mm daemon stop\` (or \`mm daemon purge\`) before starting a new daemon. ` +
+            `(${initialPing.error.message})`);
+    }
+    process.stderr.write('Starting daemon...\n');
+    const { entryPath, args } = resolveEntryPoint(config.packageRoot);
+    const child = (0, node_child_process_1.spawn)(process.execPath, [...args, entryPath], {
+        detached: true,
+        stdio: 'ignore',
+        env: {
+            ...process.env,
+            MM_DAEMON_DATA_DIR: config.dataDir,
+            MM_DAEMON_SOCKET_PATH: socketPath,
+            INFURA_PROJECT_ID: config.infuraProjectId,
+            MM_WALLET_PASSWORD: config.password,
+            MM_WALLET_SRP: config.srp,
+        },
+    });
+    const exitInfo = { value: null };
+    // A failed spawn (bad interpreter, EACCES, ENOENT) emits 'error' and may
+    // never emit 'exit'. Capture it so the readiness loop can surface the real
+    // cause immediately instead of hanging for the full timeout.
+    const spawnError = { value: null };
+    child.on('error', (error) => {
+        process.stderr.write(`Failed to spawn daemon process: ${String(error)}\n`);
+        spawnError.value = error;
+    });
+    child.on('exit', (code, signal) => {
+        exitInfo.value = { code, signal };
+    });
+    child.unref();
+    for (let i = 0; i < MAX_POLLS; i++) {
+        await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL_MS));
+        if (spawnError.value !== null) {
+            throw new Error(`Failed to spawn daemon process: ${spawnError.value.message}. ` +
+                `Check the daemon log at ${(0, paths_1.getDaemonPaths)(config.dataDir).logPath}.`);
+        }
+        if (exitInfo.value !== null) {
+            const { code, signal } = exitInfo.value;
+            throw new Error(`Daemon process exited during startup (code=${String(code)}, signal=${String(signal)}). ` +
+                `Check the daemon log at ${(0, paths_1.getDaemonPaths)(config.dataDir).logPath}.`);
+        }
+        const ping = await (0, daemon_client_1.pingDaemon)(socketPath);
+        if (ping.status === 'responsive') {
+            process.stderr.write('Daemon ready.\n');
+            return { state: 'started', socketPath };
+        }
+    }
+    throw new Error(`Daemon did not start within ${(MAX_POLLS * POLL_INTERVAL_MS) / 1000}s`);
+}
+exports.ensureDaemon = ensureDaemon;
+/**
+ * Resolve the daemon entry point path and any extra Node.js args needed.
+ *
+ * In production, uses the compiled dist output. In development, uses tsx
+ * to run TypeScript source directly.
+ *
+ * @param packageRoot - The root directory of the wallet-cli package.
+ * @returns The entry path and any extra node args.
+ */
+function resolveEntryPoint(packageRoot) {
+    const distEntry = (0, node_path_1.join)(packageRoot, 'dist', 'daemon', 'daemon-entry.mjs');
+    if ((0, node_fs_1.existsSync)(distEntry)) {
+        return { entryPath: distEntry, args: [] };
+    }
+    const srcEntry = (0, node_path_1.join)(packageRoot, 'src', 'daemon', 'daemon-entry.ts');
+    return {
+        entryPath: srcEntry,
+        args: ['--import', 'tsx'],
+    };
+}
+//# sourceMappingURL=daemon-spawn.cjs.map

package/dist/daemon/daemon-spawn.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"daemon-spawn.cjs","sourceRoot":"","sources":["../../src/daemon/daemon-spawn.ts"],"names":[],"mappings":"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","sourcesContent":["import { spawn } from 'node:child_process';\nimport { existsSync } from 'node:fs';\nimport { join } from 'node:path';\n\nimport { pingDaemon } from './daemon-client';\nimport { getDaemonPaths } from './paths';\nimport type { DaemonSpawnConfig } from './types';\n\nconst POLL_INTERVAL_MS = 100;\nconst MAX_POLLS = 300; // 30 seconds\n\n/**\n * Outcome of {@link ensureDaemon}.\n *\n * - `'already-running'`: a responsive daemon was found at the configured\n *   socket path. The supplied flags (`infuraProjectId`, `password`, `srp`)\n *   were NOT applied to that daemon; the caller should surface this so a\n *   user who is trying to change them isn't silently ignored.\n * - `'started'`: a new daemon was spawned and is now responsive.\n */\nexport type EnsureDaemonResult = {\n  state: 'already-running' | 'started';\n  socketPath: string;\n};\n\n/**\n * Ensure the daemon is running. If a responsive daemon already exists, return\n * `'already-running'` (caller decides how to surface that). Otherwise spawn\n * one as a detached process and wait until the socket becomes responsive.\n *\n * Refuses to spawn when pinging the existing socket fails with anything other\n * than `ENOENT` (wedged or foreign daemon) — taking over could orphan the\n * existing process and corrupt its PID file.\n *\n * @param config - Spawn configuration.\n * @returns The state of the daemon and the socket path it's listening on.\n */\nexport async function ensureDaemon(\n  config: DaemonSpawnConfig,\n): Promise<EnsureDaemonResult> {\n  const { socketPath } = getDaemonPaths(config.dataDir);\n\n  const initialPing = await pingDaemon(socketPath);\n  if (initialPing.status === 'responsive') {\n    return { state: 'already-running', socketPath };\n  }\n  if (initialPing.status === 'unreachable') {\n    if (initialPing.reason === 'permission') {\n      throw new Error(\n        `Refusing to start: the socket at ${socketPath} is owned by another user. ` +\n          `Choose a different data directory (MM_DAEMON_DATA_DIR) or remove the socket manually. ` +\n          `(${initialPing.error.message})`,\n      );\n    }\n    throw new Error(\n      `Refusing to start: a daemon socket already exists at ${socketPath} but is unresponsive. ` +\n        `Run \\`mm daemon stop\\` (or \\`mm daemon purge\\`) before starting a new daemon. ` +\n        `(${initialPing.error.message})`,\n    );\n  }\n\n  process.stderr.write('Starting daemon...\\n');\n\n  const { entryPath, args } = resolveEntryPoint(config.packageRoot);\n\n  const child = spawn(process.execPath, [...args, entryPath], {\n    detached: true,\n    stdio: 'ignore',\n    env: {\n      ...process.env,\n      MM_DAEMON_DATA_DIR: config.dataDir,\n      MM_DAEMON_SOCKET_PATH: socketPath,\n      INFURA_PROJECT_ID: config.infuraProjectId,\n      MM_WALLET_PASSWORD: config.password,\n      MM_WALLET_SRP: config.srp,\n    },\n  });\n\n  type ExitInfo = { code: number | null; signal: NodeJS.Signals | null };\n  const exitInfo: { value: ExitInfo | null } = { value: null };\n  // A failed spawn (bad interpreter, EACCES, ENOENT) emits 'error' and may\n  // never emit 'exit'. Capture it so the readiness loop can surface the real\n  // cause immediately instead of hanging for the full timeout.\n  const spawnError: { value: Error | null } = { value: null };\n\n  child.on('error', (error: Error) => {\n    process.stderr.write(`Failed to spawn daemon process: ${String(error)}\\n`);\n    spawnError.value = error;\n  });\n  child.on('exit', (code, signal) => {\n    exitInfo.value = { code, signal };\n  });\n  child.unref();\n\n  for (let i = 0; i < MAX_POLLS; i++) {\n    await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL_MS));\n    if (spawnError.value !== null) {\n      throw new Error(\n        `Failed to spawn daemon process: ${spawnError.value.message}. ` +\n          `Check the daemon log at ${getDaemonPaths(config.dataDir).logPath}.`,\n      );\n    }\n    if (exitInfo.value !== null) {\n      const { code, signal } = exitInfo.value;\n      throw new Error(\n        `Daemon process exited during startup (code=${String(code)}, signal=${String(signal)}). ` +\n          `Check the daemon log at ${getDaemonPaths(config.dataDir).logPath}.`,\n      );\n    }\n    const ping = await pingDaemon(socketPath);\n    if (ping.status === 'responsive') {\n      process.stderr.write('Daemon ready.\\n');\n      return { state: 'started', socketPath };\n    }\n  }\n\n  throw new Error(\n    `Daemon did not start within ${(MAX_POLLS * POLL_INTERVAL_MS) / 1000}s`,\n  );\n}\n\n/**\n * Resolve the daemon entry point path and any extra Node.js args needed.\n *\n * In production, uses the compiled dist output. In development, uses tsx\n * to run TypeScript source directly.\n *\n * @param packageRoot - The root directory of the wallet-cli package.\n * @returns The entry path and any extra node args.\n */\nfunction resolveEntryPoint(packageRoot: string): {\n  entryPath: string;\n  args: string[];\n} {\n  const distEntry = join(packageRoot, 'dist', 'daemon', 'daemon-entry.mjs');\n  if (existsSync(distEntry)) {\n    return { entryPath: distEntry, args: [] };\n  }\n\n  const srcEntry = join(packageRoot, 'src', 'daemon', 'daemon-entry.ts');\n  return {\n    entryPath: srcEntry,\n    args: ['--import', 'tsx'],\n  };\n}\n"]}