@openpalm/lib 0.9.8 → 0.10.1

package/src/control-plane/lock.test.ts

@@ -0,0 +1,194 @@
+/**
+ * Tests for orchestrator lock — acquisition, contention, stale cleanup,
+ * corrupt file handling, release, and idempotent release.
+ */
+import { describe, it, expect, beforeEach, afterEach } from "bun:test";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync, existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import {
+  acquireLock,
+  releaseLock,
+  lockPath,
+  LockAcquisitionError,
+} from "./lock.js";
+import type { LockHandle, LockInfo } from "./lock.js";
+
+let opHome: string;
+
+beforeEach(() => {
+  opHome = mkdtempSync(join(tmpdir(), "lock-test-"));
+  mkdirSync(join(opHome, "data"), { recursive: true });
+});
+
+afterEach(() => {
+  rmSync(opHome, { recursive: true, force: true });
+});
+
+// ── Acquisition ──────────────────────────────────────────────────────────
+
+describe("acquireLock", () => {
+  it("creates a lock file with correct JSON content", () => {
+    const handle = acquireLock(opHome, "install");
+    expect(existsSync(handle.path)).toBe(true);
+
+    const content = JSON.parse(readFileSync(handle.path, "utf-8"));
+    expect(content.pid).toBe(process.pid);
+    expect(content.operation).toBe("install");
+    expect(typeof content.acquiredAt).toBe("string");
+
+    releaseLock(handle);
+  });
+
+  it("returns a handle with correct info", () => {
+    const handle = acquireLock(opHome, "update");
+    expect(handle.info.pid).toBe(process.pid);
+    expect(handle.info.operation).toBe("update");
+    expect(handle.path).toBe(lockPath(opHome));
+
+    releaseLock(handle);
+  });
+
+  it("places lock at {opHome}/data/.openpalm.lock", () => {
+    const handle = acquireLock(opHome, "test");
+    expect(handle.path).toBe(join(opHome, "data", ".openpalm.lock"));
+    releaseLock(handle);
+  });
+});
+
+// ── Contention ───────────────────────────────────────────────────────────
+
+describe("contention", () => {
+  it("throws LockAcquisitionError when lock is already held by this process", () => {
+    const handle = acquireLock(opHome, "install");
+
+    try {
+      expect(() => acquireLock(opHome, "update")).toThrow(LockAcquisitionError);
+    } finally {
+      releaseLock(handle);
+    }
+  });
+
+  it("error includes holder details", () => {
+    const handle = acquireLock(opHome, "install");
+
+    try {
+      acquireLock(opHome, "update");
+      expect.unreachable("should have thrown");
+    } catch (err) {
+      expect(err).toBeInstanceOf(LockAcquisitionError);
+      const lockErr = err as LockAcquisitionError;
+      expect(lockErr.holder.pid).toBe(process.pid);
+      expect(lockErr.holder.operation).toBe("install");
+    } finally {
+      releaseLock(handle);
+    }
+  });
+});
+
+// ── Stale PID cleanup ────────────────────────────────────────────────────
+
+describe("stale PID cleanup", () => {
+  it("cleans up stale lock from a dead PID and acquires", () => {
+    // Write a lock file with a PID that does not exist
+    const stalePid = 99999999; // Very unlikely to be a real process
+    const staleInfo: LockInfo = {
+      pid: stalePid,
+      operation: "old-install",
+      acquiredAt: "2020-01-01T00:00:00.000Z",
+    };
+    writeFileSync(lockPath(opHome), JSON.stringify(staleInfo) + "\n");
+
+    // Should succeed because the PID is dead
+    const handle = acquireLock(opHome, "new-install");
+    expect(handle.info.pid).toBe(process.pid);
+    expect(handle.info.operation).toBe("new-install");
+
+    releaseLock(handle);
+  });
+});
+
+// ── Corrupt file handling ────────────────────────────────────────────────
+
+describe("corrupt lock file", () => {
+  it("recovers from a corrupt lock file", () => {
+    writeFileSync(lockPath(opHome), "not valid json{{{");
+
+    const handle = acquireLock(opHome, "install");
+    expect(handle.info.pid).toBe(process.pid);
+
+    releaseLock(handle);
+  });
+
+  it("recovers from an empty lock file", () => {
+    writeFileSync(lockPath(opHome), "");
+
+    const handle = acquireLock(opHome, "install");
+    expect(handle.info.pid).toBe(process.pid);
+
+    releaseLock(handle);
+  });
+
+  it("recovers from a lock file with missing fields", () => {
+    writeFileSync(lockPath(opHome), JSON.stringify({ pid: 1 }));
+
+    const handle = acquireLock(opHome, "install");
+    expect(handle.info.pid).toBe(process.pid);
+
+    releaseLock(handle);
+  });
+});
+
+// ── Release ──────────────────────────────────────────────────────────────
+
+describe("releaseLock", () => {
+  it("removes the lock file", () => {
+    const handle = acquireLock(opHome, "install");
+    expect(existsSync(handle.path)).toBe(true);
+
+    releaseLock(handle);
+    expect(existsSync(handle.path)).toBe(false);
+  });
+
+  it("is idempotent — second release is a no-op", () => {
+    const handle = acquireLock(opHome, "install");
+    releaseLock(handle);
+    expect(existsSync(handle.path)).toBe(false);
+
+    // Second release should not throw
+    releaseLock(handle);
+    expect(existsSync(handle.path)).toBe(false);
+  });
+
+  it("does not remove lock owned by a different PID", () => {
+    // Simulate a lock file owned by someone else
+    const otherInfo: LockInfo = {
+      pid: 99999999,
+      operation: "other",
+      acquiredAt: new Date().toISOString(),
+    };
+    writeFileSync(lockPath(opHome), JSON.stringify(otherInfo) + "\n");
+
+    // Create a handle that claims to own the lock
+    const fakeHandle: LockHandle = {
+      path: lockPath(opHome),
+      info: {
+        pid: process.pid, // Different from file content
+        operation: "mine",
+        acquiredAt: new Date().toISOString(),
+      },
+    };
+
+    releaseLock(fakeHandle);
+    // Lock file should still exist because PID doesn't match
+    expect(existsSync(lockPath(opHome))).toBe(true);
+  });
+});
+
+// ── lockPath ─────────────────────────────────────────────────────────────
+
+describe("lockPath", () => {
+  it("returns the correct path", () => {
+    expect(lockPath("/home/user/.openpalm")).toBe("/home/user/.openpalm/data/.openpalm.lock");
+  });
+});

