@anhlp/alp-client 0.0.0-beta.1

package/dist/index.d.ts

@@ -0,0 +1,101 @@
+export function alpHome(env?: NodeJS.ProcessEnv): string;
+/** Windows uses named pipes; long Unix homes get a short socket in the temp directory. */
+export function daemonPaths(home: any): {
+    home: any;
+    lock: string;
+    socket: string;
+    log: string;
+    install: string;
+};
+export function assertPrivateDirectory(directory: any, { create }?: {
+    create?: boolean | undefined;
+}): Promise<void>;
+export function assertPrivateSocket(socketPath: any): Promise<import("fs").Stats | undefined>;
+/**
+ * Finds alpd.js for a client that cannot locate it beside itself, such as the Paseo
+ * plugin, which Paseo re-bundles: the first existing candidate, then where alpd last
+ * recorded itself ($ALP_HOME/alpd.json), then the ALP CLI (`alp`) on PATH.
+ */
+export function findDaemonEntry({ home, env, candidates }?: {
+    home?: string | undefined;
+    env?: NodeJS.ProcessEnv | undefined;
+    candidates?: (string | undefined)[] | undefined;
+}): Promise<string | undefined>;
+/** Wall-clock boot time; a lock from an earlier boot is stale even if its pid is reused. */
+export function bootTime(): number;
+export function readLock(home: any): Promise<any>;
+export function lockAlive(lock: any): boolean;
+/**
+ * Takes alpd's single-instance lock for `home`: exclusive create; a lock whose pid or boot is
+ * gone is stale and replaced. alpd takes it to run; `alp backup` and `alp restore` take it with
+ * `maintenance` set, so no alpd starts on data they read or replace (ALPD §68).
+ * @param {string} home
+ * @param {{ version: string, protocolVersion: number, socket: string, maintenance?: string }} contents
+ */
+export function acquireDaemonLock(home: string, contents: {
+    version: string;
+    protocolVersion: number;
+    socket: string;
+    maintenance?: string;
+}): Promise<{
+    version: string;
+    protocolVersion: number;
+    socket: string;
+    maintenance?: string;
+    pid: number;
+    startedAt: string;
+    bootTime: number;
+    uid: number;
+    ready: boolean;
+}>;
+/** Lets go of alpd's lock if this process holds it. */
+export function releaseDaemonLock(home: any): Promise<void>;
+/**
+ * The transport to alpd's socket without the handshake, for an AlpRpcClient or a reconnecting
+ * client whose onConnect runs `hello`. `connect` is this plus `hello`.
+ * @param {string} socketPath
+ * @param {import('./ipc.js').SocketTransportOptions} [options]
+ */
+export function connectSocket(socketPath: string, options?: import("./ipc.js").SocketTransportOptions): Promise<import("./rpc/client.js").AlpTransport>;
+/**
+ * Connects and performs the version handshake.
+ * @param {string} socketPath
+ * @param {{ name: string, version: string }} [client]
+ * @param {import('./rpc/client.js').AlpRpcClientOptions & import('./ipc.js').SocketTransportOptions} [options]
+ * @returns {Promise<AlpClient>}
+ */
+export function connect(socketPath: string, client?: {
+    name: string;
+    version: string;
+}, options?: import("./rpc/client.js").AlpRpcClientOptions & import("./ipc.js").SocketTransportOptions): Promise<AlpClient>;
+/**
+ * Returns the socket of a ready daemon, starting one when none runs.
+ * `entry` is the daemon script; it is started through its own detaching launcher so the
+ * daemon outlives the client that started it.
+ */
+export function ensureDaemon({ home, entry, env, execPath, timeoutMs }?: {
+    home?: string | undefined;
+    entry?: string | undefined;
+    env?: NodeJS.ProcessEnv | undefined;
+    execPath?: string | undefined;
+    timeoutMs?: number | undefined;
+}): Promise<any>;
+export function discoverIntegration(name?: string, options?: {}): Promise<string | undefined>;
+export function startIntegration(nameOrOptions?: string): Promise<any>;
+export * from "./portable.js";
+export { createSocketTransport } from "./ipc.js";
+/**
+ * One JSON-RPC 2.0 connection to alpd over a Unix socket or named pipe; events arrive as `event`
+ * notifications. The engine is the portable AlpRpcClient; this keeps the socket constructor the
+ * CLI, alpd's tests and the Paseo plugin use.
+ */
+export class AlpClient extends AlpRpcClient {
+    /**
+     * @param {import('node:net').Socket} socket a connected or connecting socket; the client owns it
+     * @param {import('./rpc/client.js').AlpRpcClientOptions & import('./ipc.js').SocketTransportOptions} [options]
+     */
+    constructor(socket: import("node:net").Socket, { maxFrame, maxBufferedBytes, ...options }?: import("./rpc/client.js").AlpRpcClientOptions & import("./ipc.js").SocketTransportOptions);
+}
+import { AlpRpcClient } from './rpc/client.js';
+export { PROTOCOL_VERSION, MAX_FRAME, AlpRpcError, encodeFrame } from "@anhlp/alp-protocol";
+export { connectWebSocket, createWebSocketTransport, redactUrl, CLOSE_CODE } from "./websocket.js";

