@anhlp/alp-client 0.0.0-stage → 0.10.0

package/src/index.js

@@ -0,0 +1,408 @@
+import { spawn } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { readFile, realpath, stat } from 'node:fs/promises';
+import net from 'node:net';
+import os from 'node:os';
+import path from 'node:path';
+
+import { PROTOCOL_VERSION, MAX_FRAME, AlpRpcError, encodeFrame } from '@anhlp/alp-protocol';
+export { PROTOCOL_VERSION, MAX_FRAME, AlpRpcError, encodeFrame } from '@anhlp/alp-protocol';
+
+export function alpHome(env = process.env) {
+  return path.resolve(env.ALP_HOME || path.join(os.homedir(), '.alp'));
+}
+
+/** Windows uses named pipes; long Unix homes get a short socket in the temp directory. */
+export 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-${createHash('sha256').update(home).digest('hex').slice(0, 12)}.sock`);
+  return { home, lock: path.join(home, 'alpd.lock'), socket, log: path.join(home, 'logs', 'alpd.log'), install: path.join(home, 'alpd.json') };
+}
+
+const isFile = file => stat(file).then(info => info.isFile(), () => false);
+
+/** Global bin directories that a GUI app's PATH may lack. */
+const BIN_DIRECTORIES = [path.join(os.homedir(), '.npm-global', 'bin'), path.join(os.homedir(), '.local', 'bin'), '/opt/homebrew/bin', '/usr/local/bin'];
+
+/** The npm package that ships the `alp` command and alpd. */
+const CLI_PACKAGES = ['@anhlp/alp', '@anhlp/alp-cli'];
+
+/**
+ * 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 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(() => undefined);
+    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, () => undefined);
+    const entry = path.join(root, 'dist', 'alpd.js');
+    if (CLI_PACKAGES.includes(name) && await isFile(entry)) return entry;
+  }
+  return undefined;
+}
+
+/** Wall-clock boot time; a lock from an earlier boot is stale even if its pid is reused. */
+export function bootTime() {
+  return Math.round((Date.now() - os.uptime() * 1000) / 1000);
+}
+
+export async function readLock(home) {
+  try {
+    return JSON.parse(await readFile(daemonPaths(home).lock, 'utf8'));
+  } catch (error) {
+    if (error?.code === 'ENOENT' || error instanceof SyntaxError) return undefined;
+    throw error;
+  }
+}
+
+export 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';
+  }
+}
+
+/** One JSON-RPC 2.0 connection to alpd; events arrive as `event` notifications. */
+export class AlpClient {
+  #socket;
+  #sequence = 0;
+  #pending = new Map();
+  #events = new Set();
+  #closes = new Set();
+  #requestHandlers = new Set();
+  #closed = false;
+
+  constructor(socket) {
+    this.#socket = socket;
+    let buffer = '';
+    socket.setEncoding('utf8');
+    socket.on('data', chunk => {
+      buffer += chunk;
+      if (buffer.length > MAX_FRAME) { socket.destroy(new Error('ALP daemon frame exceeds size limit')); return; }
+      for (let index = buffer.indexOf('\n'); index >= 0; index = buffer.indexOf('\n')) {
+        const line = buffer.slice(0, index);
+        buffer = buffer.slice(index + 1);
+        if (line.trim()) this.#receive(line);
+      }
+    });
+    socket.on('close', () => this.#finish(new Error('ALP daemon connection closed')));
+    socket.on('error', error => this.#finish(error));
+  }
+
+  #receive(line) {
+    let message;
+    try { message = JSON.parse(line); } catch { this.#socket.destroy(new Error('Invalid frame from ALP daemon')); return; }
+    if (message.method === 'event') {
+      for (const listener of this.#events) listener(message.params);
+      return;
+    }
+    if (message.method && (message.id !== undefined && message.id !== null) && !Object.prototype.hasOwnProperty.call(message, 'result') && !Object.prototype.hasOwnProperty.call(message, 'error')) {
+      const handler = [...this.#requestHandlers][0];
+      if (handler) {
+        Promise.resolve().then(async () => {
+          try {
+            const result = await handler(message.method, message.params ?? {});
+            this.#socket.write(encodeFrame({ jsonrpc: '2.0', id: message.id, result: result === undefined ? {} : result }));
+          } catch (error) {
+            const code = (error && typeof error.code === 'number') ? error.code : 1000;
+            const msg = error instanceof Error ? error.message : String(error);
+            const data = (error && error.data !== undefined) ? { data: error.data } : {};
+            this.#socket.write(encodeFrame({ jsonrpc: '2.0', id: message.id, error: { code, message: msg.length > 2000 ? msg.slice(0,2000)+'...' : msg, ...data } }));
+          }
+        });
+        return;
+      }
+      this.#socket.write(encodeFrame({ jsonrpc: '2.0', id: message.id, error: { code: -32601, message: `Unknown method '${message.method}'` } }));
+      return;
+    }
+    const waiter = this.#pending.get(message.id);
+    if (!waiter) return;
+    this.#pending.delete(message.id);
+    if (message.error) waiter.reject(new AlpRpcError(message.error));
+    else waiter.resolve(message.result);
+  }
+
+  #finish(error) {
+    if (this.#closed) return;
+    this.#closed = true;
+    for (const waiter of this.#pending.values()) waiter.reject(error);
+    this.#pending.clear();
+    for (const listener of this.#closes) listener(error);
+  }
+
+  get closed() { return this.#closed; }
+
+  request(method, params = {}) {
+    if (this.#closed) return Promise.reject(new Error('ALP daemon connection closed'));
+    const id = ++this.#sequence;
+    return new Promise((resolve, reject) => {
+      this.#pending.set(id, { resolve, reject });
+      this.#socket.write(encodeFrame({ jsonrpc: '2.0', id, method, params }));
+    });
+  }
+
+  onEvent(listener) {
+    this.#events.add(listener);
+    return () => this.#events.delete(listener);
+  }
+
+  onRequest(handler) {
+    this.#requestHandlers.add(handler);
+    return () => this.#requestHandlers.delete(handler);
+  }
+
+  onClose(listener) {
+    this.#closes.add(listener);
+    return () => this.#closes.delete(listener);
+  }
+
+  close() {
+    this.#socket.end();
+    this.#finish(new Error('ALP daemon connection closed'));
+  }
+}
+
+/** Connects and performs the version handshake. */
+export async function connect(socketPath, client = { name: 'alp', version: '0' }) {
+  const socket = await new Promise((resolve, reject) => {
+    const candidate = net.createConnection(socketPath);
+    candidate.once('connect', () => { candidate.off('error', reject); resolve(candidate); });
+    candidate.once('error', reject);
+  });
+  const connection = new AlpClient(socket);
+  try {
+    await connection.request('daemon.hello', { protocolVersion: PROTOCOL_VERSION, client });
+  } catch (error) {
+    connection.close();
+    throw error;
+  }
+  return connection;
+}
+
+async function tail(file, lines = 30) {
+  try { return (await readFile(file, 'utf8')).split('\n').slice(-lines).join('\n'); } catch { return ''; }
+}
+
+/**
+ * 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 async function ensureDaemon({ home = alpHome(), entry = /** @type {string | undefined} */ (undefined), env = process.env, execPath = process.execPath, timeoutMs = 15_000 } = {}) {
+  const ready = async () => {
+    const lock = await readLock(home);
+    return lockAlive(lock) && lock.ready ? lock.socket : undefined;
+  };
+  const live = await ready();
+  if (live) return live;
+  if (!lockAlive(await readLock(home))) {
+    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',
+        windowsHide: true,
+      });
+      launcher.once('error', reject);
+      launcher.once('exit', code => code === 0 ? resolve() : reject(new Error(`ALP daemon launcher exited (${code})`)));
+    });
+  }
+  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 ? `\n${log}` : ''}`);
+}
+
+/** Registration descriptor field names, in priority order. */
+const 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 undefined;
+}
+
+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;
+  }
+  // Legacy single-file registration.
+  const legacy = path.join(home, 'integrations', name, 'main.js');
+  return (await isFile(legacy)) ? legacy : undefined;
+}
+
+function integrationBinaryName(name) {
+  return name === 'web' ? 'alp-web-integration' : `alp-${name}-integration`;
+}
+
+/** Distribution roots that may carry a bundled integration descriptor. */
+async function distributionRoots() {
+  const roots = [];
+  const argv = process.argv[1] ? await realpath(process.argv[1]).catch(() => process.argv[1]) : undefined;
+  if (argv) {
+    // The CLI runs from <distribution>/packages/cli/dist, so the distribution root is a few levels
+    // up. Resolve the real path first so a symlinked global bin still finds its own root.
+    let directory = path.dirname(argv);
+    for (let depth = 0; depth < 4; depth += 1) { roots.push(path.resolve(directory, '..')); directory = path.resolve(directory, '..'); }
+    // Every package ancestor may carry a bundled descriptor (a full distribution, or the plugin
+    // package installed next to it).
+    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;
+    }
+  }
+  // Also consider the current working directory for full distributions.
+  roots.push(process.cwd());
+  return [...new Set(roots)];
+}
+
+export async function discoverIntegration(name = 'web', options = {}) {
+  // Explicit environment override always wins.
+  const envCandidates = [
+    process.env.ALP_WEB_INTEGRATION,
+    process.env.ALP_INTEGRATION_ENTRY,
+    name !== 'web' ? process.env[`ALP_${name.toUpperCase()}_INTEGRATION`] : undefined,
+  ].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;
+
+  // A full distribution may describe a bundled integration relative to its own root.
+  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;
+    }
+  }
+
+  // Installed integration packages announce themselves on PATH.
+  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(() => undefined);
+    if (candidate && await isFile(candidate)) return candidate;
+  }
+  return undefined;
+}
+
+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;
+}
+
+export 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`);
+
+  // Clear, actionable diagnostics for a disabled optional integration.
+  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 readLock = async () => {
+    try { return JSON.parse(await fs.readFile(lockPath, 'utf8')); } catch { return undefined; }
+  };
+  const readWeb = async () => {
+    try { return JSON.parse(await fs.readFile(webPath, 'utf8')); } catch { return undefined; }
+  };
+
+  // The authoritative check: the ready integration lock and live web.json must name the same pid.
+  // A loser of a concurrent start accepts the winning pid after its own contender has exited or
+  // the lock already names the winner.
+  async function waitForReady() {
+    const deadline = Date.now() + 30_000;
+    while (Date.now() < deadline) {
+      const lock = await readLock();
+      if (lock && integrationAlive(lock) && lock.ready) {
+        const info = await readWeb();
+        if (info && info.pid === lock.pid) return lock;
+      }
+      await sleep(100);
+    }
+    const lock = await readLock();
+    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 alp-paseo-plugin`) and run `alp web` again.');
+    throw new Error('ALP web integration did not publish a matching web.json lock');
+  }
+
+  const existing = await readLock();
+  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 alp-paseo-plugin`) and run `alp web` again.');
+  }
+
+  const { spawn } = await import('node:child_process');
+  // The child is detached with its stdio ignored, so it cannot rely on the parent's console. `--service`
+  // is the generic contract: the entry writes its own log (the path its error messages advertise) and
+  // keeps the process alive as a service. `--register` still prints to stdout and is not passed here.
+  const child = spawn(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;
+  // Give the process a moment to fail immediately on missing entry or bad permissions.
+  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();
+}

package/src/library-test.js

@@ -0,0 +1,41 @@
+import path from 'node:path';
+import { AlpError } from '@anhlp/alp-core/errors';
+import { getEntry } from '@anhlp/alp-core/library-edit';
+import { runHook, samplePayload } from '@anhlp/alp-core/hook-run';
+import { normalizeMcp } from '@anhlp/alp-core/validation';
+import { probeMcp } from './mcp-probe.js';
+import { probeAcp } from './acp-probe.js';
+import { probeAntigravity } from './antigravity-probe.js';
+import { loadProvider } from '@anhlp/alp-core/providers';
+
+/**
+ * Tries an MCP server, a hook or an ACP provider out (ALPD §43, §46). An MCP server is
+ * started and its tools listed; a provider is started and initialized; a hook runs once with a sample payload for its event, in the project (or the
+ * library when there is none), with the variables ALP gives hooks.
+ */
+export async function testEntry(kind, name, { root, library, templates, scope, timeoutMs } = {}) {
+  const entry = await getEntry(kind, name, { root, library, templates, scope });
+  const home = entry.source === 'project' ? path.join(path.resolve(root), '.alp') : library;
+  if (kind === 'mcp') {
+    const server = normalizeMcp({ mcpServers: { [name]: entry.content.server } }, path.join(home, 'mcp'), `${name}.json`).mcpServers[name];
+    const result = await probeMcp(server, { cwd: root ? path.resolve(root) : library, ...(timeoutMs ? { timeoutMs } : {}) });
+    return { kind, name, source: entry.source, ok: true, ...result };
+  }
+  if (kind === 'hooks') {
+    const hook = entry.content.hook;
+    const project = root ? path.resolve(root) : undefined;
+    const payload = samplePayload(hook.event, { project, agent: hook.match?.agent ?? 'main' });
+    const env = { ALP_EVENT: hook.event, ALP_SESSION: payload.session, ALP_AGENT: payload.agent, ALP_PROJECT: project ?? '', ALP_TASK: payload.task ?? '' };
+    const result = await runHook(hook, payload, { cwd: project ?? library, env, ...(timeoutMs ? { timeoutMs } : {}) });
+    const ok = result.exitCode === 0 && !result.timedOut;
+    return { kind, name, source: entry.source, ok, ...(hook.blocking && !ok ? { wouldBlock: true } : {}), payload, ...result };
+  }
+  if (kind === 'providers') {
+    const provider = await loadProvider(library, name);
+    const result = provider.kind === 'antigravity'
+      ? await probeAntigravity(provider, { cwd: root ? path.resolve(root) : library, ...(timeoutMs ? { timeoutMs } : {}) })
+      : await probeAcp(provider, { cwd: root ? path.resolve(root) : library, ...(timeoutMs ? { timeoutMs } : {}) });
+    return { kind, name, source: entry.source, ok: true, ...result };
+  }
+  throw new AlpError('INVALID_KIND', `Only mcp servers, hooks and providers can be tested, not ${kind}`);
+}

package/src/mcp-probe.js

@@ -0,0 +1,115 @@
+import { spawn } from 'node:child_process';
+import { createInterface } from 'node:readline';
+
+const PROTOCOL = '2025-06-18';
+const client = { name: 'alp', version: '1' };
+
+/**
+ * Starts an MCP server once and lists its tools (ALPD §43), for the Test button and
+ * `alp mcp test`. `server` is a normalized definition: { command, args, env, cwd } for
+ * stdio, or { url, headers } for HTTP. The server is stopped afterwards.
+ * @returns {Promise<{ server?: { name?: string, version?: string }, tools: Array<{ name: string, description?: string }> }>}
+ */
+export async function probeMcp(server, { cwd, timeoutMs = 15_000 } = {}) {
+  const session = server.url ? await httpSession(server, timeoutMs) : stdioSession(server, cwd, timeoutMs);
+  try {
+    const init = await session.request('initialize', { protocolVersion: PROTOCOL, capabilities: {}, clientInfo: client });
+    await session.notify('notifications/initialized');
+    const tools = [];
+    let cursor;
+    for (let page = 0; page < 20; page++) {
+      const result = await session.request('tools/list', cursor ? { cursor } : {});
+      for (const tool of result.tools ?? []) tools.push({ name: tool.name, ...(tool.description ? { description: tool.description } : {}) });
+      cursor = result.nextCursor;
+      if (!cursor) break;
+    }
+    return { ...(init.serverInfo ? { server: { name: init.serverInfo.name, version: init.serverInfo.version } } : {}), tools };
+  } finally {
+    await session.close();
+  }
+}
+
+/** A JSON-RPC session with a process over stdio; ACP providers are probed with it too. */
+export function stdioSession(server, cwd, timeoutMs) {
+  // Its own process group, so a launcher such as npx is stopped with what it started.
+  const child = spawn(server.command, server.args ?? [], { cwd: server.cwd ?? cwd, env: { ...process.env, ...(server.env ?? {}) }, stdio: ['pipe', 'pipe', 'pipe'], detached: true });
+  const signal = name => { try { process.kill(-child.pid, name); } catch { child.kill(name); } };
+  let stderr = '';
+  child.stderr.setEncoding('utf8');
+  child.stderr.on('data', chunk => { if (stderr.length < 4000) stderr += chunk; });
+  const pending = new Map();
+  let exited;
+  const failAll = error => { for (const { reject } of pending.values()) reject(error); pending.clear(); };
+  child.on('error', error => { exited = error; failAll(error); });
+  child.on('exit', code => {
+    exited = new Error(`${server.command} exited (${code ?? 'signal'})${stderr.trim() ? `: ${stderr.trim().split('\n').slice(-3).join(' ')}` : ''}`);
+    failAll(exited);
+  });
+  createInterface({ input: child.stdout }).on('line', line => {
+    let message;
+    try { message = JSON.parse(line); } catch { return; }
+    const waiting = pending.get(message.id);
+    if (!waiting) return;
+    pending.delete(message.id);
+    if (message.error) waiting.reject(new Error(`${message.error.message ?? 'MCP error'} (${message.error.code})`));
+    else waiting.resolve(message.result ?? {});
+  });
+  child.stdin.on('error', () => {});
+  let id = 0;
+  return {
+    request(method, params) {
+      if (exited) return Promise.reject(exited);
+      const current = ++id;
+      return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => { pending.delete(current); reject(new Error(`${method} got no answer within ${timeoutMs / 1000} s`)); }, timeoutMs);
+        pending.set(current, { resolve: value => { clearTimeout(timer); resolve(value); }, reject: error => { clearTimeout(timer); reject(error); } });
+        child.stdin.write(JSON.stringify({ jsonrpc: '2.0', id: current, method, params }) + '\n');
+      });
+    },
+    async notify(method) { if (!exited) child.stdin.write(JSON.stringify({ jsonrpc: '2.0', method }) + '\n'); },
+    async close() {
+      if (child.exitCode !== null || child.signalCode !== null) return;
+      const done = new Promise(resolve => child.once('exit', resolve));
+      child.stdin.end();
+      signal('SIGTERM');
+      const timer = setTimeout(() => signal('SIGKILL'), 2000);
+      await done;
+      clearTimeout(timer);
+    },
+  };
+}
+
+async function httpSession(server, timeoutMs) {
+  let sessionId;
+  let id = 0;
+  const post = async body => {
+    const response = await fetch(server.url, {
+      method: 'POST',
+      headers: { ...(server.headers ?? {}), 'content-type': 'application/json', accept: 'application/json, text/event-stream', ...(sessionId ? { 'mcp-session-id': sessionId } : {}), 'mcp-protocol-version': PROTOCOL },
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+    sessionId = response.headers.get('mcp-session-id') ?? sessionId;
+    if (!response.ok) throw new Error(`${server.url} answered ${response.status} ${response.statusText}`);
+    return response;
+  };
+  return {
+    async request(method, params) {
+      const current = ++id;
+      const response = await post({ jsonrpc: '2.0', id: current, method, params });
+      const text = await response.text();
+      // A streamable HTTP server answers with JSON or with server-sent events.
+      const messages = (response.headers.get('content-type') ?? '').includes('text/event-stream')
+        ? text.split('\n').filter(line => line.startsWith('data:')).map(line => { try { return JSON.parse(line.slice(5)); } catch { return undefined; } })
+        : [JSON.parse(text)];
+      const message = messages.find(entry => entry?.id === current);
+      if (!message) throw new Error(`${method}: no answer in the response`);
+      if (message.error) throw new Error(`${message.error.message ?? 'MCP error'} (${message.error.code})`);
+      return message.result ?? {};
+    },
+    async notify(method) { await post({ jsonrpc: '2.0', method }); },
+    async close() {
+      if (sessionId) await fetch(server.url, { method: 'DELETE', headers: { ...(server.headers ?? {}), 'mcp-session-id': sessionId }, signal: AbortSignal.timeout(timeoutMs) }).catch(() => {});
+    },
+  };
+}

package/src/prompt.js

@@ -0,0 +1,64 @@
+import { emitKeypressEvents } from 'node:readline';
+
+const dim = text => `\x1b[2m${text}\x1b[22m`;
+const cyan = text => `\x1b[36m${text}\x1b[39m`;
+
+export class Cancelled extends Error {
+  constructor() { super('Setup cancelled.'); }
+}
+
+/**
+ * A select box in the terminal: ↑/↓ (or k/j) move, Enter picks, Ctrl-C or Esc cancels.
+ * Choices are { label, value, hint? }; `initial` is the value highlighted first.
+ * @template T
+ * @param {{ message: string, choices: Array<{ label: string, value: T, hint?: string }>, initial?: T }} question
+ * @param {{ input?: NodeJS.ReadStream, output?: NodeJS.WriteStream }} [io]
+ * @returns {Promise<T>}
+ */
+export function select({ message, choices, initial }, { input = process.stdin, output = process.stdout } = {}) {
+  let index = Math.max(0, choices.findIndex(choice => choice.value === initial));
+  let drawn = 0;
+  const draw = () => {
+    if (drawn) output.write(`\x1b[${drawn}A\x1b[0J`);
+    const lines = [`${cyan('?')} ${message} ${dim('(↑/↓, Enter)')}`, ...choices.map((choice, at) =>
+      at === index ? cyan(`❯ ${choice.label}`) + (choice.hint ? ` ${dim(choice.hint)}` : '') : `  ${choice.label}${choice.hint ? ` ${dim(choice.hint)}` : ''}`)];
+    output.write(lines.join('\n') + '\n');
+    drawn = lines.length;
+  };
+  return new Promise((resolve, reject) => {
+    emitKeypressEvents(input);
+    const raw = input.isRaw;
+    input.setRawMode?.(true);
+    input.resume();
+    output.write('\x1b[?25l');
+    const done = (settle, value) => {
+      input.off('keypress', onKey);
+      input.setRawMode?.(raw ?? false);
+      input.pause();
+      output.write(`\x1b[${drawn}A\x1b[0J\x1b[?25h`);
+      if (settle === resolve) output.write(`${cyan('✔')} ${message} ${cyan(choices[index].label)}\n`);
+      settle(value);
+    };
+    const onKey = (text, key = {}) => {
+      if ((key.ctrl && key.name === 'c') || key.name === 'escape') return done(reject, new Cancelled());
+      if (key.name === 'return' || key.name === 'enter') return done(resolve, choices[index].value);
+      if (key.name === 'up' || key.name === 'k') index = (index + choices.length - 1) % choices.length;
+      else if (key.name === 'down' || key.name === 'j') index = (index + 1) % choices.length;
+      else return;
+      draw();
+    };
+    input.on('keypress', onKey);
+    draw();
+  });
+}
+
+/**
+ * A line of text, for a value the list does not offer.
+ * @param {string} message
+ * @param {{ input?: NodeJS.ReadStream, output?: NodeJS.WriteStream }} [io]
+ */
+export async function text(message, { input = process.stdin, output = process.stdout } = {}) {
+  const { createInterface } = await import('node:readline/promises');
+  const rl = createInterface({ input, output });
+  try { return (await rl.question(`${cyan('?')} ${message} `)).trim(); } finally { rl.close(); }
+}