@anhlp/alp-client 0.0.1-beta.3 → 0.0.1-beta.4

package/README.md

@@ -11,13 +11,18 @@ and setup helpers.
 - `@anhlp/alp-client` (Node): everything above plus `connect`, `AlpClient`, `connectSocket`,
   `ensureDaemon`, the private-socket checks and lock helpers, unchanged for existing callers.
 - `@anhlp/alp-client/ipc` (Node): `createSocketTransport` for a Unix socket or named pipe.
+- `@anhlp/alp-client/integration-lock` (Node): `createIntegrationLock(home, name)`, the single-owner
+  lock of one integration service at `<home>/integrations/<name>.lock`, serialized by the exclusive
+  guard directory `<name>.lock.reclaim`. Each instance is single-use (`acquire`, then `setReady` and
+  `release` while it owns the lock); its recovery rules are in
+  [docs/modular-monorepo.md](../../docs/modular-monorepo.md).
 
 Timeouts and aborts end only the caller's wait, and nothing is ever resent after a disconnect.
 See [docs/alp/client-sdk.md](../../docs/alp/client-sdk.md) for the transport contract, the
 request lifecycle, the old-to-new API table and what still waits on the protocol (Task 06) and
 the gateway (Task 08).
 
-`startIntegration` discovers an optional integration's descriptor and starts it detached with `--service`, so the entry writes its own log; discovery and the selected `ALP_HOME` are pinned by tests. Restarting is non-destructive: a daemon left running by an older install is reported as older than the current CLI and is never killed in place.
+`startIntegration({ name, entry, home, args })` (or `startIntegration(name)`; `name` defaults to `web`) discovers an optional integration's descriptor and starts it detached with `--service` and then `args`, so the entry writes its own log; discovery and the selected `ALP_HOME` are pinned by tests. `name` is a single lowercase path segment (`assertIntegrationName`). With `entry`, that script runs with the current Node and no descriptor, environment or PATH discovery happens; a missing entry is an error even when a live owner would be reused. `web` is alp-web, the service of the ALP CLI (`alp web`): it is never discovered, so it needs its `entry`, and `"web": { "enabled": false }` in the home's settings refuses it and no other integration. Everything once registered under `web` (`integrations/web.json`, the `alp-web-integration` binary, `ALP_WEB_INTEGRATION`) is the Paseo integration from before its rename; `discoverIntegration('paseo')` reads `ALP_PASEO_INTEGRATION`, then `ALP_WEB_INTEGRATION` for one release, then `ALP_INTEGRATION_ENTRY`. Errors name the integration, the entry and its log under `<home>/logs/integrations`. Either way a live owner of `integrations/<name>.lock` is reused, and the call resolves once that lock is ready and `<home>/<name>.json` names the same pid. Restarting is non-destructive: a daemon left running by an older install is reported as older than the current CLI and is never killed in place.
 
 Build: `npm run build --workspace=@anhlp/alp-client`. Test: `npm run test --workspace=@anhlp/alp-client`.
 

package/dist/index.d.ts

@@ -21,6 +21,13 @@ export function findDaemonEntry({ home, env, candidates }?: {
     env?: NodeJS.ProcessEnv | undefined;
     candidates?: (string | undefined)[] | undefined;
 }): Promise<string | undefined>;