package/dist/index.js

@@ -0,0 +1,422 @@
+// packages/client/src/index.js
+import { spawn } from "node:child_process";
+import { createHash } from "node:crypto";
+import { open, readFile, realpath, stat, lstat, mkdir, readlink, unlink } from "node:fs/promises";
+import net from "node:net";
+import os from "node:os";
+import path from "node:path";
+import { scrubText } from "@anhlp/alp-core/log";
+import { createSocketTransport } from "./ipc.js";
+import { AlpRpcClient } from "./rpc/client.js";
+import { hello } from "./rpc/handshake.js";
+import { PROTOCOL_VERSION, MAX_FRAME, AlpRpcError, encodeFrame } from "@anhlp/alp-protocol";
+export * from "./portable.js";
+import { connectWebSocket, createWebSocketTransport, redactUrl, CLOSE_CODE } from "./websocket.js";
+import { createSocketTransport as createSocketTransport2 } from "./ipc.js";
+function alpHome(env = process.env) {
+  return path.resolve(env.ALP_HOME || path.join(os.homedir(), ".alp"));
+}
+function daemonPaths(home) {
+  const preferred = path.join(home, "alpd.sock");
+  const socket = process.platform === "win32" ? `\\\\.\\pipe\\alpd-${createHash("sha256").update(home).digest("hex").slice(0, 24)}` : Buffer.byteLength(preferred) < 100 ? preferred : path.join(os.tmpdir(), `alpd-${process.getuid?.() ?? "user"}-${createHash("sha256").update(home).digest("hex").slice(0, 12)}`, "rpc.sock");
+  return { home, lock: path.join(home, "alpd.lock"), socket, log: path.join(home, "logs", "alpd.log"), install: path.join(home, "alpd.json") };
+}
+async function assertSafeAncestors(directory) {
+  if (process.platform === "win32") return;
+  const absolute = path.isAbsolute(directory) ? directory : `${process.cwd()}/${directory}`;
+  let current = path.parse(absolute).root;
+  const pending = absolute.slice(current.length).split("/");
+  let links = 0;
+  while (pending.length) {
+    const part = pending.shift();
+    if (!part || part === ".") continue;
+    if (part === "..") {
+      current = path.dirname(current);
+      continue;
+    }
+    const candidate = path.join(current, part);
+    const info = await lstat(candidate).catch((error) => {
+      if (error.code !== "ENOENT") throw error;
+    });
+    if (!info) {
+      current = candidate;
+      continue;
+    }
+    const trustedOwner = info.uid === 0 || info.uid === process.getuid?.();
+    if (!trustedOwner) throw new Error("IPC requires ancestors owned by the current user or root");
+    if (info.isSymbolicLink()) {
+      if (++links > 40) throw new Error("IPC ancestor symlink loop");
+      const target = await readlink(candidate);
+      if (path.isAbsolute(target)) current = path.parse(target).root;
+      pending.unshift(...target.slice(path.isAbsolute(target) ? path.parse(target).root.length : 0).split("/"));
+      continue;
+    }
+    if (!info.isDirectory() || info.mode & 18 && !(info.mode & 512)) {
+      throw new Error("IPC requires trusted ancestors without shared write permissions");
+    }
+    current = candidate;
+  }
+}
+async function assertPrivateDirectory(directory, { create = false } = {}) {
+  await assertSafeAncestors(directory);
+  if (create) await mkdir(directory, { recursive: true, mode: 448 });
+  const info = await lstat(directory);
+  if (!info.isDirectory() || info.isSymbolicLink()) throw new Error("IPC requires a private directory, not a symlink");
+  if (process.platform !== "win32" && (info.uid !== process.getuid?.() || (info.mode & 63) !== 0)) {
+    throw new Error("IPC directory must be owned by the current user with private permissions (0700)");
+  }
+}
+async function assertPrivateSocket(socketPath) {
+  if (process.platform === "win32") return;
+  await assertPrivateDirectory(path.dirname(socketPath));
+  const info = await lstat(socketPath);
+  if (!info.isSocket() || info.uid !== process.getuid?.() || (info.mode & 63) !== 0) {
+    throw new Error("IPC socket must be owned by the current user with private permissions (0600)");
+  }
+  return info;
+}
+var isFile = (file) => stat(file).then((info) => info.isFile(), () => false);
+var BIN_DIRECTORIES = [path.join(os.homedir(), ".npm-global", "bin"), path.join(os.homedir(), ".local", "bin"), "/opt/homebrew/bin", "/usr/local/bin"];
+var CLI_PACKAGES = ["@anhlp/alp", "@anhlp/alp-cli"];
+async function findDaemonEntry({ home = alpHome(), env = process.env, candidates = (
+  /** @type {Array<string | undefined>} */
+  []
+) } = {}) {
+  for (const candidate of candidates) if (candidate && await isFile(candidate)) return candidate;
+  try {
+    const { entry } = JSON.parse(await readFile(daemonPaths(home).install, "utf8"));
+    if (typeof entry === "string" && await isFile(entry)) return entry;
+  } catch {
+  }
+  for (const directory of [...(env.PATH ?? "").split(path.delimiter).filter(Boolean), ...BIN_DIRECTORIES]) {
+    const cli = await realpath(path.join(directory, "alp")).catch(() => void 0);
+    if (!cli || path.basename(cli) !== "cli.js") continue;
+    const root = path.resolve(path.dirname(cli), "..");
+    const name = await readFile(path.join(root, "package.json"), "utf8").then((text) => JSON.parse(text).name, () => void 0);
+    const entry = path.join(root, "dist", "alpd.js");
+    if (CLI_PACKAGES.includes(name) && await isFile(entry)) return entry;
+  }
+  return void 0;
+}
+function bootTime() {
+  return Math.round((Date.now() - os.uptime() * 1e3) / 1e3);
+}
+async function readLock(home) {
+  try {
+    return JSON.parse(await readFile(daemonPaths(home).lock, "utf8"));
+  } catch (error) {
+    if (error?.code === "ENOENT" || error instanceof SyntaxError) return void 0;
+    throw error;
+  }
+}
+function lockAlive(lock) {
+  if (!lock || !Number.isSafeInteger(lock.pid) || Math.abs((lock.bootTime ?? 0) - bootTime()) > 30) return false;
+  try {
+    process.kill(lock.pid, 0);
+    return true;
+  } catch (error) {
+    return error?.code === "EPERM";
+  }
+}
+async function acquireDaemonLock(home, contents) {
+  const file = daemonPaths(home).lock;
+  const lock = { pid: process.pid, startedAt: (/* @__PURE__ */ new Date()).toISOString(), bootTime: bootTime(), uid: process.getuid?.() ?? -1, ready: false, ...contents };
+  for (let attempt = 0; attempt < 2; attempt++) {
+    try {
+      const handle = await open(file, "wx", 384);
+      await handle.writeFile(JSON.stringify(lock));
+      await handle.close();
+      return lock;
+    } catch (error) {
+      if (error?.code !== "EEXIST") throw error;
+      const current = await readLock(home);
+      if (lockAlive(current)) throw new Error(current.maintenance ? `ALP is busy: alp ${current.maintenance} runs (pid ${current.pid}); try again when it finishes` : `ALP daemon already running (pid ${current.pid})`);
+      const again = await readFile(file, "utf8").catch(() => void 0);
+      if (again === void 0 || JSON.stringify(current) === again || !lockAlive(JSON.parse(again))) await unlink(file).catch(() => {
+      });
+    }
+  }
+  throw new Error("Could not acquire the ALP daemon lock");
+}
+async function releaseDaemonLock(home) {
+  const current = await readLock(home);
+  if (current?.pid === process.pid) await unlink(daemonPaths(home).lock).catch(() => {
+  });
+}
+var AlpClient = class extends AlpRpcClient {
+  /**
+   * @param {import('node:net').Socket} socket a connected or connecting socket; the client owns it
+   * @param {import('./rpc/client.js').AlpRpcClientOptions & import('./ipc.js').SocketTransportOptions} [options]
+   */
+  constructor(socket, { maxFrame, maxBufferedBytes, ...options } = {}) {
+    super(createSocketTransport(socket, { maxFrame, maxBufferedBytes }), { maxFrame, ...options });
+  }
+};
+async function openSocket(socketPath) {
+  await assertPrivateSocket(socketPath);
+  return (
+    /** @type {Promise<import('node:net').Socket>} */
+    new Promise((resolve, reject) => {
+      const candidate = net.createConnection(socketPath);
+      candidate.once("connect", () => {
+        candidate.off("error", reject);
+        resolve(candidate);
+      });
+      candidate.once("error", reject);
+    })
+  );
+}
+async function connectSocket(socketPath, options) {
+  return createSocketTransport(await openSocket(socketPath), options);
+}
+async function connect(socketPath, client = { name: "alp", version: "0" }, options = {}) {
+  const connection = new AlpClient(await openSocket(socketPath), options);
+  try {
+    await hello(connection, client);
+  } catch (error) {
+    connection.close();
+    throw error;
+  }
+  return connection;
+}
+function launcherReason(text) {
+  const line = text.trim().split("\n").filter(Boolean).at(-1);
+  if (!line) return "";
+  let reason = line;
+  try {
+    const record = JSON.parse(line);
+    reason = `${record.code ? `${record.code}, ` : ""}${record.msg}${record.error?.message ? `: ${record.error.message}` : ""}`;
+  } catch {
+  }
+  return `: ${scrubText(reason, { max: 600 })}`;
+}
+async function tail(file, lines = 30) {
+  try {
+    return scrubText((await readFile(file, "utf8")).split("\n").slice(-lines).join("\n"), { max: 8e3 });
+  } catch {
+    return "";
+  }
+}
+async function ensureDaemon({ home = alpHome(), entry = (
+  /** @type {string | undefined} */
+  void 0
+), env = process.env, execPath = process.execPath, timeoutMs = 15e3 } = {}) {
+  const ready = async () => {
+    const lock = await readLock(home);
+    return lockAlive(lock) && lock.ready ? lock.socket : void 0;
+  };
+  const live = await ready();
+  if (live) return live;
+  const held = await readLock(home);
+  if (lockAlive(held) && held.maintenance) throw new Error(`ALP is busy: alp ${held.maintenance} runs (pid ${held.pid}); alpd starts again when it finishes`);
+  if (!lockAlive(held)) {
+    entry ??= await findDaemonEntry({ home, env });
+    if (!entry) throw new Error("ALP daemon is not running and alpd.js was not found. Install the ALP CLI and run `alp daemon start`, or set ALP_DAEMON_ENTRY to alpd.js");
+    await new Promise((resolve, reject) => {
+      const launcher = spawn(execPath, [entry, "--detach"], {
+        env: { ...env, ALP_HOME: home, ELECTRON_RUN_AS_NODE: "1" },
+        stdio: ["ignore", "ignore", "pipe"],
+        windowsHide: true
+      });
+      let failure = "";
+      launcher.stderr.on("data", (chunk) => {
+        if (failure.length < 8e3) failure += chunk;
+      });
+      launcher.once("error", reject);
+      launcher.once("close", (code) => code === 0 ? resolve() : reject(new Error(`ALP daemon launcher exited (${code})${launcherReason(failure)}`)));
+    });
+  }
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const socket = await ready();
+    if (socket) return socket;
+    await new Promise((resolve) => setTimeout(resolve, 100));
+  }
+  const log = await tail(daemonPaths(home).log);
+  throw new Error(`ALP daemon did not become ready within ${timeoutMs} ms${log ? `
+${log}` : ""}`);
+}
+var INTEGRATION_DESCRIPTOR_FIELDS = ["main", "entry", "path", "command"];
+async function readIntegrationDescriptor(file, baseDirs = []) {
+  try {
+    const raw = JSON.parse(await readFile(file, "utf8"));
+    for (const field of INTEGRATION_DESCRIPTOR_FIELDS) {
+      const value = raw?.[field];
+      if (typeof value !== "string" || !value.trim()) continue;
+      if (path.isAbsolute(value)) {
+        if (await isFile(value)) return value;
+      } else {
+        const bases = [path.dirname(file), ...baseDirs];
+        for (const base of bases) {
+          const resolved = path.resolve(base, value);
+          if (await isFile(resolved)) return resolved;
+        }
+      }
+    }
+  } catch {
+  }
+  return void 0;
+}
+async function integrationCandidateFromHome(home, name) {
+  const descriptors = [
+    path.join(home, "integrations", `${name}.json`),
+    path.join(home, "integrations", name, "integration.json")
+  ];
+  for (const descriptor of descriptors) {
+    const entry = await readIntegrationDescriptor(descriptor, [home]);
+    if (entry) return entry;
+  }
+  const legacy = path.join(home, "integrations", name, "main.js");
+  return await isFile(legacy) ? legacy : void 0;
+}
+function integrationBinaryName(name) {
+  return name === "web" ? "alp-web-integration" : `alp-${name}-integration`;
+}
+async function distributionRoots() {
+  const roots = [];
+  const argv = process.argv[1] ? await realpath(process.argv[1]).catch(() => process.argv[1]) : void 0;
+  if (argv) {
+    let directory = path.dirname(argv);
+    for (let depth = 0; depth < 4; depth += 1) {
+      roots.push(path.resolve(directory, ".."));
+      directory = path.resolve(directory, "..");
+    }
+    for (let ancestor = path.dirname(argv); ; ancestor = path.dirname(ancestor)) {
+      if (await isFile(path.join(ancestor, "package.json"))) roots.push(ancestor);
+      if (path.dirname(ancestor) === ancestor) break;
+    }
+  }
+  roots.push(process.cwd());
+  return [...new Set(roots)];
+}
+async function discoverIntegration(name = "web", options = {}) {
+  const envCandidates = [
+    process.env.ALP_WEB_INTEGRATION,
+    process.env.ALP_INTEGRATION_ENTRY,
+    name !== "web" ? process.env[`ALP_${name.toUpperCase()}_INTEGRATION`] : void 0
+  ].filter(Boolean);
+  for (const candidate of envCandidates) if (await isFile(candidate)) return candidate;
+  const home = options?.home ? path.resolve(options.home) : alpHome();
+  const fromHome = await integrationCandidateFromHome(home, name);
+  if (fromHome) return fromHome;
+  for (const root of await distributionRoots()) {
+    for (const descriptorPath of [path.join(root, "integrations", `${name}.json`), path.join(root, "integrations", name, "integration.json")]) {
+      const entry = await readIntegrationDescriptor(descriptorPath, [root]);
+      if (entry) return entry;
+    }
+  }
+  const binary = integrationBinaryName(name);
+  for (const directory of [...(process.env.PATH ?? "").split(path.delimiter).filter(Boolean), ...BIN_DIRECTORIES]) {
+    const candidate = await realpath(path.join(directory, binary)).catch(() => void 0);
+    if (candidate && await isFile(candidate)) return candidate;
+  }
+  return void 0;
+}
+function integrationAlive(lock) {
+  if (!lock || !Number.isSafeInteger(lock.pid)) return false;
+  try {
+    process.kill(lock.pid, 0);
+  } catch (error) {
+    return error?.code === "EPERM";
+  }
+  if (typeof lock.bootTime === "number" && Math.abs(lock.bootTime - bootTime()) > 30) return false;
+  return true;
+}
+async function startIntegration(nameOrOptions = "web") {
+  const options = typeof nameOrOptions === "string" ? { name: nameOrOptions } : nameOrOptions ?? {};
+  const name = options.name ?? "web";
+  const fs = await import("node:fs/promises");
+  const pathMod = await import("node:path");
+  const home = options.home ? pathMod.resolve(options.home) : alpHome();
+  const lockPath = pathMod.join(home, "integrations", `${name}.lock`);
+  const webPath = pathMod.join(home, `${name}.json`);
+  let settings = {};
+  try {
+    settings = JSON.parse(await fs.readFile(pathMod.join(home, "settings.json"), "utf8"));
+  } catch {
+  }
+  if (settings?.web?.enabled === false) {
+    throw new Error('ALP web app is disabled by settings ("web.enabled": false).');
+  }
+  const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+  const readLock2 = async () => {
+    try {
+      return JSON.parse(await fs.readFile(lockPath, "utf8"));
+    } catch {
+      return void 0;
+    }
+  };
+  const readWeb = async () => {
+    try {
+      return JSON.parse(await fs.readFile(webPath, "utf8"));
+    } catch {
+      return void 0;
+    }
+  };
+  async function waitForReady() {
+    const deadline = Date.now() + 3e4;
+    while (Date.now() < deadline) {
+      const lock2 = await readLock2();
+      if (lock2 && integrationAlive(lock2) && lock2.ready) {
+        const info = await readWeb();
+        if (info && info.pid === lock2.pid) return lock2;
+      }
+      await sleep(100);
+    }
+    const lock = await readLock2();
+    if (lock && !lock.ready) throw new Error("ALP web integration started but did not become ready; see ~/.alp/logs/integrations/paseo.log");
+    if (!lock) throw new Error("ALP web app is provided by an optional integration package. Install it (for example `npm install -g @anhlp/alp-paseo@beta`) and run `alp web` again.");
+    throw new Error("ALP web integration did not publish a matching web.json lock");
+  }
+  const existing = await readLock2();
+  if (existing && integrationAlive(existing)) {
+    return waitForReady();
+  }
+  const entry = await discoverIntegration(name, { home });
+  if (!entry) {
+    throw new Error("ALP web app is provided by an optional integration package. Install it (for example `npm install -g @anhlp/alp-paseo@beta`) and run `alp web` again.");
+  }
+  const { spawn: spawn2 } = await import("node:child_process");
+  const child = spawn2(process.execPath, [entry, "--service"], { stdio: "ignore", detached: true, env: { ...process.env, ALP_HOME: home } });
+  let spawnError = null;
+  child.on("error", (error) => {
+    spawnError = error;
+  });
+  let exited = false;
+  child.on("exit", (code) => {
+    if (code !== 0 && code !== null) exited = true;
+  });
+  child.unref();
+  if (spawnError) throw spawnError;
+  await sleep(150);
+  if (spawnError) throw spawnError;
+  if (exited) throw new Error("ALP web integration failed to start; see ~/.alp/logs/integrations/paseo.log");
+  return waitForReady();
+}
+export {
+  AlpClient,
+  AlpRpcError,
+  CLOSE_CODE,
+  MAX_FRAME,
+  PROTOCOL_VERSION,
+  acquireDaemonLock,
+  alpHome,
+  assertPrivateDirectory,
+  assertPrivateSocket,
+  bootTime,
+  connect,
+  connectSocket,
+  connectWebSocket,
+  createSocketTransport2 as createSocketTransport,
+  createWebSocketTransport,
+  daemonPaths,
+  discoverIntegration,
+  encodeFrame,
+  ensureDaemon,
+  findDaemonEntry,
+  lockAlive,
+  readLock,
+  redactUrl,
+  releaseDaemonLock,
+  startIntegration
+};

