@loreai/gateway 0.13.3 → 0.14.0

package/src/cli/lib/binary.ts

@@ -0,0 +1,353 @@
+/**
+ * Binary Management
+ *
+ * Shared utilities for installing, replacing, and managing the CLI binary.
+ * Adapted from Sentry CLI's binary.ts for the Lore upgrade system.
+ *
+ * Key differences from Sentry CLI:
+ * - No musl detection (Lore doesn't target Alpine)
+ * - Lore binary naming: `lore-{os}-{arch}[.exe]`
+ * - Install dirs: ~/.lore/bin, ~/.local/bin
+ * - No Sentry SDK telemetry
+ */
+
+import {
+  existsSync,
+  readFileSync,
+  renameSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { chmod, mkdir, unlink } from "node:fs/promises";
+import { delimiter, join, resolve } from "node:path";
+import { VERSION } from "../version";
+import { stringifyUnknown, UpgradeError } from "./errors";
+
+/** GitHub owner/repo for Lore releases */
+const GITHUB_OWNER = "BYK";
+const GITHUB_REPO = "loreai";
+
+/** GitHub API base URL for releases */
+export const GITHUB_RELEASES_URL =
+  `https://api.github.com/repos/${GITHUB_OWNER}/${GITHUB_REPO}/releases`;
+
+/** Known directories where the curl installer may place the binary */
+export const KNOWN_CURL_DIRS = [".local/bin", "bin", ".lore/bin"];
+
+/**
+ * Build the platform-specific binary base name.
+ *
+ * Matches the naming convention used by GitHub Releases and GHCR:
+ * `lore-{os}-{arch}[.exe]`
+ */
+export function getPlatformBinaryName(): string {
+  let os: string;
+  if (process.platform === "darwin") {
+    os = "darwin";
+  } else if (process.platform === "win32") {
+    os = "windows";
+  } else {
+    os = "linux";
+  }
+  const arch = process.arch === "arm64" ? "arm64" : "x64";
+  const suffix = process.platform === "win32" ? ".exe" : "";
+  return `lore-${os}-${arch}${suffix}`;
+}
+
+/**
+ * Build the download URL for a platform-specific binary from GitHub releases.
+ */
+export function getBinaryDownloadUrl(version: string): string {
+  return `https://github.com/${GITHUB_OWNER}/${GITHUB_REPO}/releases/download/${version}/${getPlatformBinaryName()}`;
+}
+
+/**
+ * Detect whether a version string identifies a nightly build.
+ *
+ * Nightlies use the format `X.Y.Z-dev.<unix-seconds>`.
+ */
+export function isNightlyVersion(version: string): boolean {
+  return version.includes("-dev.");
+}
+
+/**
+ * Compare two version strings and return their ordering.
+ *
+ * Uses `Bun.semver.order` which handles both stable (`X.Y.Z`) and
+ * nightly (`X.Y.Z-dev.<unix-seconds>`) versions correctly.
+ */
+export function compareVersions(a: string, b: string): -1 | 0 | 1 {
+  return Bun.semver.order(a, b);
+}
+
+/**
+ * Check whether moving from `current` to `target` is a downgrade.
+ */
+export function isDowngrade(current: string, target: string): boolean {
+  return compareVersions(current, target) === 1;
+}
+
+/**
+ * Get the binary filename for the current platform.
+ */
+export function getBinaryFilename(): string {
+  return process.platform === "win32" ? "lore.exe" : "lore";
+}
+
+/**
+ * Build paths object from an install path.
+ */
+export function getBinaryPaths(installPath: string): {
+  installPath: string;
+  tempPath: string;
+  oldPath: string;
+  lockPath: string;
+} {
+  return {
+    installPath,
+    tempPath: `${installPath}.download`,
+    oldPath: `${installPath}.old`,
+    lockPath: `${installPath}.lock`,
+  };
+}
+
+/**
+ * Determine the install directory for a curl-installed binary.
+ *
+ * Priority:
+ * 1. $LORE_INSTALL_DIR environment variable
+ * 2. ~/.local/bin (if exists AND in $PATH)
+ * 3. ~/bin (if exists AND in $PATH)
+ * 4. ~/.lore/bin (fallback)
+ */
+export function determineInstallDir(
+  homeDir: string,
+  env: NodeJS.ProcessEnv,
+): string {
+  const pathDirs = (env.PATH ?? "").split(delimiter);
+
+  if (env.LORE_INSTALL_DIR) {
+    return env.LORE_INSTALL_DIR;
+  }
+
+  const candidates = [join(homeDir, ".local", "bin"), join(homeDir, "bin")];
+
+  for (const dir of candidates) {
+    if (existsSync(dir) && pathDirs.includes(dir)) {
+      return dir;
+    }
+  }
+
+  return join(homeDir, ".lore", "bin");
+}
+
+/**
+ * Build headers for GitHub API requests.
+ */
+export function getGitHubHeaders(): Record<string, string> {
+  return {
+    Accept: "application/vnd.github.v3+json",
+    "User-Agent": getUserAgent(),
+  };
+}
+
+/**
+ * Generate the User-Agent string for API requests.
+ */
+export function getUserAgent(): string {
+  const runtime =
+    typeof process.versions.bun !== "undefined"
+      ? `bun/${process.versions.bun}`
+      : `node/${process.versions.node}`;
+  return `lore/${VERSION} (${process.platform}-${process.arch}) ${runtime}`;
+}
+
+/**
+ * Fetch wrapper that converts network errors to UpgradeError.
+ */
+export async function fetchWithUpgradeError(
+  url: string,
+  init: RequestInit,
+  serviceName: string,
+): Promise<Response> {
+  try {
+    return await fetch(url, init);
+  } catch (error) {
+    if (error instanceof Error && error.name === "AbortError") {
+      throw error;
+    }
+    const msg = stringifyUnknown(error);
+    throw new UpgradeError(
+      "network_error",
+      `Failed to connect to ${serviceName}: ${msg}`,
+    );
+  }
+}
+
+/**
+ * Replace the binary at the install path, handling platform differences.
+ *
+ * Intentionally synchronous: the multi-step rename sequence must be
+ * uninterruptible to avoid leaving the install path in a broken state.
+ *
+ * - Unix: Atomic rename overwrites the target
+ * - Windows: Rename old binary to .old first, then rename temp into place
+ */
+export function replaceBinarySync(tempPath: string, installPath: string): void {
+  if (process.platform === "win32") {
+    const oldPath = `${installPath}.old`;
+    try {
+      renameSync(installPath, oldPath);
+    } catch {
+      try {
+        unlinkSync(oldPath);
+        renameSync(installPath, oldPath);
+      } catch {
+        // Current binary might not exist — that's fine
+      }
+    }
+    renameSync(tempPath, installPath);
+  } else {
+    renameSync(tempPath, installPath);
+  }
+}
+
+/**
+ * Clean up leftover .old files from previous upgrades.
+ * Called on CLI startup. Fire-and-forget.
+ */
+export function cleanupOldBinary(oldPath: string): void {
+  unlink(oldPath).catch(() => {
+    // Intentionally ignore — file may not exist
+  });
+}
+
+// Lock Management
+
+/**
+ * Check if a process with the given PID is still running.
+ */
+export function isProcessRunning(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "EPERM") {
+      return true;
+    }
+    return false;
+  }
+}
+
+/**
+ * Acquire an exclusive lock for binary installation/upgrade.
+ * Uses atomic file creation with 'wx' flag to prevent race conditions.
+ */
+export function acquireLock(lockPath: string): void {
+  try {
+    writeFileSync(lockPath, String(process.pid), { flag: "wx" });
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "EEXIST") {
+      throw error;
+    }
+    handleExistingLock(lockPath);
+  }
+}
+
+function handleExistingLock(lockPath: string): void {
+  let content: string;
+  try {
+    content = readFileSync(lockPath, "utf-8").trim();
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+      acquireLock(lockPath);
+      return;
+    }
+    throw error;
+  }
+
+  const existingPid = Number.parseInt(content, 10);
+
+  if (!Number.isNaN(existingPid) && isProcessRunning(existingPid)) {
+    if (existingPid === process.ppid) {
+      writeFileSync(lockPath, String(process.pid));
+      return;
+    }
+    throw new UpgradeError(
+      "execution_failed",
+      "Another upgrade is already in progress",
+    );
+  }
+
+  // Stale lock from dead process — remove and retry
+  try {
+    unlinkSync(lockPath);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT") {
+      throw error;
+    }
+  }
+
+  acquireLock(lockPath);
+}
+
+/**
+ * Release the binary lock.
+ */
+export function releaseLock(lockPath: string): void {
+  try {
+    unlinkSync(lockPath);
+  } catch {
+    // Ignore — file might already be gone
+  }
+}
+
+/**
+ * Install a binary to the target directory.
+ */
+export async function installBinary(
+  sourcePath: string,
+  installDir: string,
+): Promise<string> {
+  await mkdir(installDir, { recursive: true, mode: 0o755 });
+
+  const installPath = join(installDir, getBinaryFilename());
+  const { tempPath, lockPath } = getBinaryPaths(installPath);
+
+  acquireLock(lockPath);
+
+  try {
+    if (resolve(sourcePath) !== resolve(tempPath)) {
+      try {
+        await unlink(tempPath);
+      } catch {
+        // Ignore if doesn't exist
+      }
+
+      await Bun.write(tempPath, Bun.file(sourcePath));
+
+      if (process.platform !== "win32") {
+        await chmod(tempPath, 0o755);
+      }
+    }
+
+    replaceBinarySync(tempPath, installPath);
+  } finally {
+    releaseLock(lockPath);
+  }
+
+  return installPath;
+}
+
+/**
+ * Get the Lore config directory.
+ * Uses $LORE_CONFIG_DIR if set, otherwise ~/.lore
+ */
+export function getConfigDir(): string {
+  if (process.env.LORE_CONFIG_DIR) {
+    return process.env.LORE_CONFIG_DIR;
+  }
+  const home =
+    process.env.HOME ?? process.env.USERPROFILE ?? require("node:os").homedir();
+  return join(home, ".lore");
+}