+/**
+ * Integration names are single lowercase path segments: they name `<home>/integrations/<name>.lock`,
+ * its guard and `<home>/<name>.json`. Returns the name, or throws a TypeError.
+ * @param {unknown} name
+ * @returns {string}
+ */
+export function assertIntegrationName(name: unknown): string;
 /** 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>;
@@ -95,8 +102,34 @@ export function ensureDaemon({ home, entry, env, execPath, timeoutMs, lifecycleL
     timeoutMs?: number | undefined;
     lifecycleLocked?: boolean | undefined;
 }): Promise<any>;
-export function discoverIntegration(name?: string, options?: {}): Promise<string | undefined>;
-export function startIntegration(nameOrOptions?: string): Promise<any>;
+/**
+ * The entry of integration `name`: an environment override, a descriptor under the home or a
+ * distribution root, or an `alp-<name>-integration` binary. Discovery never returns an entry for
+ * `web`: that name belongs to alp-web, which ships with the CLI and is started with its explicit
+ * entry. Everything once registered under `web` (the descriptor `integrations/web.json`, the
+ * `alp-web-integration` binary, `ALP_WEB_INTEGRATION`) is the Paseo integration from before its
+ * rename to `paseo`, which must never run under the web lock. `ALP_WEB_INTEGRATION` is read for
+ * `paseo` only, after `ALP_PASEO_INTEGRATION`, for one release (like the alp-web-integration alias).
+ * @param {string} [name]
+ * @param {{ home?: string }} [options]
+ */
+export function discoverIntegration(name?: string, options?: {
+    home?: string;
+}): Promise<string | undefined>;
+/**
+ * Starts integration `name` (default `web`) detached with `--service` (then `args`) unless its lock
+ * already names a live owner, then waits until its ready lock and `<home>/<name>.json` name the same
+ * pid. `entry` names the script to run with this Node and skips descriptor, environment and PATH
+ * discovery; `web` (alp-web) is never discovered, so it needs its entry. `"web": { "enabled": false }`
+ * in the home's settings.json refuses `web` only.
+ * @param {string | { name?: string, entry?: string, home?: string, args?: string[] }} [nameOrOptions]
+ */
+export function startIntegration(nameOrOptions?: string | {
+    name?: string;
+    entry?: string;
+    home?: string;
+    args?: string[];
+}): Promise<any>;
 export * from "./portable.js";
 export { createSocketTransport } from "./ipc.js";
 /**
@@ -110,6 +143,8 @@ export class AlpClient extends AlpRpcClient {
      * @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);
+    /** Host features captured by connect's handshake. @type {readonly string[]} */
+    capabilities: readonly string[];
 }
 import { AlpRpcClient } from './rpc/client.js';
 export { PROTOCOL_VERSION, MAX_FRAME, AlpRpcError, encodeFrame } from "@anhlp/alp-protocol";

package/dist/index.js

@@ -98,6 +98,10 @@ async function findDaemonEntry({ home = alpHome(), env = process.env, candidates
   }
   return void 0;
 }
+function assertIntegrationName(name) {
+  if (typeof name !== "string" || !/^[a-z0-9][a-z0-9-]*$/.test(name)) throw new TypeError(`Invalid integration name: ${JSON.stringify(name)}`);
+  return name;
+}
 function bootTime() {
   return Math.round((Date.now() - os.uptime() * 1e3) / 1e3);
 }