package/src/control-plane/lock.ts

@@ -0,0 +1,176 @@
+/**
+ * Orchestrator lock — prevents concurrent mutating operations.
+ *
+ * Uses O_CREAT | O_EXCL for atomic exclusive file creation.
+ * Lock file lives at {dataDir}/.openpalm.lock containing JSON
+ * with { pid, operation, acquiredAt }.
+ *
+ * Uses node:fs (not Bun) since lib must be Node-compatible for SvelteKit admin.
+ */
+import { openSync, writeSync, closeSync, readFileSync, unlinkSync, mkdirSync, constants } from "node:fs";
+import { dirname } from "node:path";
+
+// ── Types ────────────────────────────────────────────────────────────────
+
+export type LockInfo = {
+  pid: number;
+  operation: string;
+  acquiredAt: string;
+};
+
+export type LockHandle = {
+  path: string;
+  info: LockInfo;
+};
+
+// ── Error ────────────────────────────────────────────────────────────────
+
+export class LockAcquisitionError extends Error {
+  public readonly holder: LockInfo;
+
+  constructor(holder: LockInfo) {
+    super(
+      `Cannot acquire lock: already held by PID ${holder.pid} ` +
+      `for "${holder.operation}" since ${holder.acquiredAt}`
+    );
+    this.name = "LockAcquisitionError";
+    this.holder = holder;
+  }
+}
+
+// ── Path ─────────────────────────────────────────────────────────────────
+
+export function lockPath(opHome: string): string {
+  return `${opHome}/data/.openpalm.lock`;
+}
+
+// ── Stale PID Detection ──────────────────────────────────────────────────
+
+function isProcessAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// ── Read existing lock info ──────────────────────────────────────────────
+
+function readLockInfo(path: string): LockInfo | null {
+  try {
+    const content = readFileSync(path, "utf-8");
+    const parsed = JSON.parse(content);
+    if (
+      typeof parsed.pid === "number" &&
+      typeof parsed.operation === "string" &&
+      typeof parsed.acquiredAt === "string"
+    ) {
+      return parsed as LockInfo;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+// ── Acquire / Release ────────────────────────────────────────────────────
+
+export function acquireLock(opHome: string, operation: string): LockHandle {
+  const path = lockPath(opHome);
+  mkdirSync(dirname(path), { recursive: true });
+  const info: LockInfo = {
+    pid: process.pid,
+    operation,
+    acquiredAt: new Date().toISOString(),
+  };
+  const content = JSON.stringify(info) + "\n";
+
+  try {
+    // Atomic exclusive create — fails if file already exists
+    const fd = openSync(path, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL, 0o644);
+    try {
+      writeSync(fd, content);
+    } finally {
+      closeSync(fd);
+    }
+    return { path, info };
+  } catch (err: unknown) {
+    // File already exists — check if it's stale
+    if ((err as NodeJS.ErrnoException).code === "EEXIST") {
+      const existing = readLockInfo(path);
+
+      if (existing && !isProcessAlive(existing.pid)) {
+        // Stale lock — remove and retry once
+        try {
+          unlinkSync(path);
+        } catch {
+          // Race: another process already removed it; fall through to retry
+        }
+        // Retry acquisition
+        try {
+          const fd = openSync(path, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL, 0o644);
+          try {
+            writeSync(fd, content);
+          } finally {
+            closeSync(fd);
+          }
+          return { path, info };
+        } catch (retryErr: unknown) {
+          if ((retryErr as NodeJS.ErrnoException).code === "EEXIST") {
+            // Another process won the race — read the new holder
+            const newHolder = readLockInfo(path);
+            throw new LockAcquisitionError(
+              newHolder ?? { pid: 0, operation: "unknown", acquiredAt: "unknown" }
+            );
+          }
+          throw retryErr;
+        }
+      }
+
+      // Lock is held by a live process (or corrupt file — treat as held)
+      if (existing) {
+        throw new LockAcquisitionError(existing);
+      }
+
+      // Corrupt lock file — remove and retry
+      try {
+        unlinkSync(path);
+      } catch {
+        // ignore
+      }
+      try {
+        const fd = openSync(path, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL, 0o644);
+        try {
+          writeSync(fd, content);
+        } finally {
+          closeSync(fd);
+        }
+        return { path, info };
+      } catch (retryErr: unknown) {
+        if ((retryErr as NodeJS.ErrnoException).code === "EEXIST") {
+          const newHolder = readLockInfo(path);
+          throw new LockAcquisitionError(
+            newHolder ?? { pid: 0, operation: "unknown", acquiredAt: "unknown" }
+          );
+        }
+        throw retryErr;
+      }
+    }
+
+    throw err;
+  }
+}
+
+export function releaseLock(handle: LockHandle): void {
+  // Verify ownership before deleting — only remove if we still own it
+  const existing = readLockInfo(handle.path);
+  if (!existing) return; // Already gone — idempotent
+  if (existing.pid !== handle.info.pid) return; // Not ours — don't touch
+
+  try {
+    unlinkSync(handle.path);
+  } catch {
+    // Already removed — idempotent
+  }
+}

package/src/control-plane/memory-config.ts

@@ -1,18 +1,8 @@
-/**
- * Memory LLM & Embedding configuration management.
- */
+/** Memory LLM & Embedding configuration management. */
 import { mkdirSync, writeFileSync, readFileSync, existsSync, rmSync } from "node:fs";
-import { loadSecretsEnvFile } from "./secrets.js";
-import {
-  LLM_PROVIDERS,
-  EMBEDDING_DIMS,
-  PROVIDER_DEFAULT_URLS,
-} from "../provider-constants.js";
+import { readStackEnv } from "./secrets.js";
+import { EMBEDDING_DIMS, PROVIDER_DEFAULT_URLS } from "../provider-constants.js";
 
-// Re-export shared constants for barrel compatibility
-export { LLM_PROVIDERS, EMBEDDING_DIMS, PROVIDER_DEFAULT_URLS };
-
-// ── Types ────────────────────────────────────────────────────────────────
 
 export type MemoryConfig = {
   mem0: {
@@ -31,7 +21,6 @@ export type MemoryConfig = {
   memory: { custom_instructions: string };
 };
 
-// ── Constants (module-specific) ─────────────────────────────────────────
 
 export const EMBED_PROVIDERS = [
   "openai", "ollama", "huggingface", "lmstudio"
@@ -48,7 +37,6 @@ const ANTHROPIC_MODELS = [
   "claude-3-5-haiku-20241022",
 ];
 
-// ── API Key Resolution ──────────────────────────────────────────────────
 
 export function resolveApiKey(apiKeyRef: string, configDir: string): string {
   if (!apiKeyRef) return "";
@@ -57,11 +45,10 @@ export function resolveApiKey(apiKeyRef: string, configDir: string): string {
   const varName = apiKeyRef.slice(4);
   if (process.env[varName]) return process.env[varName]!;
 
-  const secrets = loadSecretsEnvFile(configDir);
+  const secrets = readStackEnv(configDir);
   return secrets[varName] ?? "";
 }
 
-// ── Provider Model Listing ──────────────────────────────────────────────
 
 export type ModelDiscoveryReason =
   | 'none'
@@ -78,37 +65,15 @@ export type ProviderModelsResult = {
   error?: string;
 };
 
-function describeHttpStatus(status: number): string {
-  switch (status) {
-    case 401: return 'Invalid or missing API key';
-    case 403: return 'Access denied — check API key permissions';
-    case 404: return 'Endpoint not found — verify the base URL';
-    case 429: return 'Rate limited — try again shortly';
-    case 500: return 'Provider internal error';
-    case 502: return 'Provider returned a bad gateway error';
-    case 503: return 'Provider is temporarily unavailable';
-    default:  return `HTTP ${status}`;
-  }
-}
-
-async function extractProviderErrorDetail(res: Response): Promise<string> {
-  try {
-    const text = await res.text();
-    const json = JSON.parse(text) as Record<string, unknown>;
-    if (
-      typeof json.error === 'object' && json.error !== null &&
-      typeof (json.error as Record<string, unknown>).message === 'string'
-    ) {
-      return (json.error as Record<string, unknown>).message as string;
-    }
-    if (typeof json.error === 'string') return json.error;
-    if (typeof json.message === 'string') return json.message;
-    if (typeof json.detail === 'string') return json.detail;
-    return '';
-  } catch {
-    return '';
-  }
-}
+const HTTP_STATUS_LABELS: Record<number, string> = {
+  401: 'Invalid or missing API key',
+  403: 'Access denied — check API key permissions',
+  404: 'Endpoint not found — verify the base URL',
+  429: 'Rate limited — try again shortly',
+  500: 'Provider internal error',
+  502: 'Provider returned a bad gateway error',
+  503: 'Provider is temporarily unavailable',
+};
 
 export async function fetchProviderModels(
   provider: string,
@@ -132,7 +97,7 @@ export async function fetchProviderModels(
           models: [],
           status: 'recoverable_error',
           reason: 'provider_http',
-          error: `Ollama API returned ${res.status}: ${describeHttpStatus(res.status)}`,
+          error: `Ollama API returned ${res.status}: ${(HTTP_STATUS_LABELS[res.status] ?? `HTTP ${res.status}`)}`,
         };
       }
       const data = (await res.json()) as { models?: { name: string }[] };
@@ -158,14 +123,22 @@ export async function fetchProviderModels(
 
     const res = await fetch(url, { headers, signal: AbortSignal.timeout(5000) });
     if (!res.ok) {
-      const detail = await extractProviderErrorDetail(res);
+      let detail = '';
+      try {
+        const json = JSON.parse(await res.text()) as Record<string, unknown>;
+        const errObj = json.error as Record<string, unknown> | string | undefined;
+        detail = (typeof errObj === 'object' && errObj !== null && typeof errObj.message === 'string') ? errObj.message
+          : typeof errObj === 'string' ? errObj
+          : typeof json.message === 'string' ? json.message
+          : typeof json.detail === 'string' ? json.detail : '';
+      } catch { /* ignore parse errors */ }
       return {
         models: [],
         status: 'recoverable_error',
         reason: 'provider_http',
         error: detail
           ? `Provider API returned ${res.status}: ${detail}`
-          : `Provider API returned ${res.status}: ${describeHttpStatus(res.status)}`,
+          : `Provider API returned ${res.status}: ${(HTTP_STATUS_LABELS[res.status] ?? `HTTP ${res.status}`)}`,
       };
     }
     const data = (await res.json()) as { data?: { id: string }[] };
@@ -185,7 +158,6 @@ export async function fetchProviderModels(
   }
 }
 
-// ── Default Config ───────────────────────────────────────────────────────
 
 export function getDefaultConfig(): MemoryConfig {
   return {
@@ -219,66 +191,27 @@ export function getDefaultConfig(): MemoryConfig {
   };
 }
 
-// ── File I/O ─────────────────────────────────────────────────────────────
-
-const CONFIG_FILENAME = "memory/default_config.json";
-
-function configPath(dataDir: string): string {
-  return `${dataDir}/${CONFIG_FILENAME}`;
-}
 
 export function readMemoryConfig(dataDir: string): MemoryConfig {
-  const path = configPath(dataDir);
+  const path = `${dataDir}/memory/default_config.json`;
   if (!existsSync(path)) return getDefaultConfig();
   try {
-    const raw = readFileSync(path, "utf-8");
-    return JSON.parse(raw) as MemoryConfig;
+    return JSON.parse(readFileSync(path, "utf-8")) as MemoryConfig;
   } catch {
     return getDefaultConfig();
   }
 }
 
-export function writeMemoryConfig(
-  dataDir: string,
-  config: MemoryConfig
-): void {
-  const path = configPath(dataDir);
+export function writeMemoryConfig(dataDir: string, config: MemoryConfig): void {
   mkdirSync(`${dataDir}/memory`, { recursive: true });
-  writeFileSync(path, JSON.stringify(config, null, 2) + "\n");
+  writeFileSync(`${dataDir}/memory/default_config.json`, JSON.stringify(config, null, 2) + "\n");
 }
 
 export function ensureMemoryConfig(dataDir: string): void {
-  const path = configPath(dataDir);
-  if (existsSync(path)) return;
+  if (existsSync(`${dataDir}/memory/default_config.json`)) return;
   writeMemoryConfig(dataDir, getDefaultConfig());
 }
 
-// ── Config Resolution ────────────────────────────────────────────────
-
-export function resolveConfigForPush(
-  config: MemoryConfig,
-  configDir: string
-): MemoryConfig {
-  const resolved = structuredClone(config);
-
-  if (typeof resolved.mem0.llm.config.api_key === "string") {
-    resolved.mem0.llm.config.api_key = resolveApiKey(
-      resolved.mem0.llm.config.api_key as string,
-      configDir
-    );
-  }
-
-  if (typeof resolved.mem0.embedder.config.api_key === "string") {
-    resolved.mem0.embedder.config.api_key = resolveApiKey(
-      resolved.mem0.embedder.config.api_key as string,
-      configDir
-    );
-  }
-
-  return resolved;
-}
-
-// ── Dimension Checking ──────────────────────────────────────────────
 
 export type VectorDimensionResult = {
   match: boolean;
@@ -286,9 +219,6 @@ export type VectorDimensionResult = {
   expectedDims: number;
 };
 
-/** @deprecated Use checkVectorDimensions instead */
-export type QdrantDimensionResult = VectorDimensionResult;
-
 export function checkVectorDimensions(
   dataDir: string,
   newConfig: MemoryConfig
@@ -299,9 +229,6 @@ export function checkVectorDimensions(
   return { match: currentDims === expectedDims, currentDims, expectedDims };
 }
 
-/** @deprecated Use checkVectorDimensions instead */
-export const checkQdrantDimensions = checkVectorDimensions;
-
 export function resetVectorStore(
   dataDir: string
 ): { ok: boolean; error?: string } {
@@ -334,79 +261,26 @@ export function resetVectorStore(
   }
 }
 
-/** @deprecated Use resetVectorStore instead */
-export const resetQdrantCollection = resetVectorStore;
-
-// ── Runtime API ──────────────────────────────────────────────────────────
 
-function getMemoryApiBases(): string[] {
-  const configured =
-    process.env.MEMORY_API_URL?.trim() ||
-    process.env.OPENPALM_MEMORY_API_URL?.trim();
-
-  const bases = configured
-    ? [configured]
-    : ["http://memory:8765", "http://127.0.0.1:8765"];
-
-  return Array.from(new Set(bases.map((base) => base.replace(/\/+$/, ""))));
-}
-
-function getMemoryAuthHeaders(): Record<string, string> {
+async function callMemoryApi(path: string, init?: RequestInit): Promise<Response> {
+  const configured = process.env.MEMORY_API_URL?.trim() || process.env.OP_MEMORY_API_URL?.trim();
+  const bases = configured ? [configured.replace(/\/+$/, "")] : ["http://memory:8765", "http://127.0.0.1:8765"];
   const token = process.env.MEMORY_AUTH_TOKEN?.trim();
-  return token ? { authorization: `Bearer ${token}` } : {};
-}
-
-async function callMemoryApi(
-  path: string,
-  init?: RequestInit,
-): Promise<Response> {
-  const bases = getMemoryApiBases();
-  const authHeaders = getMemoryAuthHeaders();
+  const authHeaders: Record<string, string> = token ? { authorization: `Bearer ${token}` } : {};
   let lastError: unknown;
 
   for (let i = 0; i < bases.length; i++) {
-    const url = `${bases[i]}${path}`;
     try {
       const headers = { ...authHeaders, ...(init?.headers as Record<string, string>) };
-      return await fetch(url, { ...init, headers });
+      return await fetch(`${bases[i]}${path}`, { ...init, headers });
     } catch (err) {
       lastError = err;
       if (i === bases.length - 1) throw err;
     }
   }
-
   throw lastError ?? new Error("Memory API request failed");
 }
 
-export async function pushConfigToMemory(
-  config: MemoryConfig
-): Promise<{ ok: boolean; error?: string }> {
-  try {
-    const res = await callMemoryApi("/api/v1/config/", {
-      method: "PUT",
-      headers: { "content-type": "application/json" },
-      body: JSON.stringify(config),
-    });
-    if (!res.ok) {
-      const text = await res.text().catch(() => "");
-      return { ok: false, error: `HTTP ${res.status}: ${text}` };
-    }
-    return { ok: true };
-  } catch (err) {
-    return { ok: false, error: String(err) };
-  }
-}
-
-export async function fetchConfigFromMemory(): Promise<MemoryConfig | null> {
-  try {
-    const res = await callMemoryApi("/api/v1/config/");
-    if (!res.ok) return null;
-    return (await res.json()) as MemoryConfig;
-  } catch {
-    return null;
-  }
-}
-
 export async function provisionMemoryUser(
   userId: string,
 ): Promise<{ ok: boolean; error?: string }> {