libretto 0.6.11 → 0.6.12

package/src/shared/ipc/ipc.ts

@@ -0,0 +1,288 @@
+import { randomUUID } from "node:crypto";
+
+export type IpcTransport<T = unknown> = {
+  send(message: T): void | Promise<void>;
+  listen(callback: (message: T) => void): () => void;
+  onClose?(callback: (error?: Error) => void): () => void;
+  close?(): void;
+};
+
+type FunctionMap<T> = {
+  [K in keyof T]: (...args: never[]) => unknown;
+};
+
+type UnwrapPromise<T> = T extends Promise<infer Result> ? Result : T;
+
+type MaybeAsync<T extends (...args: never[]) => unknown> = T extends (
+  ...args: infer Args
+) => infer Result
+  ? (...args: Args) => UnwrapPromise<Result> | Promise<UnwrapPromise<Result>>
+  : never;
+
+export type IpcPeerHandlers<Local extends FunctionMap<Local>> = {
+  [K in keyof Local]: MaybeAsync<Local[K]>;
+};
+
+export type IpcPeerCalls<Remote extends FunctionMap<Remote>> = {
+  [K in keyof Remote]: Remote[K] extends (...args: infer Args) => infer Result
+    ? (...args: Args) => Promise<UnwrapPromise<Result>>
+    : never;
+};
+
+export type IpcPeer<Remote extends FunctionMap<Remote>> = {
+  call: IpcPeerCalls<Remote>;
+  destroy(): void;
+};
+
+type IpcRequestMessage = {
+  type: "ipc-request";
+  id: string;
+  method: string;
+  args: unknown[];
+};
+
+type SerializedError = {
+  name: string;
+  message: string;
+  stack?: string;
+  code?: string | number;
+  cause?: SerializedError;
+  errors?: SerializedError[];
+};
+
+type IpcResponseMessage = {
+  type: "ipc-response";
+  id: string;
+  method: string;
+  data?: unknown;
+  error?: SerializedError;
+};
+
+export type IpcProtocolMessage = IpcRequestMessage | IpcResponseMessage;
+
+type PendingRequest = {
+  method: string;
+  resolve(value: unknown): void;
+  reject(error: unknown): void;
+};
+
+export function createIpcPeer<
+  Remote extends FunctionMap<Remote>,
+  Local extends FunctionMap<Local>,
+>(
+  transport: IpcTransport<IpcProtocolMessage>,
+  handlers: IpcPeerHandlers<Local>,
+): IpcPeer<Remote> {
+  const pending = new Map<string, PendingRequest>();
+  let destroyed = false;
+
+  const stopListening = transport.listen((message) => {
+    if (message.type === "ipc-request") {
+      void handleRequest(message);
+      return;
+    }
+
+    handleResponse(message);
+  });
+  const stopCloseListener = transport.onClose?.((error) => {
+    destroy(error ?? new Error("IPC transport closed"));
+  });
+
+  async function handleRequest(message: IpcRequestMessage): Promise<void> {
+    if (destroyed) return;
+
+    const handler = handlers[message.method as keyof Local];
+    if (!handler) {
+      await sendResponse({
+        type: "ipc-response",
+        id: message.id,
+        method: message.method,
+        error: serializeError(
+          new Error(`No handler registered for method: ${message.method}`),
+        ),
+      });
+      return;
+    }
+
+    try {
+      const data = await Promise.resolve(handler(...(message.args as never[])));
+      await sendResponse({
+        type: "ipc-response",
+        id: message.id,
+        method: message.method,
+        data,
+      });
+    } catch (error) {
+      await sendResponse({
+        type: "ipc-response",
+        id: message.id,
+        method: message.method,
+        error: serializeError(error),
+      });
+    }
+  }
+
+  async function sendResponse(message: IpcResponseMessage): Promise<void> {
+    try {
+      await transport.send(message);
+    } catch {
+      // The caller has no response channel for response-send failures.
+    }
+  }
+
+  function handleResponse(message: IpcResponseMessage): void {
+    const request = pending.get(message.id);
+    if (!request) return;
+
+    pending.delete(message.id);
+
+    if (message.error) {
+      request.reject(deserializeRemoteError(request.method, message.error));
+      return;
+    }
+
+    request.resolve(message.data);
+  }
+
+  const call = new Proxy({} as IpcPeerCalls<Remote>, {
+    get: (_target, method: string | symbol) => {
+      if (typeof method !== "string") return undefined;
+
+      return (...args: unknown[]) => {
+        if (destroyed) {
+          return Promise.reject(new Error("IPC peer destroyed"));
+        }
+
+        const id = `${method}-${randomUUID()}`;
+
+        const promise = new Promise<unknown>((resolve, reject) => {
+          pending.set(id, { method, resolve, reject });
+        });
+
+        void Promise.resolve(
+          transport.send({
+            type: "ipc-request",
+            id,
+            method,
+            args,
+          }),
+        ).catch((error: unknown) => {
+          const request = pending.get(id);
+          if (!request) return;
+          pending.delete(id);
+          request.reject(error);
+        });
+
+        return promise;
+      };
+    },
+  });
+
+  function destroy(error = new Error("IPC peer destroyed")): void {
+    if (destroyed) return;
+    destroyed = true;
+    stopListening();
+    stopCloseListener?.();
+    transport.close?.();
+
+    for (const request of pending.values()) {
+      request.reject(error);
+    }
+
+    pending.clear();
+  }
+
+  return { call, destroy };
+}
+
+function serializeError(
+  error: unknown,
+  seen = new WeakSet<object>(),
+): SerializedError {
+  if (typeof error === "object" && error !== null) {
+    if (seen.has(error)) {
+      return {
+        name: "Error",
+        message: "[Circular]",
+      };
+    }
+
+    seen.add(error);
+  }
+
+  if (error instanceof Error) {
+    const serialized: SerializedError = {
+      name: error.name,
+      message: error.message,
+      stack: error.stack,
+    };
+
+    const errorWithCode = error as Error & { code?: unknown };
+    if (
+      typeof errorWithCode.code === "string" ||
+      typeof errorWithCode.code === "number"
+    ) {
+      serialized.code = errorWithCode.code;
+    }
+
+    if (error.cause !== undefined) {
+      serialized.cause = serializeError(error.cause, seen);
+    }
+
+    if (error instanceof AggregateError) {
+      serialized.errors = error.errors.map((aggregateError: unknown) =>
+        serializeError(aggregateError, seen),
+      );
+    }
+
+    return serialized;
+  }
+
+  return {
+    name: "NonError",
+    message: String(error),
+  };
+}
+
+function deserializeRemoteError(
+  method: string,
+  remoteError: SerializedError,
+): Error {
+  const error = deserializeSerializedError(
+    remoteError,
+    `${method} > ${remoteError.message}`,
+  );
+  error.stack = [new Error(method).stack, remoteError.stack]
+    .filter((stack): stack is string => typeof stack === "string")
+    .join("\n");
+  return error;
+}
+
+function deserializeSerializedError(
+  serialized: SerializedError,
+  message = serialized.message,
+): Error {
+  const cause = serialized.cause
+    ? deserializeSerializedError(serialized.cause)
+    : undefined;
+  const error =
+    serialized.name === "AggregateError" && serialized.errors
+      ? new AggregateError(
+          serialized.errors.map((aggregateError) =>
+            deserializeSerializedError(aggregateError),
+          ),
+          message,
+          { cause },
+        )
+      : new Error(message, { cause });
+
+  error.name = serialized.name;
+  error.stack = serialized.stack;
+
+  const errorWithCode = error as Error & { code?: string | number };
+  if (serialized.code !== undefined) {
+    errorWithCode.code = serialized.code;
+  }
+
+  return error;
+}

