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

package/src/integration-lock.js

@@ -0,0 +1,179 @@
+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';
+
+/**
+ * @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, name) {
+  const file = path.join(home, 'integrations', `${assertIntegrationName(name)}.lock`);
+  const guard = `${file}.reclaim`;
+  /** @type {'new' | 'acquiring' | 'owned' | 'retired'} */
+  let phase = 'new';
+  /** This instance's lock while it owns it: the lifetime nonce and the file's identity. @type {{ owner: string, dev: number, ino: number } | undefined} */
+  let owned;
+  // The lock file as read: its record and the stats of the handle it was read through. Kept inside
+  // the factory so the published declarations name only IntegrationLock and its record.
+  /** @typedef {{ value: any, info: import('node:fs').Stats }} Snapshot */
+  /** @param {string} reason */
+  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`);
+
+  /**
+   * @template T
+   * @param {() => Promise<T>} run
+   * @returns {Promise<T>}
+   */
+  async function guarded(run) {
+    await mkdir(path.dirname(file), { recursive: true, mode: 0o700 });
+    const deadline = Date.now() + 20_000;
+    for (;;) {
+      try { await mkdir(guard, { mode: 0o700 }); 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()}`);
+    // If token initialization/close fails, leave the guard: no speculative cleanup of shared paths.
+    try {
+      const handle = await open(token, 'wx', 0o600);
+      await handle.close();
+    } catch (error) { throw recovery(`Integration guard initialization failed: ${String(error)}`); }
+    try { return await run(); }
+    finally {
+      // Only this successful mkdir owner finalizes, once. Missing token may mean a replacement
+      // generation: never rmdir in that case. No contender removes any other owner's token.
+      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)}`); }
+    }
+  }
+
+  /** @returns {Promise<Snapshot | undefined>} */
+  async function snapshot() {
+    let handle;
+    try { handle = await open(file, 'r'); }
+    catch (error) { if (/** @type {any} */ (error)?.code === 'ENOENT') return undefined; throw error; }
+    try {
+      const info = await handle.stat();
+      const raw = await handle.readFile('utf8');
+      let value;
+      try { value = JSON.parse(raw); } catch { value = undefined; }
+      return { value, info };
+    } finally { await handle.close(); }
+  }
+
+  /**
+   * @param {any} value
+   * @returns {value is IntegrationLockRecord}
+   */
+  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 === undefined && value.owner === undefined
+        || value.lockVersion === 1 && typeof value.owner === 'string' && /^[a-f0-9-]{36}$/.test(value.owner));
+  }
+
+  /**
+   * @param {IntegrationLockRecord} value
+   * @returns {boolean}
+   */
+  function dead(value) {
+    try { process.kill(value.pid, 0); return false; }
+    catch (error) {
+      if (/** @type {any} */ (error)?.code !== 'ESRCH') return false; // EPERM and unknown errors never grant takeover.
+      // Approximate wall-clock boot metadata is context, never affirmative death evidence.
+      if (Math.abs(value.bootTime - bootTime()) > 30) throw recovery('Integration owner boot context is uncertain');
+      return true;
+    }
+  }
+
+  /**
+   * @param {Snapshot | undefined} current
+   * @returns {boolean}
+   */
+  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);
+          }
+          /** @type {IntegrationLockRecord & { owner: string }} */
+          const value = { pid: process.pid, bootTime: bootTime(), startedAt: new Date().toISOString(), ready: false, lockVersion: 1, owner: randomUUID() };
+          const handle = await open(file, 'wx', 0o600);
+          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 = undefined; 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 = undefined; return false; }
+        const value = { ...current.value, ready };
+        const tmp = `${file}.${randomUUID()}.tmp`;
+        const handle = await open(tmp, 'wx', 0o600);
+        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 = undefined;
+        if (!ours) return false;
+        await unlink(file);
+        return true;
+      });
+    },
+  };
+}

package/src/portable.js

@@ -25,3 +25,4 @@ export { createLineDecoder, utf8Length } from './rpc/framing.js';
 export { MAX_TIMER_MS, timerDelay } from './rpc/timers.js';
 export { hello } from './rpc/handshake.js';
 export { backoffDelay, createReconnectingClient, retryable } from './rpc/reconnect.js';
+export { attachments, base64Encode, conversation, sha256Hex, workspaceRegistry } from './rpc/registry.js';

package/src/rpc/registry.js

@@ -0,0 +1,161 @@
+/** Typed registry methods for portable clients. Mutations are sent once: callers retain requestId
+ * and ifRevision to reconcile a timeout by repeating the identical request. @param {{request<T = any>(method: string, params?: unknown): Promise<T>}} client */
+export function workspaceRegistry(client) {
+  return {
+    /** @param {string} workspaceId @returns {Promise<import('@anhlp/alp-protocol').RpcMethodMap['workspace.worktree.options']['result']>} */
+    worktreeOptions: workspaceId => client.request('workspace.worktree.options', { workspaceId }),
+    /** @param {import('@anhlp/alp-protocol').RpcMethodMap['workspace.worktree.create']['params']} params @returns {Promise<import('@anhlp/alp-protocol').RpcMethodMap['workspace.worktree.create']['result']>} */
+    createWorktree: params => client.request('workspace.worktree.create', params),
+    /** @param {import('@anhlp/alp-protocol').RpcMethodMap['workspace.worktree.remove']['params']} params @returns {Promise<import('@anhlp/alp-protocol').RpcMethodMap['workspace.worktree.remove']['result']>} */
+    removeWorktree: params => client.request('workspace.worktree.remove', params),
+    /** Read-only Git status of a registry workspace (capability `workspace.git`, §12.5). @param {string} workspaceId @returns {Promise<import('@anhlp/alp-protocol').RpcMethodMap['workspace.git.status']['result']>} */
+    gitStatus: workspaceId => client.request('workspace.git.status', { workspaceId }),
+    /** One page of a read-only Git diff; pass `nextCursor` back as `cursor` with the same comparison and path. @param {import('@anhlp/alp-protocol').RpcMethodMap['workspace.git.diff']['params']} params @returns {Promise<import('@anhlp/alp-protocol').RpcMethodMap['workspace.git.diff']['result']>} */
+    gitDiff: params => client.request('workspace.git.diff', params),
+    /** @param {import('@anhlp/alp-protocol').RpcMethodMap['project.list']['params']} [params] @returns {Promise<import('@anhlp/alp-protocol').RpcMethodMap['project.list']['result']>} */
+    projects: (params = {}) => client.request('project.list', params),
+    /** @param {import('@anhlp/alp-protocol').RpcMethodMap['workspace.list']['params']} [params] @returns {Promise<import('@anhlp/alp-protocol').RpcMethodMap['workspace.list']['result']>} */
+    workspaces: (params = {}) => client.request('workspace.list', params),
+    /** @param {string} workspaceId @returns {Promise<import('@anhlp/alp-protocol').RpcMethodMap['workspace.get']['result']>} */
+    get: workspaceId => client.request('workspace.get', { workspaceId }),
+    /** @param {import('@anhlp/alp-protocol').RpcMethodMap['project.register']['params']} params @returns {Promise<import('@anhlp/alp-protocol').RpcMethodMap['project.register']['result']>} */
+    register: params => client.request('project.register', params),
+    /** @param {import('@anhlp/alp-protocol').RpcMethodMap['project.remove']['params']} params @returns {Promise<import('@anhlp/alp-protocol').RpcMethodMap['project.remove']['result']>} */
+    remove: params => client.request('project.remove', params),
+    /** @param {import('@anhlp/alp-protocol').RpcMethodMap['workspace.update']['params']} params @returns {Promise<import('@anhlp/alp-protocol').RpcMethodMap['workspace.update']['result']>} */
+    update: params => client.request('workspace.update', params),
+  };
+}
+
+const BASE64 = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+
+/** Canonical base64 of `bytes`, without Buffer or btoa, so it runs in browsers and Node alike. @param {Uint8Array} bytes */
+export function base64Encode(bytes) {
+  let out = '';
+  let index = 0;
+  for (; index + 2 < bytes.length; index += 3) {
+    const n = (bytes[index] << 16) | (bytes[index + 1] << 8) | bytes[index + 2];
+    out += BASE64[n >> 18] + BASE64[(n >> 12) & 63] + BASE64[(n >> 6) & 63] + BASE64[n & 63];
+  }
+  if (index < bytes.length) {
+    const n = (bytes[index] << 16) | ((index + 1 < bytes.length ? bytes[index + 1] : 0) << 8);
+    out += BASE64[n >> 18] + BASE64[(n >> 12) & 63] + (index + 1 < bytes.length ? BASE64[(n >> 6) & 63] : '=') + '=';
+  }
+  return out;
+}
+
+/** Lowercase hex SHA-256 of `bytes` through WebCrypto (browsers' secure contexts, Node 19+). @param {Uint8Array} bytes */
+export async function sha256Hex(bytes) {
+  const subtle = globalThis.crypto?.subtle;
+  if (!subtle) throw new Error('SHA-256 needs WebCrypto here; pass sha256 yourself');
+  const digest = new Uint8Array(await subtle.digest('SHA-256', bytes));
+  return Array.from(digest, byte => byte.toString(16).padStart(2, '0')).join('');
+}
+
+/**
+ * Typed attachment methods (capability `attachments`, docs/protocol/alp-json-rpc-v1.md §12.6) and a
+ * chunked upload that keeps to the limits the daemon (or gateway) advertised. Mutations are sent
+ * once: `upload` resumes an interrupted upload by repeating its begin with the same requestId and
+ * continues from what the daemon holds.
+ * @param {{request<T = any>(method: string, params?: unknown): Promise<T>}} client
+ */
+export function attachments(client) {
+  /** @typedef {import('@anhlp/alp-protocol').RpcMethodMap} Map */
+  const api = {
+    /** @param {Map['attachment.begin']['params']} params @returns {Promise<Map['attachment.begin']['result']>} */
+    begin: params => client.request('attachment.begin', params),
+    /** @param {Map['attachment.chunk']['params']} params @returns {Promise<Map['attachment.chunk']['result']>} */
+    chunk: params => client.request('attachment.chunk', params),
+    /** @param {Map['attachment.commit']['params']} params @returns {Promise<Map['attachment.commit']['result']>} */
+    commit: params => client.request('attachment.commit', params),
+    /** @param {string} uploadId @returns {Promise<Map['attachment.abort']['result']>} */
+    abort: uploadId => client.request('attachment.abort', { uploadId }),
+    /** Metadata only (no bytes, no path). @param {string} attachmentId @returns {Promise<Map['attachment.get']['result']>} */
+    get: attachmentId => client.request('attachment.get', { attachmentId }),
+    /** Refused (1004 attachment_referenced) while a prompt references it. @param {string} attachmentId @returns {Promise<Map['attachment.delete']['result']>} */
+    delete: attachmentId => client.request('attachment.delete', { attachmentId }),
+    /**
+     * Uploads `data` and commits it: begin (or resume, with the same requestId), chunks of at most
+     * the smaller of `maxChunkBytes` and what begin answered, commit with its SHA-256. A chunk
+     * refused `offset_mismatch` continues from the daemon's `received`. Returns the attachment.
+     * @param {{ sessionId: string, name: string, mimeType: string, data: Uint8Array, requestId: string, sha256?: string, maxChunkBytes?: number, onProgress?: (received: number, size: number) => void }} options
+     */
+    async upload({ sessionId, name, mimeType, data, requestId, sha256, maxChunkBytes, onProgress }) {
+      const digest = sha256 ?? await sha256Hex(data);
+      const begun = await api.begin({ sessionId, name, size: data.length, mimeType, sha256: digest, requestId });
+      if (begun.state === 'committed' && begun.attachmentId) return (await api.get(begun.attachmentId)).attachment;
+      const size = Math.max(1, Math.min(begun.maxChunkBytes, maxChunkBytes ?? Infinity));
+      let offset = begun.received;
+      for (let realigned = 0; offset < data.length;) {
+        const end = Math.min(data.length, offset + size);
+        try {
+          const { received } = await api.chunk({ uploadId: begun.uploadId, offset, data: base64Encode(data.subarray(offset, end)) });
+          offset = received;
+        } catch (error) {
+          const held = /** @type {any} */ (error)?.data;
+          // Another attempt got further (or less far) than this one knew: continue where the daemon is.
+          if (held?.reason !== 'offset_mismatch' || !Number.isSafeInteger(held.received) || ++realigned > 3) throw error;
+          offset = held.received;
+          continue;
+        }
+        onProgress?.(offset, data.length);
+      }
+      return (await api.commit({ uploadId: begun.uploadId, sha256: digest })).attachment;
+    },
+  };
+  return api;
+}
+
+/**
+ * Typed conversation methods (capabilities `session.fork` and `session.rewind`, docs/protocol/
+ * alp-json-rpc-v1.md §12.7; `session.reload` and `session.resumeCommand`, §12.8). Both change the conversation only, never a file. Mutations are sent
+ * once: keep `requestId` (and `ifGeneration`) to repeat the identical request after a timeout, which
+ * answers the first result with `duplicate: true`. After a rewind, attached clients get a
+ * `history.reset` event: drop cached history, fetch a new tail and attach with its generation.
+ * @param {{request<T = any>(method: string, params?: unknown): Promise<T>}} client
+ */
+export function conversation(client) {
+  /** @typedef {import('@anhlp/alp-protocol').RpcMethodMap} Map */
+  return {
+    /**
+     * A new closed root whose conversation is the source root's through or before a turn (`boundary`),
+     * or a branch a rewind set aside (`branchId`); resume it with session.create { sessionId, resume: true }.
+     * Principal fields are set by a trusted gateway on its own connection, never by a remote client.
+     * @param {Map['session.fork']['params']} params @returns {Promise<Map['session.fork']['result']>}
+     */
+    fork: params => client.request('session.fork', params),
+    /**
+     * Continues the root's conversation from before `beforeTurnId` under the same session id; the
+     * later turns stay a branch (`branch.branchId`) that `fork({ branchId })` recovers.
+     * @param {Map['session.rewind']['params']} params @returns {Promise<Map['session.rewind']['result']>}
+     */
+    rewind: params => client.request('session.rewind', params),
+    /**
+     * Restarts a live root's native process on its own conversation and configuration at the idle
+     * barrier (capability `session.reload`, §12.8); id, history and receipts stay. Sent once: repeat
+     * the same `requestId` after a lost answer.
+     * @param {Map['session.reload']['params']} params @returns {Promise<Map['session.reload']['result']>}
+     */
+    reload: params => client.request('session.reload', params),
+    /**
+     * The ALP CLI command that follows the session in a terminal (capability `session.resumeCommand`,
+     * §12.8), built by alpd: for the clipboard only, never to run.
+     * @param {Map['session.resumeCommand']['params']} params @returns {Promise<Map['session.resumeCommand']['result']>}
+     */
+    resumeCommand: params => client.request('session.resumeCommand', params),
+    /**
+     * Changes a live root's model, effort or team (capability `session.configure.live`, §12.9) at the
+     * idle barrier, through a restart of its native process on the same conversation; `configured` says
+     * what it runs with now. Sent once: repeat the same `requestId` after a lost answer. A change to
+     * another runtime is refused (1005 runtime_mismatch, `data.action: 'session.create'`).
+     * @param {Map['session.configure']['params'] & { requestId: string; ifGeneration: string }} params @returns {Promise<Map['session.configure']['result']>}
+     */
+    configure: params => client.request('session.configure', params),
+    /**
+     * What a change of model, effort, team or mode would run a live root with, and whether it would be
+     * taken now (capability `session.configure.live`, §12.9). Reads only.
+     * @param {Map['session.configure.preview']['params']} params @returns {Promise<Map['session.configure.preview']['result']>}
+     */
+    configurePreview: params => client.request('session.configure.preview', params),
+  };
+}

package/src/supervise.d.ts

@@ -9,4 +9,6 @@ export function superviseDaemon(options: {
   intervalMs?: number;
   misses?: number;
   log?: (message: string) => void;
+  /** Who keeps alpd up, for the log: "alpd started with <by>". */
+  by?: string;
 }): (() => Promise<void>) & { started: Promise<void> };

package/src/supervise.js

@@ -61,14 +61,16 @@ export async function startDaemon({ home, entry, env = process.env, timeoutMs =
  * Starts alpd now and starts it again whenever it is found down on `misses` checks in a
  * row, `intervalMs` apart, unless the user holds it. Two misses let `alp daemon restart`
  * and `install` finish their own stop and start first. Returns a function that stops
- * watching, and resolves once a start it began has settled; alpd keeps running.
+ * watching, and resolves once a start it began has settled; alpd keeps running. `by` names the
+ * caller in the log line of the first start ("alpd started with <by>").
  */
-export function superviseDaemon({ home, entry, env = process.env, intervalMs = 5_000, misses = 2, log = () => {} }) {
+export function superviseDaemon({ home, entry, env = process.env, intervalMs = 5_000, misses = 2, log = () => {}, by }) {
   let stopped = false;
   let missed = 0;
   let starting;
-  const start = reason => {
-    starting ??= startDaemon({ home, entry: typeof entry === 'function' ? entry() : entry, env, automatic: reason !== 'started with Paseo' })
+  // The first start is the caller's own request (it lifts a hold); later ones are automatic.
+  const start = (reason, automatic = true) => {
+    starting ??= startDaemon({ home, entry: typeof entry === 'function' ? entry() : entry, env, automatic })
       .then(socket => { if (socket) log(`alpd ${reason}`); }, error => log(`could not start alpd: ${error?.message ?? error}`))
       .finally(() => { starting = undefined; missed = 0; });
     return starting;
@@ -80,7 +82,8 @@ export function superviseDaemon({ home, entry, env = process.env, intervalMs = 5
     // Stopped while this check looked: start nothing.
     if (++missed >= misses && !stopped) await start('was down; started it again');
   };
-  const initial = start('started with Paseo');
+  // `by` names the supervising service in the log, for example `Paseo` or `alp web`.
+  const initial = start(by ? `started with ${by}` : 'started', false);
   const timer = setInterval(() => { void check(); }, intervalMs);
   timer.unref?.();
   const stop = () => { stopped = true; clearInterval(timer); return starting ?? Promise.resolve(); };