@@ -144,6 +148,8 @@ async function releaseDaemonLock(home) {
   });
 }
 var AlpClient = class extends AlpRpcClient {
+  /** Host features captured by connect's handshake. @type {readonly string[]} */
+  capabilities = [];
   /**
    * @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]
@@ -172,7 +178,8 @@ async function connectSocket(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);
+    const greeting = await hello(connection, client);
+    connection.capabilities = Object.freeze(Array.isArray(greeting.capabilities) ? greeting.capabilities.filter((value) => typeof value === "string") : []);
   } catch (error) {
     connection.close();
     throw error;
@@ -346,7 +353,7 @@ async function integrationCandidateFromHome(home, name) {
   return await isFile(legacy) ? legacy : void 0;
 }
 function integrationBinaryName(name) {
-  return name === "web" ? "alp-web-integration" : `alp-${name}-integration`;
+  return `alp-${name}-integration`;
 }
 async function distributionRoots() {
   const roots = [];
@@ -366,10 +373,12 @@ async function distributionRoots() {
   return [...new Set(roots)];
 }
 async function discoverIntegration(name = "web", options = {}) {
+  assertIntegrationName(name);
+  if (name === "web") return void 0;
   const envCandidates = [
-    process.env.ALP_WEB_INTEGRATION,
-    process.env.ALP_INTEGRATION_ENTRY,
-    name !== "web" ? process.env[`ALP_${name.toUpperCase()}_INTEGRATION`] : void 0
+    process.env[`ALP_${name.toUpperCase()}_INTEGRATION`],
+    name === "paseo" ? process.env.ALP_WEB_INTEGRATION : void 0,
+    process.env.ALP_INTEGRATION_ENTRY
   ].filter(Boolean);
   for (const candidate of envCandidates) if (await isFile(candidate)) return candidate;
   const home = options?.home ? path.resolve(options.home) : alpHome();
@@ -398,21 +407,46 @@ function integrationAlive(lock) {
   if (typeof lock.bootTime === "number" && Math.abs(lock.bootTime - bootTime()) > 30) return false;
   return true;
 }
+function integrationText(name, home) {
+  const logs = path.join(home, "logs", "integrations");
+  if (name === "web") return {
+    what: "alp web",
+    log: path.join(logs, "alp-web.log"),
+    missing: "alp web runs the alp-web service of the ALP CLI, which is started with its entry (packages/cli/dist/alp-web.js); run `alp web`"
+  };
+  if (name === "paseo") return {
+    what: "The Paseo integration",
+    log: path.join(logs, "paseo.log"),
+    missing: "The Paseo integration is an optional integration package. Install it (for example `npm install -g @anhlp/alp-paseo@beta`), then run the command again."
+  };
+  return {
+    what: `ALP integration ${name}`,
+    log: path.join(logs, `${name}.log`),
+    missing: `ALP integration ${name} is not installed: no ALP_${name.toUpperCase()}_INTEGRATION, descriptor <home>/integrations/${name}.json or alp-${name}-integration binary was found.`
+  };
+}
 async function startIntegration(nameOrOptions = "web") {
   const options = typeof nameOrOptions === "string" ? { name: nameOrOptions } : nameOrOptions ?? {};
-  const name = options.name ?? "web";
+  const name = assertIntegrationName(options.name ?? "web");
+  if (options.entry !== void 0 && (typeof options.entry !== "string" || !options.entry)) throw new TypeError("startIntegration entry must be a non-empty path");
+  const args = options.args ?? [];
+  if (!Array.isArray(args) || !args.every((arg) => typeof arg === "string")) throw new TypeError("startIntegration args must be a list of strings");
   const fs = await import("node:fs/promises");
   const pathMod = await import("node:path");
   const home = options.home ? pathMod.resolve(options.home) : alpHome();
+  const text = integrationText(name, home);
+  const explicit = options.entry !== void 0 ? pathMod.resolve(options.entry) : void 0;
+  if (explicit !== void 0 && !await isFile(explicit)) throw new Error(`${text.what}: integration entry not found: ${explicit}`);
   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 started = explicit ? ` (entry ${explicit})` : "";
+  if (name === "web") {
+    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 is disabled by settings ("web.enabled": false).');
   }
   const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
   const readLock2 = async () => {
@@ -440,20 +474,18 @@ async function startIntegration(nameOrOptions = "web") {
       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");
+    if (lock && !lock.ready) throw new Error(`${text.what}${started} started but did not become ready; see ${text.log}`);
+    if (!lock) throw new Error(explicit ? `${text.what}${started} did not start; see ${text.log}` : text.missing);
+    throw new Error(`${text.what}${started} did not publish a ${name}.json matching its lock; see ${text.log}`);
   }
   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 entry = explicit ?? await discoverIntegration(name, { home });
+  if (!entry) throw new Error(text.missing);
   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 } });
+  const child = spawn2(process.execPath, [entry, "--service", ...args], { stdio: "ignore", detached: true, env: { ...process.env, ALP_HOME: home } });
   let spawnError = null;
   child.on("error", (error) => {
     spawnError = error;
@@ -466,7 +498,7 @@ async function startIntegration(nameOrOptions = "web") {
   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");
+  if (exited) throw new Error(`${text.what}${explicit ? started : ` (${entry})`} failed to start; see ${text.log}`);
   return waitForReady();
 }
 export {
@@ -477,6 +509,7 @@ export {
   PROTOCOL_VERSION,
   acquireDaemonLock,
   alpHome,
+  assertIntegrationName,
   assertPrivateDirectory,
   assertPrivateSocket,
   bootTime,

package/dist/integration-lock.d.ts

@@ -0,0 +1,35 @@
+/**
+ * @typedef {{ pid: number, bootTime: number, startedAt: string, ready: boolean, lockVersion?: number, owner?: string }} IntegrationLockRecord
+ * @typedef {{
+ *   acquire(): Promise<{ acquired: boolean, lock: IntegrationLockRecord }>,
+ *   setReady(ready: boolean): Promise<boolean>,
+ *   release(): Promise<boolean>,
+ * }} IntegrationLock
+ */
+/**
+ * The single-owner lock of one integration service, at `<home>/integrations/<name>.lock`, with its
+ * mutation guard `<name>.lock.reclaim`. Each instance is single-use: acquire once, then setReady and
+ * release while it owns the lock.
+ *
+ * Single-host, same PID namespace, private local filesystem only. Never reap the mutation guard.
+ * @param {string} home the ALP_HOME the integration runs under
+ * @param {string} name the integration name, for example `web`
+ * @returns {IntegrationLock}
+ */
+export function createIntegrationLock(home: string, name: string): IntegrationLock;
+export type IntegrationLockRecord = {
+    pid: number;
+    bootTime: number;
+    startedAt: string;
+    ready: boolean;
+    lockVersion?: number;
+    owner?: string;
+};
+export type IntegrationLock = {
+    acquire(): Promise<{
+        acquired: boolean;
+        lock: IntegrationLockRecord;
+    }>;
+    setReady(ready: boolean): Promise<boolean>;
+    release(): Promise<boolean>;
+};

package/dist/integration-lock.js

@@ -0,0 +1,179 @@
+// packages/client/src/integration-lock.js
+import { randomUUID } from "node:crypto";
+import { mkdir, open, rename, rmdir, unlink } from "node:fs/promises";
+import path from "node:path";
+import { assertIntegrationName, bootTime } from "./index.js";
+function createIntegrationLock(home, name) {
+  const file = path.join(home, "integrations", `${assertIntegrationName(name)}.lock`);
+  const guard = `${file}.reclaim`;
+  let phase = "new";
+  let owned;
+  const recovery = (reason) => new Error(`${reason}. Stop ALL integration processes using this ALP_HOME before manual lock-only recovery of ${file} and ${guard}; see docs/modular-monorepo.md`);
+  async function guarded(run) {
+    await mkdir(path.dirname(file), { recursive: true, mode: 448 });
+    const deadline = Date.now() + 2e4;
+    for (; ; ) {
+      try {
+        await mkdir(guard, { mode: 448 });
+        break;
+      } catch (error) {
+        if (
+          /** @type {any} */
+          error?.code !== "EEXIST"
+        ) throw error;
+        if (Date.now() >= deadline) throw recovery("Integration mutation guard remains busy or abandoned");
+        await new Promise((resolve) => setTimeout(resolve, 25));
+      }
+    }
+    const token = path.join(guard, `owner-${process.pid}-${randomUUID()}`);
+    try {
+      const handle = await open(token, "wx", 384);
+      await handle.close();
+    } catch (error) {
+      throw recovery(`Integration guard initialization failed: ${String(error)}`);
+    }
+    try {
+      return await run();
+    } finally {
+      try {
+        await unlink(token);
+      } catch (error) {
+        throw recovery(
+          /** @type {any} */
+          error?.code === "ENOENT" ? "Integration guard ownership was lost" : `Integration guard token cleanup failed: ${String(error)}`
+        );
+      }
+      try {
+        await rmdir(guard);
+      } catch (error) {
+        throw recovery(`Integration guard cleanup failed: ${String(error)}`);
+      }
+    }
+  }
+  async function snapshot() {
+    let handle;
+    try {
+      handle = await open(file, "r");
+    } catch (error) {
+      if (
+        /** @type {any} */
+        error?.code === "ENOENT"
+      ) return void 0;
+      throw error;
+    }
+    try {
+      const info = await handle.stat();
+      const raw = await handle.readFile("utf8");
+      let value;
+      try {
+        value = JSON.parse(raw);
+      } catch {
+        value = void 0;
+      }
+      return { value, info };
+    } finally {
+      await handle.close();
+    }
+  }
+  function complete(value) {
+    return value && Number.isSafeInteger(value.pid) && value.pid > 0 && typeof value.bootTime === "number" && Number.isFinite(value.bootTime) && value.bootTime > 0 && typeof value.startedAt === "string" && Number.isFinite(Date.parse(value.startedAt)) && typeof value.ready === "boolean" && (value.lockVersion === void 0 && value.owner === void 0 || value.lockVersion === 1 && typeof value.owner === "string" && /^[a-f0-9-]{36}$/.test(value.owner));
+  }
+  function dead(value) {
+    try {
+      process.kill(value.pid, 0);
+      return false;
+    } catch (error) {
+      if (
+        /** @type {any} */
+        error?.code !== "ESRCH"
+      ) return false;
+      if (Math.abs(value.bootTime - bootTime()) > 30) throw recovery("Integration owner boot context is uncertain");
+      return true;
+    }
+  }
+  function matches(current) {
+    return !!owned && current?.value?.owner === owned.owner && current.info.dev === owned.dev && current.info.ino === owned.ino;
+  }
+  return {
+    async acquire() {
+      if (phase !== "new") throw new Error("Integration lock instance has already been used");
+      phase = "acquiring";
+      try {
+        return await guarded(async () => {
+          const current = await snapshot();
+          if (current) {
+            if (!complete(current.value)) throw recovery("Integration lock is malformed, incomplete or unsupported");
+            if (!dead(current.value)) {
+              phase = "retired";
+              return { acquired: false, lock: current.value };
+            }
+            await unlink(file);
+          }
+          const value = { pid: process.pid, bootTime: bootTime(), startedAt: (/* @__PURE__ */ new Date()).toISOString(), ready: false, lockVersion: 1, owner: randomUUID() };
+          const handle = await open(file, "wx", 384);
+          let info;
+          try {
+            await handle.writeFile(JSON.stringify(value));
+            info = await handle.stat();
+          } finally {
+            await handle.close();
+          }
+          owned = { owner: value.owner, dev: info.dev, ino: info.ino };
+          phase = "owned";
+          return { acquired: true, lock: value };
+        });
+      } catch (error) {
+        phase = "retired";
+        owned = void 0;
+        throw error;
+      }
+    },
+    async setReady(ready) {
+      if (phase !== "owned") return false;
+      return guarded(async () => {
+        if (phase !== "owned") return false;
+        const current = await snapshot();
+        if (!current || !matches(current)) {
+          phase = "retired";
+          owned = void 0;
+          return false;
+        }
+        const value = { ...current.value, ready };
+        const tmp = `${file}.${randomUUID()}.tmp`;
+        const handle = await open(tmp, "wx", 384);
+        let info;
+        try {
+          try {
+            await handle.writeFile(JSON.stringify(value));
+            info = await handle.stat();
+          } finally {
+            await handle.close();
+          }
+          await rename(tmp, file);
+          owned = { owner: value.owner, dev: info.dev, ino: info.ino };
+          return true;
+        } finally {
+          await unlink(tmp).catch((error) => {
+            if (error?.code !== "ENOENT") throw error;
+          });
+        }
+      });
+    },
+    async release() {
+      if (phase !== "owned") return false;
+      return guarded(async () => {
+        if (phase !== "owned") return false;
+        const current = await snapshot();
+        const ours = matches(current);
+        phase = "retired";
+        owned = void 0;
+        if (!ours) return false;
+        await unlink(file);
+        return true;
+      });
+    }
+  };
+}
+export {
+  createIntegrationLock
+};

package/dist/portable.d.ts

@@ -16,3 +16,4 @@ export { AlpClientError, CLIENT_ERROR, isAlpClientError } from "./rpc/errors.js"
 export { createLineDecoder, utf8Length } from "./rpc/framing.js";
 export { MAX_TIMER_MS, timerDelay } from "./rpc/timers.js";
 export { backoffDelay, createReconnectingClient, retryable } from "./rpc/reconnect.js";
+export { attachments, base64Encode, conversation, sha256Hex, workspaceRegistry } from "./rpc/registry.js";

package/dist/portable.js

@@ -6,6 +6,7 @@ import { createLineDecoder, utf8Length } from "./rpc/framing.js";
 import { MAX_TIMER_MS, timerDelay } from "./rpc/timers.js";
 import { hello } from "./rpc/handshake.js";
 import { backoffDelay, createReconnectingClient, retryable } from "./rpc/reconnect.js";
+import { attachments, base64Encode, conversation, sha256Hex, workspaceRegistry } from "./rpc/registry.js";
 export {
   AlpClientError,
   AlpRpcClient,
@@ -16,12 +17,17 @@ export {
   MAX_FRAME,
   MAX_TIMER_MS,
   PROTOCOL_VERSION,
+  attachments,
   backoffDelay,
+  base64Encode,
+  conversation,
   createLineDecoder,
   createReconnectingClient,
   hello,
   isAlpClientError,
   retryable,
+  sha256Hex,
   timerDelay,
-  utf8Length
+  utf8Length,
+  workspaceRegistry
 };