package/dist/ipc.d.ts

@@ -0,0 +1,42 @@
+/**
+ * The Node transport of the ALP client: a Unix socket or Windows named pipe carrying
+ * newline-delimited JSON (plans/reference/ALPD.md §3). Node-only; the portable engine
+ * (`@anhlp/alp-client/portable`) never imports it. Socket discovery, the private-socket checks
+ * and daemon startup stay in the Node entry (`connect`, `ensureDaemon`).
+ *
+ * @typedef {import('./rpc/client.js').AlpTransport} AlpTransport
+ * @typedef {import('./rpc/client.js').TransportClose} TransportClose
+ * @typedef {{ maxFrame?: number, maxBufferedBytes?: number }} SocketTransportOptions
+ *   `maxBufferedBytes` bounds what may wait in the socket's write buffer; a send beyond it fails
+ *   as `send_failed` instead of growing memory while the daemon does not read.
+ */
+/**
+ * Wraps a connected or still-connecting socket (writes made while it connects are queued by
+ * Node). The transport owns the socket from then on.
+ * @param {import('node:net').Socket} socket
+ * @param {SocketTransportOptions} [options]
+ * @returns {AlpTransport}
+ */
+export function createSocketTransport(socket: import("node:net").Socket, { maxFrame, maxBufferedBytes }?: SocketTransportOptions): AlpTransport;
+/**
+ * The Node transport of the ALP client: a Unix socket or Windows named pipe carrying
+ * newline-delimited JSON (plans/reference/ALPD.md §3). Node-only; the portable engine
+ * (`@anhlp/alp-client/portable`) never imports it. Socket discovery, the private-socket checks
+ * and daemon startup stay in the Node entry (`connect`, `ensureDaemon`).
+ */
+export type AlpTransport = import("./rpc/client.js").AlpTransport;
+/**
+ * The Node transport of the ALP client: a Unix socket or Windows named pipe carrying
+ * newline-delimited JSON (plans/reference/ALPD.md §3). Node-only; the portable engine
+ * (`@anhlp/alp-client/portable`) never imports it. Socket discovery, the private-socket checks
+ * and daemon startup stay in the Node entry (`connect`, `ensureDaemon`).
+ */
+export type TransportClose = import("./rpc/client.js").TransportClose;
+/**
+ * `maxBufferedBytes` bounds what may wait in the socket's write buffer; a send beyond it fails
+ * as `send_failed` instead of growing memory while the daemon does not read.
+ */
+export type SocketTransportOptions = {
+    maxFrame?: number;
+    maxBufferedBytes?: number;
+};