package/src/shared/ipc/socket-transport.spec.ts

@@ -0,0 +1,141 @@
+import { mkdtemp, stat, writeFile } from "node:fs/promises";
+import { createConnection } from "node:net";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { expect, test as base } from "vitest";
+import { createIpcPeer, type IpcPeer } from "./ipc.js";
+import {
+  connectToIpcSocket,
+  listenForIpcConnections,
+} from "./socket-transport.js";
+
+const test = base.extend<{
+  socketPath: string;
+}>({
+  socketPath: async ({}, use) => {
+    const directory = await mkdtemp(join(tmpdir(), "libretto-ipc-"));
+    await use(join(directory, "daemon.sock"));
+  },
+});
+
+type ClientApi = {
+  ping(): string;
+};
+
+type ServerApi = {
+  double(value: number): Promise<number>;
+  wait(): Promise<string>;
+};
+
+test("sends concurrent calls over one socket", async ({ socketPath }) => {
+  await writeFile(socketPath, "stale");
+
+  const serverPeers: Array<IpcPeer<ClientApi>> = [];
+  const server = await listenForIpcConnections(socketPath, (transport) => {
+    serverPeers.push(
+      createIpcPeer<ClientApi, ServerApi>(transport, {
+        async double(value) {
+          return value * 2;
+        },
+        async wait() {
+          return "done";
+        },
+      }),
+    );
+  });
+  const client = createIpcPeer<ServerApi, ClientApi>(
+    await connectToIpcSocket(socketPath),
+    {
+      ping() {
+        return "pong";
+      },
+    },
+  );
+
+  await expect(
+    Promise.all([client.call.double(2), client.call.double(21)]),
+  ).resolves.toEqual([4, 42]);
+
+  client.destroy();
+  for (const peer of serverPeers) peer.destroy();
+  await new Promise<void>((resolve, reject) => {
+    server.close((error) => (error ? reject(error) : resolve()));
+  });
+  await expect(stat(socketPath)).rejects.toThrow();
+});
+
+test("rejects pending calls when the socket closes", async ({ socketPath }) => {
+  const serverPeers: Array<IpcPeer<ClientApi>> = [];
+  const server = await listenForIpcConnections(socketPath, (transport) => {
+    serverPeers.push(
+      createIpcPeer<ClientApi, ServerApi>(transport, {
+        async double(value) {
+          return value * 2;
+        },
+        async wait() {
+          return new Promise(() => {});
+        },
+      }),
+    );
+  });
+  const client = createIpcPeer<ServerApi, ClientApi>(
+    await connectToIpcSocket(socketPath),
+    {
+      ping() {
+        return "pong";
+      },
+    },
+  );
+  const pending = client.call.wait();
+
+  for (const peer of serverPeers) peer.destroy();
+
+  await expect(pending).rejects.toThrow(/IPC transport closed|ECONNRESET/);
+
+  client.destroy();
+  await new Promise<void>((resolve, reject) => {
+    server.close((error) => (error ? reject(error) : resolve()));
+  });
+});
+
+test("closes malformed socket messages without stopping the server", async ({
+  socketPath,
+}) => {
+  const server = await listenForIpcConnections(socketPath, (transport) => {
+    createIpcPeer<ClientApi, ServerApi>(transport, {
+      async double(value) {
+        return value * 2;
+      },
+      async wait() {
+        return "done";
+      },
+    });
+  });
+
+  const malformedClient = createConnection(socketPath);
+  await new Promise<void>((resolve, reject) => {
+    malformedClient.once("connect", resolve);
+    malformedClient.once("error", reject);
+  });
+  const malformedClosed = new Promise<void>((resolve) => {
+    malformedClient.once("close", () => resolve());
+  });
+  malformedClient.write("not-json\n");
+  await malformedClosed;
+
+  const validClient = createIpcPeer<ServerApi, ClientApi>(
+    await connectToIpcSocket(socketPath),
+    {
+      ping() {
+        return "pong";
+      },
+    },
+  );
+
+  await expect(validClient.call.double(4)).resolves.toBe(8);
+
+  validClient.destroy();
+  await new Promise<void>((resolve, reject) => {
+    server.close((error) => (error ? reject(error) : resolve()));
+  });
+});

