feat(cli,nodejs): add daemon process with ocap daemon CLI

eslint.config.mjs

@@ -256,6 +256,7 @@ const config = createConfig([
     files: [
       '**/vite.config.ts',
       '**/vitest.config.ts',
+      'packages/cli/**/*',
       'packages/extension/**/*',
       'packages/nodejs/**/*-worker.ts',
       'packages/nodejs/test/workers/**/*',

package.json

@@ -113,7 +113,6 @@
     "allowScripts": {
       "$root$": true,
       "@ocap/cli>@metamask/logger>@metamask/streams": true,
-      "@ocap/cli>@libp2p/webrtc>@ipshipyard/node-datachannel": false,
       "@lavamoat/preinstall-always-fail": false,
       "eslint-import-resolver-typescript>unrs-resolver": false,
       "eslint-plugin-import-x>unrs-resolver": false,
@@ -124,7 +123,9 @@
       "vitest>@vitest/browser>webdriverio>@wdio/utils>edgedriver": false,
       "vitest>@vitest/browser>webdriverio>@wdio/utils>geckodriver": false,
       "vitest>@vitest/mocker>msw": false,
-      "@ocap/cli>@metamask/kernel-shims>@libp2p/webrtc>@ipshipyard/node-datachannel": false
+      "@ocap/cli>@ocap/nodejs>@libp2p/webrtc>@ipshipyard/node-datachannel": false,
+      "@ocap/cli>@ocap/nodejs>@metamask/kernel-store>better-sqlite3": false,
+      "@ocap/cli>@ocap/nodejs>@metamask/streams": false
     }
   },
   "resolutions": {

packages/cli/README.md

@@ -24,6 +24,33 @@ Bundle all `.js` files in the target dir, watch for changes to `.js` files and r
 
 Starts a libp2p relay.
 
+### `ocap daemon start`
+
+Start the daemon or confirm it is already running.
+
+### `ocap daemon stop`
+
+Gracefully stop the daemon.
+
+### `ocap daemon purge --force`
+
+Stop the daemon and delete all state.
+
+### `ocap daemon exec [method] [params-json]`
+
+Send an RPC method call to the daemon. Defaults to `getStatus` when `method` is omitted.
+
+## Known Limitations
+
+The daemon is a prototype. The following limitations apply:
+
+1. **`executeDBQuery` accepts arbitrary SQL** — any CLI user can execute unrestricted SQL against the kernel database. For production, this should be removed or restricted to read-only queries.
+2. **No socket permission enforcement** — the Unix socket is created with default permissions. Any local user can connect and issue commands. For production, socket permissions should be restricted to `0600`.
+3. **No daemon spawn concurrency protection** — if two CLI invocations run simultaneously and neither finds a running daemon, both may attempt to spawn one. A lockfile mechanism would prevent this.
+4. **No request size limits** — the RPC server buffers incoming data without a size cap. A malicious client could exhaust daemon memory.
+5. **No log rotation** — `daemon.log` grows without bound. Production use should add log rotation.
+6. **PID file is vulnerable to PID reuse** — if the daemon crashes without cleaning up `daemon.pid` and the OS reassigns that PID to an unrelated process, `stopDaemon` may signal the wrong process. A lockfile (`flock`) mechanism would eliminate this risk (and also solve limitation #3).
+
 ## Contributing
 
 This package is part of a monorepo. Instructions for contributing can be found in the [monorepo README](https://github.com/MetaMask/ocap-kernel#readme).

packages/cli/package.json

@@ -34,26 +34,16 @@
     "test:dev:quiet": "yarn test:dev --reporter @ocap/repo-tools/vitest-reporters/silent"
   },
   "dependencies": {
-    "@chainsafe/libp2p-noise": "^16.1.3",
-    "@chainsafe/libp2p-yamux": "patch:@chainsafe/libp2p-yamux@npm%3A7.0.4#~/.yarn/patches/@chainsafe-libp2p-yamux-npm-7.0.4-284c2f6812.patch",
     "@endo/promise-kit": "^1.1.13",
-    "@libp2p/autonat": "2.0.38",
-    "@libp2p/circuit-relay-v2": "3.2.24",
-    "@libp2p/crypto": "5.1.8",
-    "@libp2p/identify": "3.0.39",
-    "@libp2p/interface": "2.11.0",
-    "@libp2p/ping": "2.0.37",
-    "@libp2p/tcp": "10.1.19",
-    "@libp2p/websockets": "9.2.19",
     "@metamask/kernel-shims": "workspace:^",
     "@metamask/kernel-utils": "workspace:^",
     "@metamask/logger": "workspace:^",
     "@metamask/utils": "^11.9.0",
+    "@ocap/nodejs": "workspace:^",
     "@ocap/repo-tools": "workspace:^",
     "@types/node": "^22.13.1",
     "chokidar": "^4.0.1",
     "glob": "^11.0.0",
-    "libp2p": "2.10.0",
     "serve-handler": "^6.1.6",
     "vite": "^7.3.0",
     "yargs": "^17.7.2"
@@ -95,7 +85,6 @@
     "node": ">=22"
   },
   "exports": {
-    "./package.json": "./package.json",
-    "./relay": "./dist/relay.mjs"
+    "./package.json": "./package.json"
   }
 }

packages/cli/src/app.ts

@@ -1,16 +1,24 @@
 import '@metamask/kernel-shims/endoify-node';
+import { startRelay } from '@metamask/kernel-utils/libp2p';
 import { Logger } from '@metamask/logger';
 import type { LogEntry } from '@metamask/logger';
 import path from 'node:path';
 import yargs from 'yargs';
 import { hideBin } from 'yargs/helpers';
 
 import { bundleSource } from './commands/bundle.ts';
+import { getSocketPath } from './commands/daemon-client.ts';
+import { ensureDaemon } from './commands/daemon-spawn.ts';
+import {
+  handleDaemonBegone,
+  handleDaemonExec,
+  handleDaemonStart,
+  stopDaemon,
+} from './commands/daemon.ts';
 import { getServer } from './commands/serve.ts';
 import { watchDir } from './commands/watch.ts';
 import { defaultConfig } from './config.ts';
 import type { Config } from './config.ts';
-import { startRelay } from './relay.ts';
 import { withTimeout } from './utils.ts';
 
 /**
@@ -173,6 +181,108 @@ const yargsInstance = yargs(hideBin(process.argv))
     async () => {
       await startRelay(logger);
     },
+  )
+  .command(
+    'daemon',
+    'Manage the OCAP daemon process',
+    (_yargs) => {
+      const socketPath = getSocketPath();
+
+      return _yargs
+        .command(
+          'start',
+          'Start the daemon (or confirm it is running)',
+          (_y) => _y,
+          async () => {
+            await handleDaemonStart(socketPath);
+          },
+        )
+        .command(
+          'stop',
+          'Stop the daemon',
+          (_y) => _y,
+          async () => {
+            const stopped = await stopDaemon(socketPath);
+            if (!stopped) {
+              process.exitCode = 1;
+            }
+          },
+        )
+        .command(
+          ['purge', 'begone'],
+          'Stop the daemon and delete all state',
+          (_y) =>
+            _y.option('force', {
+              describe: 'Confirm state deletion',
+              type: 'boolean',
+              demandOption: true,
+            }),
+          async (args) => {
+            if (!args.force) {
+              process.stderr.write(
+                'Usage: ocap daemon purge --force\n' +
+                  'This will delete all OCAP daemon state.\n',
+              );
+              process.exitCode = 1;
+              return;
+            }
+            await handleDaemonBegone(socketPath);
+          },
+        )
+        .command(
+          'exec [method] [params-json]',
+          'Send an RPC method call to the daemon',
+          (_y) =>
+            _y
+              .positional('method', {
+                describe: 'RPC method name (defaults to getStatus)',
+                type: 'string',
+              })
+              .positional('params-json', {
+                describe: 'JSON-encoded method parameters',
+                type: 'string',
+              })
+              .example('$0 daemon exec', 'Get daemon status')
+              .example(
+                '$0 daemon exec getStatus',
+                'Get daemon status (explicit)',
+              )
+              .example(
+                '$0 daemon exec pingVat \'{"vatId":"v1"}\'',
+                'Ping a vat',
+              )
+              .example(
+                '$0 daemon exec executeDBQuery \'{"sql":"SELECT * FROM kv LIMIT 5"}\'',
+                'Run a SQL query',
+              )
+              .example(
+                '$0 daemon exec terminateVat \'{"vatId":"v1"}\'',
+                'Terminate a vat',
+              ),
+          async (args) => {
+            const execArgs: string[] = [];
+            if (args.method) {
+              execArgs.push(String(args.method));
+            }
+            if (args['params-json']) {
+              execArgs.push(String(args['params-json']));
+            }
+            await ensureDaemon(socketPath);
+            await handleDaemonExec(execArgs, socketPath);
+          },
+        )
+        .command(
+          '$0',
+          false,
+          (_y) => _y,
+          async () => {
+            await handleDaemonStart(socketPath);
+          },
+        );
+    },
+    () => {
+      // Handled by subcommands.
+    },
   );
 
 await yargsInstance.help('help').parse();

packages/cli/src/commands/daemon-client.ts

@@ -0,0 +1,119 @@
+import type { JsonRpcResponse } from '@metamask/utils';
+import { assertIsJsonRpcResponse } from '@metamask/utils';
+import { readLine, writeLine } from '@ocap/nodejs/daemon';
+import { randomUUID } from 'node:crypto';
+import { createConnection } from 'node:net';
+import type { Socket } from 'node:net';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+/**
+ * Get the default daemon socket path.
+ *
+ * @returns The socket path.
+ */
+export function getSocketPath(): string {
+  return join(homedir(), '.ocap', 'daemon.sock');
+}
+
+/**
+ * Connect to a UNIX domain socket.
+ *
+ * @param socketPath - The socket path to connect to.
+ * @returns A connected socket.
+ */
+async function connectSocket(socketPath: string): Promise<Socket> {
+  return new Promise((resolve, reject) => {
+    const socket = createConnection(socketPath, () => {
+      socket.removeListener('error', reject);
+      resolve(socket);
+    });
+    socket.on('error', reject);
+  });
+}
+
+/**
+ * Options for {@link sendCommand}.
+ */
+type SendCommandOptions = {
+  /** The UNIX socket path. */
+  socketPath: string;
+  /** The RPC method name. */
+  method: string;
+  /** Optional method parameters. */
+  params?: Record<string, unknown> | undefined;
+  /** 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
+ * if the connection is rejected (e.g. due to a probe connection race).
+ *
+ * @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 (default: 30 000).
+ * @returns The parsed JSON-RPC response.
+ */
+export async function sendCommand({
+  socketPath,
+  method,
+  params,
+  timeoutMs = 30_000,
+}: SendCommandOptions): Promise<JsonRpcResponse> {
+  const id = randomUUID();
+  const request = {
+    jsonrpc: '2.0',
+    id,
+    method,
+    ...(params === undefined ? {} : { params }),
+  };
+
+  const attempt = async (): Promise<JsonRpcResponse> => {
+    const socket = await connectSocket(socketPath);
+    try {
+      await writeLine(socket, JSON.stringify(request));
+      const responseLine = await readLine(socket, timeoutMs);
+      const parsed: unknown = JSON.parse(responseLine);
+      assertIsJsonRpcResponse(parsed);
+      return parsed;
+    } finally {
+      socket.destroy();
+    }
+  };
+
+  try {
+    return await attempt();
+  } catch (error: unknown) {
+    // Retry once on connection errors only — the daemon's socket may
+    // still be cleaning up a previous connection.
+    const code = (error as NodeJS.ErrnoException | undefined)?.code;
+    if (code !== 'ECONNREFUSED' && code !== 'ECONNRESET') {
+      throw error;
+    }
+    await new Promise((resolve) => setTimeout(resolve, 100));
+    return attempt();
+  }
+}
+
+/**
+ * Check whether the daemon is running by sending a lightweight `getStatus`
+ * RPC call. Unlike a bare socket probe, this avoids spurious connect/disconnect
+ * noise on the server.
+ *
+ * @param socketPath - The UNIX socket path.
+ * @returns True if the daemon responds to the RPC call.
+ */
+export async function pingDaemon(socketPath: string): Promise<boolean> {
+  try {
+    await sendCommand({ socketPath, method: 'getStatus', timeoutMs: 3_000 });
+    return true;
+  } catch {
+    return false;
+  }
+}