package/dist/ipc.js

@@ -0,0 +1,69 @@
+// packages/client/src/ipc.js
+import { MAX_FRAME } from "@anhlp/alp-protocol";
+import { AlpClientError } from "./rpc/errors.js";
+import { createLineDecoder } from "./rpc/framing.js";
+function createSocketTransport(socket, { maxFrame = MAX_FRAME, maxBufferedBytes = 4 * MAX_FRAME } = {}) {
+  const decoder = createLineDecoder({ maxFrame });
+  const messages = /* @__PURE__ */ new Set();
+  const closes = /* @__PURE__ */ new Set();
+  let ended;
+  const end = (close) => {
+    if (ended) return;
+    ended = close;
+    socket.off("data", onData);
+    messages.clear();
+    const listeners = [...closes];
+    closes.clear();
+    for (const listener of listeners) listener(close);
+  };
+  const onData = (chunk) => {
+    if (ended) return;
+    let frames;
+    try {
+      frames = decoder.push(chunk);
+    } catch {
+      const error = new AlpClientError("ALP daemon frame exceeds size limit", { reason: "protocol" });
+      socket.destroy();
+      return end({ error });
+    }
+    for (const frame of frames) {
+      if (ended) return;
+      for (const listener of [...messages]) listener(frame);
+    }
+  };
+  socket.setEncoding("utf8");
+  socket.on("data", onData);
+  socket.on("error", (error) => end({ error }));
+  socket.on("close", () => end({}));
+  if (socket.destroyed) end({});
+  const gone = () => socket.destroyed || socket.writableEnded;
+  return {
+    get state() {
+      return ended || gone() ? "closed" : "open";
+    },
+    send(frame) {
+      if (!ended && gone()) end({});
+      if (ended) throw new AlpClientError("ALP daemon connection closed", { reason: "send_failed" });
+      if (socket.writableLength + frame.length > maxBufferedBytes) throw new AlpClientError(`ALP socket write buffer is over ${maxBufferedBytes} bytes`, { reason: "send_failed" });
+      socket.write(`${frame}
+`);
+    },
+    onMessage(listener) {
+      if (ended) return () => false;
+      messages.add(listener);
+      return () => messages.delete(listener);
+    },
+    onClose(listener) {
+      if (ended) return () => false;
+      closes.add(listener);
+      return () => closes.delete(listener);
+    },
+    close() {
+      if (!socket.writableEnded) socket.end(() => socket.destroy());
+      end({});
+    }
+  };
+}
+export {
+  createSocketTransport
+};