package/src/shared/ipc/socket-transport.ts

@@ -0,0 +1,189 @@
+import { rm } from "node:fs/promises";
+import {
+  createServer,
+  createConnection,
+  type Server,
+  type Socket,
+} from "node:net";
+import { dirname } from "node:path";
+import { mkdir } from "node:fs/promises";
+import type { IpcProtocolMessage, IpcTransport } from "./ipc.js";
+
+function createJsonSocketTransport(
+  socket: Socket,
+): IpcTransport<IpcProtocolMessage> {
+  socket.setEncoding("utf8");
+
+  return {
+    send(message) {
+      return new Promise<void>((resolve, reject) => {
+        const line = `${JSON.stringify(message)}\n`;
+        socket.write(line, (error) => {
+          if (error) reject(error);
+          else resolve();
+        });
+      });
+    },
+    listen(callback) {
+      let buffer = "";
+      const onData = (chunk: string) => {
+        buffer += chunk;
+
+        while (true) {
+          const newlineIndex = buffer.indexOf("\n");
+          if (newlineIndex === -1) break;
+
+          const line = buffer.slice(0, newlineIndex);
+          buffer = buffer.slice(newlineIndex + 1);
+          if (line.length === 0) continue;
+
+          let message: unknown;
+          try {
+            message = JSON.parse(line) as unknown;
+          } catch (error) {
+            socket.destroy(
+              new Error(
+                `Invalid IPC socket message: ${error instanceof Error ? error.message : String(error)}`,
+              ),
+            );
+            return;
+          }
+
+          if (!isIpcProtocolMessage(message)) {
+            socket.destroy(new Error("Invalid IPC socket protocol message."));
+            return;
+          }
+
+          callback(message);
+        }
+      };
+
+      socket.on("data", onData);
+      return () => socket.off("data", onData);
+    },
+    onClose(callback) {
+      let closeError: Error | undefined;
+      const onError = (error: Error) => {
+        closeError = error;
+      };
+      const onClose = () => callback(closeError);
+
+      socket.on("error", onError);
+      socket.on("close", onClose);
+      return () => {
+        socket.off("error", onError);
+        socket.off("close", onClose);
+      };
+    },
+    close() {
+      socket.destroy();
+    },
+  };
+}
+
+export async function connectToIpcSocket(
+  socketPath: string,
+): Promise<IpcTransport<IpcProtocolMessage>> {
+  const socket = await connectSocket(socketPath);
+  return createJsonSocketTransport(socket);
+}
+
+export function createIpcSocketServer(
+  onConnection: (transport: IpcTransport<IpcProtocolMessage>) => void,
+): Server {
+  return createServer((socket) => {
+    onConnection(createJsonSocketTransport(socket));
+  });
+}
+
+export async function listenForIpcConnections(
+  socketPath: string,
+  onConnection: (transport: IpcTransport<IpcProtocolMessage>) => void,
+): Promise<Server> {
+  const server = createIpcSocketServer(onConnection);
+  await listenOnIpcSocket(server, socketPath);
+  return server;
+}
+
+export async function listenOnIpcSocket(
+  server: Server,
+  socketPath: string,
+): Promise<void> {
+  await mkdir(dirname(socketPath), { recursive: true });
+  await rm(socketPath, { force: true });
+
+  const originalClose = server.close.bind(server);
+  server.close = ((callback?: (error?: Error) => void) => {
+    return originalClose((error?: Error) => {
+      void rm(socketPath, { force: true }).finally(() => callback?.(error));
+    });
+  }) as Server["close"];
+
+  await new Promise<void>((resolve, reject) => {
+    const onError = (error: Error) => {
+      server.off("listening", onListening);
+      reject(error);
+    };
+    const onListening = () => {
+      server.off("error", onError);
+      resolve();
+    };
+
+    server.once("error", onError);
+    server.once("listening", onListening);
+    server.listen(socketPath);
+  });
+}
+
+async function connectSocket(socketPath: string): Promise<Socket> {
+  const socket = createConnection(socketPath);
+
+  return new Promise<Socket>((resolve, reject) => {
+    const onError = (error: Error) => {
+      socket.off("connect", onConnect);
+      reject(error);
+    };
+    const onConnect = () => {
+      socket.off("error", onError);
+      resolve(socket);
+    };
+
+    socket.once("error", onError);
+    socket.once("connect", onConnect);
+  });
+}
+
+function isIpcProtocolMessage(message: unknown): message is IpcProtocolMessage {
+  if (!isRecord(message)) return false;
+
+  if (message.type === "ipc-request") {
+    return (
+      typeof message.id === "string" &&
+      typeof message.method === "string" &&
+      Array.isArray(message.args)
+    );
+  }
+
+  if (message.type === "ipc-response") {
+    return (
+      typeof message.id === "string" &&
+      typeof message.method === "string" &&
+      (message.error === undefined || isSerializedError(message.error))
+    );
+  }
+
+  return false;
+}
+
+function isSerializedError(value: unknown): boolean {
+  return (
+    isRecord(value) &&
+    typeof value.name === "string" &&
+    typeof value.message === "string" &&
+    (value.stack === undefined || typeof value.stack === "string")
+  );
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}