package/src/cli/lib/bspatch.ts

@@ -0,0 +1,306 @@
+/**
+ * Streaming TRDIFF10 Binary Patch Application
+ *
+ * Implements the bspatch algorithm for applying binary delta patches in the
+ * TRDIFF10 format (produced by zig-bsdiff with `--use-zstd`). Designed for
+ * minimal memory usage during CLI self-upgrades:
+ *
+ * - Old binary: copy-then-mmap for 0 JS heap (CoW on btrfs/xfs/APFS),
+ *   falling back to `arrayBuffer()` if copy/mmap fails
+ * - Diff/extra blocks: streamed via `DecompressionStream('zstd')`
+ * - Output: written incrementally to disk via `Bun.file().writer()`
+ * - Integrity: SHA-256 computed inline via `Bun.CryptoHasher`
+ *
+ * TRDIFF10 format (from zig-bsdiff):
+ * ```
+ * [0..8]   magic: "TRDIFF10"
+ * [8..16]  controlLen: i64 LE (compressed size of control block)
+ * [16..24] diffLen:    i64 LE (compressed size of diff block)
+ * [24..32] newSize:    i64 LE (expected output size)
+ * [32..]   zstd(control) | zstd(diff) | zstd(extra)
+ * ```
+ *
+ * Adapted from Sentry CLI's bspatch.ts — pure Bun, no external dependencies.
+ */
+
+import { constants, copyFileSync } from "node:fs";
+import { unlink } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+/** TRDIFF10 header magic bytes */
+const TRDIFF10_MAGIC = "TRDIFF10";
+
+/** Header size in bytes (magic + 3 x i64) */
+const HEADER_SIZE = 32;
+
+/** Parsed TRDIFF10 header fields */
+export type PatchHeader = {
+  controlLen: number;
+  diffLen: number;
+  newSize: number;
+};
+
+/**
+ * Read a signed 64-bit little-endian integer using the zig-bsdiff encoding.
+ *
+ * The sign is stored in bit 7 of byte 7 (the MSB of the last byte).
+ * The magnitude is in the lower 63 bits, read as unsigned LE.
+ * This differs from standard two's complement — it uses sign-magnitude.
+ */
+export function offtin(buf: Uint8Array, offset: number): number {
+  const view = new DataView(buf.buffer, buf.byteOffset + offset, 8);
+  const lo = view.getUint32(0, true);
+  const hi = view.getUint32(4, true);
+
+  const magnitude = (hi % 0x80_00_00_00) * 0x1_00_00_00_00 + lo;
+
+  if (magnitude !== 0 && hi >= 0x80_00_00_00) {
+    return -magnitude;
+  }
+  return magnitude;
+}
+
+/**
+ * Parse and validate a TRDIFF10 patch header.
+ */
+export function parsePatchHeader(patch: Uint8Array): PatchHeader {
+  if (patch.byteLength < HEADER_SIZE) {
+    throw new Error(
+      `Patch too small: ${patch.byteLength} bytes (need at least ${HEADER_SIZE})`,
+    );
+  }
+
+  const magic = new TextDecoder().decode(patch.subarray(0, 8));
+  if (magic !== TRDIFF10_MAGIC) {
+    throw new Error(`Invalid patch format: expected TRDIFF10, got "${magic}"`);
+  }
+
+  const controlLen = offtin(patch, 8);
+  const diffLen = offtin(patch, 16);
+  const newSize = offtin(patch, 24);
+
+  if (controlLen < 0 || diffLen < 0 || newSize < 0) {
+    throw new Error("Corrupt patch: negative length in header");
+  }
+
+  const totalCompressed = HEADER_SIZE + controlLen + diffLen;
+  if (totalCompressed > patch.byteLength) {
+    throw new Error(
+      `Corrupt patch: header lengths (${totalCompressed}) exceed file size (${patch.byteLength})`,
+    );
+  }
+
+  return { controlLen, diffLen, newSize };
+}
+
+/**
+ * Buffered reader over a `ReadableStream` that serves exact byte counts.
+ */
+class BufferedStreamReader {
+  private readonly chunks: Uint8Array[] = [];
+  private buffered = 0;
+  private done = false;
+  private readonly reader: ReadableStreamDefaultReader<Uint8Array>;
+
+  constructor(reader: ReadableStreamDefaultReader<Uint8Array>) {
+    this.reader = reader;
+  }
+
+  async read(n: number): Promise<Uint8Array> {
+    while (this.buffered < n && !this.done) {
+      const result = await this.reader.read();
+      if (result.done) {
+        this.done = true;
+        break;
+      }
+      this.chunks.push(result.value);
+      this.buffered += result.value.byteLength;
+    }
+
+    if (this.buffered < n) {
+      throw new Error(
+        `Unexpected end of stream: needed ${n} bytes, have ${this.buffered}`,
+      );
+    }
+
+    const output = new Uint8Array(n);
+    let written = 0;
+
+    while (written < n) {
+      const front = this.chunks[0];
+      if (!front) break;
+      const needed = n - written;
+
+      if (front.byteLength <= needed) {
+        output.set(front, written);
+        written += front.byteLength;
+        this.buffered -= front.byteLength;
+        this.chunks.shift();
+      } else {
+        output.set(front.subarray(0, needed), written);
+        this.chunks[0] = front.subarray(needed);
+        this.buffered -= needed;
+        written = n;
+      }
+    }
+
+    return output;
+  }
+}
+
+/**
+ * Create a streaming zstd decompressor from a compressed buffer.
+ */
+function createZstdStreamReader(compressed: Uint8Array): BufferedStreamReader {
+  const input = new ReadableStream<Uint8Array>({
+    start(controller) {
+      controller.enqueue(compressed);
+      controller.close();
+    },
+  });
+
+  // Bun supports 'zstd' but the standard CompressionFormat type doesn't include it.
+  // The double cast works around TypeScript's strict WritableStream<BufferSource>
+  // vs WritableStream<Uint8Array> mismatch in DecompressionStream.
+  const decompressed = input.pipeThrough(
+    new DecompressionStream("zstd" as "deflate") as unknown as TransformStream<Uint8Array, Uint8Array>,
+  );
+
+  return new BufferedStreamReader(
+    decompressed.getReader() as ReadableStreamDefaultReader<Uint8Array>,
+  );
+}
+
+type OldFileHandle = {
+  data: Uint8Array;
+  cleanup: () => void | Promise<void>;
+};
+
+/**
+ * Load the old binary for read access during patching.
+ *
+ * Strategy: copy to temp file, then try mmap on the copy. Falls back to
+ * arrayBuffer() if copy or mmap fails.
+ */
+let loadCounter = 0;
+
+async function loadOldBinary(oldPath: string): Promise<OldFileHandle> {
+  loadCounter += 1;
+  const tempCopy = join(
+    tmpdir(),
+    `lore-patch-old-${process.pid}-${loadCounter}`,
+  );
+  try {
+    copyFileSync(oldPath, tempCopy, constants.COPYFILE_FICLONE);
+    const data = Bun.mmap(tempCopy, { shared: false });
+    return {
+      data,
+      cleanup: () =>
+        unlink(tempCopy).catch(() => {
+          /* Best-effort */
+        }),
+    };
+  } catch {
+    await unlink(tempCopy).catch(() => {
+      /* May not exist */
+    });
+    return {
+      data: new Uint8Array(await Bun.file(oldPath).arrayBuffer()),
+      cleanup: () => {},
+    };
+  }
+}
+
+/**
+ * Apply a TRDIFF10 binary patch with streaming I/O for minimal memory usage.
+ *
+ * @param oldPath - Path to the existing (old) binary file
+ * @param patchData - Complete TRDIFF10 patch file contents
+ * @param destPath - Path to write the patched (new) binary
+ * @returns SHA-256 hex digest of the written output
+ */
+export async function applyPatch(
+  oldPath: string,
+  patchData: Uint8Array,
+  destPath: string,
+): Promise<string> {
+  const { controlLen, diffLen, newSize } = parsePatchHeader(patchData);
+
+  const controlStart = HEADER_SIZE;
+  const diffStart = controlStart + controlLen;
+  const extraStart = diffStart + diffLen;
+
+  // Control block is tiny — decompress fully for random access
+  const controlBlock = Bun.zstdDecompressSync(
+    patchData.subarray(controlStart, diffStart),
+  );
+
+  // Diff and extra blocks are streamed
+  const diffReader = createZstdStreamReader(
+    patchData.subarray(diffStart, extraStart),
+  );
+  const extraReader = createZstdStreamReader(patchData.subarray(extraStart));
+
+  const { data: oldFile, cleanup: cleanupOldFile } =
+    await loadOldBinary(oldPath);
+
+  const writer = Bun.file(destPath).writer();
+  const hasher = new Bun.CryptoHasher("sha256");
+
+  let oldpos = 0;
+  let newpos = 0;
+
+  try {
+    for (
+      let controlPos = 0;
+      controlPos < controlBlock.byteLength;
+      controlPos += 24
+    ) {
+      const readDiffBy = offtin(controlBlock, controlPos);
+      const readExtraBy = offtin(controlBlock, controlPos + 8);
+      const seekBy = offtin(controlBlock, controlPos + 16);
+
+      // Step 1: Read diff bytes and add to old file bytes (wrapping u8 add)
+      if (readDiffBy > 0) {
+        const diffChunk = await diffReader.read(readDiffBy);
+        const outputChunk = new Uint8Array(readDiffBy);
+
+        for (let i = 0; i < readDiffBy; i++) {
+          outputChunk[i] =
+            ((oldFile[oldpos + i] ?? 0) + (diffChunk[i] ?? 0)) % 256;
+        }
+
+        writer.write(outputChunk);
+        hasher.update(outputChunk);
+        oldpos += readDiffBy;
+        newpos += readDiffBy;
+      }
+
+      // Step 2: Copy extra bytes directly to output
+      if (readExtraBy > 0) {
+        const extraChunk = await extraReader.read(readExtraBy);
+        writer.write(extraChunk);
+        hasher.update(extraChunk);
+        newpos += readExtraBy;
+      }
+
+      // Step 3: Seek old file position
+      oldpos += seekBy;
+    }
+  } finally {
+    try {
+      await writer.end();
+    } finally {
+      await cleanupOldFile();
+    }
+  }
+
+  if (newpos !== newSize) {
+    throw new Error(
+      `Output size mismatch: wrote ${newpos} bytes, expected ${newSize}`,
+    );
+  }
+
+  return hasher.digest("hex") as string;
+}