package/src/shared/package-manager.ts

@@ -0,0 +1,76 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { resolveLibrettoRepoRoot } from "./paths/repo-root.js";
+
+export type PackageManager = "npm" | "pnpm" | "yarn" | "bun";
+
+function packageManagerFromUserAgent(
+  env: NodeJS.ProcessEnv = process.env,
+): PackageManager | null {
+  const userAgent = env.npm_config_user_agent ?? "";
+  if (userAgent.startsWith("pnpm")) return "pnpm";
+  if (userAgent.startsWith("yarn")) return "yarn";
+  if (userAgent.startsWith("bun")) return "bun";
+  if (userAgent.startsWith("npm")) return "npm";
+  return null;
+}
+
+function packageManagerFromLockfile(root: string): PackageManager | null {
+  if (existsSync(join(root, "pnpm-lock.yaml"))) return "pnpm";
+  if (existsSync(join(root, "yarn.lock"))) return "yarn";
+  if (existsSync(join(root, "bun.lockb")) || existsSync(join(root, "bun.lock")))
+    return "bun";
+  return null;
+}
+
+export function detectPackageManager(
+  root = resolveLibrettoRepoRoot(),
+  env: NodeJS.ProcessEnv = process.env,
+): PackageManager {
+  const fromUserAgent = packageManagerFromUserAgent(env);
+  if (fromUserAgent) return fromUserAgent;
+
+  return packageManagerFromLockfile(root) ?? "npm";
+}
+
+export function detectProjectPackageManager(
+  root = resolveLibrettoRepoRoot(),
+): PackageManager {
+  return packageManagerFromLockfile(root) ?? "npm";
+}
+
+export function installCommand(
+  packageManager = detectProjectPackageManager(),
+): string {
+  switch (packageManager) {
+    case "yarn":
+      return "yarn add";
+    case "bun":
+      return "bun add";
+    case "pnpm":
+      return "pnpm add";
+    default:
+      return "npm install";
+  }
+}
+
+function librettoRunner(packageManager = detectPackageManager()): string {
+  switch (packageManager) {
+    case "pnpm":
+      return "pnpm exec";
+    case "yarn":
+      return "yarn";
+    case "bun":
+      return "bunx";
+    default:
+      return "npx";
+  }
+}
+
+export function librettoCommand(
+  args = "",
+  packageManager = detectPackageManager(),
+): string {
+  const suffix = args.trim();
+  return `${librettoRunner(packageManager)} libretto${suffix ? ` ${suffix}` : ""}`;
+}