@dikolab/kbdb 0.3.2 → 0.4.1

package/dist/mod.mjs

@@ -1,18 +1,133 @@
 // src/shared/version/constants/version.constant.ts
-var VERSION = "0.2.2";
+var VERSION = "0.4.1";
 
 // src/shared/worker-client/classes/worker-client.class.ts
 import { connect } from "node:net";
+
+// src/shared/worker-client/functions/discover-daemon.function.ts
+import { existsSync, readFileSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+// src/shared/platform/functions/is-process-alive.function.ts
+function isProcessAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// src/shared/log/typings/log-level.type.ts
+var LogLevel = /* @__PURE__ */ ((LogLevel2) => {
+  LogLevel2[LogLevel2["DEBUG"] = 0] = "DEBUG";
+  LogLevel2[LogLevel2["INFO"] = 1] = "INFO";
+  LogLevel2[LogLevel2["WARNING"] = 2] = "WARNING";
+  LogLevel2[LogLevel2["ERROR"] = 3] = "ERROR";
+  return LogLevel2;
+})(LogLevel || {});
+
+// src/shared/log/constants/log-colors.constant.ts
+var ANSI_RESET = "\x1B[0m";
+var LOG_COLORS = {
+  [0 /* DEBUG */]: "\x1B[37m",
+  [1 /* INFO */]: "\x1B[36m",
+  [2 /* WARNING */]: "\x1B[33m",
+  [3 /* ERROR */]: "\x1B[91m"
+};
+
+// src/shared/log/constants/log-icons.constant.ts
+var LOG_ICONS = {
+  [0 /* DEBUG */]: "\u25B8",
+  [1 /* INFO */]: "\u2139",
+  [2 /* WARNING */]: "\u26A0",
+  [3 /* ERROR */]: "\u2716"
+};
+
+// src/shared/log/constants/log-defaults.constant.ts
+var DEFAULT_LOG_LEVEL = 3 /* ERROR */;
+
+// src/shared/log/functions/write-stderr.function.ts
+function writeStderr(message) {
+  const g = globalThis;
+  const proc = g["process"];
+  if (proc?.stderr) {
+    proc.stderr.write(message);
+    return;
+  }
+  const deno = g["Deno"];
+  deno?.stderr.writeSync(new TextEncoder().encode(message));
+}
+
+// src/shared/log/functions/log.function.ts
+var currentLevel = DEFAULT_LOG_LEVEL;
+var outputs = {
+  [0 /* DEBUG */]: writeStderr,
+  [1 /* INFO */]: writeStderr,
+  [2 /* WARNING */]: writeStderr,
+  [3 /* ERROR */]: writeStderr
+};
+function log(message, level = 3 /* ERROR */) {
+  if (level < currentLevel) {
+    return;
+  }
+  const color = LOG_COLORS[level];
+  const icon = LOG_ICONS[level];
+  const name = LogLevel[level];
+  const line = `${color}${icon} [${name}] ${message}${ANSI_RESET}
+`;
+  outputs[level](line);
+}
+
+// src/shared/worker-client/functions/discover-daemon.function.ts
+function discoverDaemon(contextId) {
+  log("discovering daemon for context: " + contextId, 0 /* DEBUG */);
+  const pidPath = join(tmpdir(), `kbdb-${contextId}.pid`);
+  if (!existsSync(pidPath)) {
+    log(
+      "no daemon PID file found for context: " + contextId,
+      0 /* DEBUG */
+    );
+    return null;
+  }
+  const pidStr = readFileSync(pidPath, "utf-8").trim();
+  const pid = parseInt(pidStr, 10);
+  if (isNaN(pid) || !isProcessAlive(pid)) {
+    log(
+      "daemon process not alive for context: " + contextId,
+      0 /* DEBUG */
+    );
+    try {
+      unlinkSync(pidPath);
+    } catch {
+    }
+    return null;
+  }
+  log("daemon found: pid=" + pid.toString(), 0 /* DEBUG */);
+  const socketPath = join(tmpdir(), `kbdb-${contextId}.sock`);
+  const crashPath = join(tmpdir(), `kbdb-${contextId}.crash`);
+  try {
+    unlinkSync(crashPath);
+  } catch {
+  }
+  return { pid, socketPath };
+}
+
+// src/shared/worker-client/classes/worker-client.class.ts
 var WorkerClient = class {
   /**
    * @param socketPath - absolute path to the daemon's IPC socket
    *   (or Windows named pipe path)
    * @param contextId - 16-character context identifier sent as
    *   `ctx` in every JSON-RPC request
+   * @param requestTimeoutMs - per-request timeout in ms
+   *   (0 or undefined disables the timeout)
    */
-  constructor(socketPath, contextId) {
+  constructor(socketPath, contextId, requestTimeoutMs) {
     this.socketPath = socketPath;
     this.contextId = contextId;
+    this.requestTimeoutMs = requestTimeoutMs;
   }
   /** Underlying socket; `null` when not connected. */
   socket = null;
@@ -22,30 +137,121 @@ var WorkerClient = class {
   pending = /* @__PURE__ */ new Map();
   /** Partial line buffer for split TCP/IPC frames. */
   buffer = "";
+  /** Whether the underlying socket is connected. */
+  get isConnected() {
+    return this.socket !== null;
+  }
   /**
    * Establishes the IPC connection to the worker daemon.
    *
+   * Retries up to 5 times with exponential backoff on
+   * transient errors (`ENOENT`, `ECONNREFUSED`).
+   *
    * @throws {Error} if the connection cannot be established
    */
   async connect() {
+    log("connecting to " + this.socketPath, 0 /* DEBUG */);
+    const maxRetries = 5;
+    let delay = 50;
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+      try {
+        await this.tryConnect();
+        log("connected", 0 /* DEBUG */);
+        return;
+      } catch (err) {
+        const code = err.code;
+        const retriable = code === "ENOENT" || code === "ECONNREFUSED";
+        if (!retriable || attempt === maxRetries) {
+          throw err;
+        }
+        log(
+          "connect retry: attempt=" + attempt.toString() + " code=" + code + " delay=" + delay.toString() + "ms",
+          0 /* DEBUG */
+        );
+        await new Promise((r) => setTimeout(r, delay));
+        delay = Math.min(delay * 2, 1e3);
+      }
+    }
+  }
+  /** Destroys the IPC socket and clears the connection state. */
+  disconnect() {
+    log("disconnecting client", 0 /* DEBUG */);
+    if (this.socket) {
+      this.socket.destroy();
+      this.socket = null;
+    }
+  }
+  /**
+   * Kills the daemon process and disconnects the client.
+   *
+   * Discovers the daemon via PID file and sends `SIGTERM`.
+   * Always disconnects the socket regardless of kill outcome.
+   */
+  killDaemon() {
+    const info = discoverDaemon(this.contextId);
+    log(
+      "killing daemon: pid=" + (info ? info.pid.toString() : "unknown"),
+      0 /* DEBUG */
+    );
+    if (info) {
+      try {
+        process.kill(info.pid, "SIGTERM");
+      } catch {
+      }
+    }
+    this.disconnect();
+  }
+  /**
+   * Single connection attempt with keepalive and
+   * post-connect failure handlers.
+   */
+  async tryConnect() {
     return new Promise((resolve2, reject) => {
-      this.socket = connect(this.socketPath, () => {
+      const sock = connect(this.socketPath, () => {
+        sock.removeListener("error", reject);
+        sock.setKeepAlive(true, 3e4);
+        sock.on("error", (err) => {
+          log(
+            "socket error: code=" + (err.code ?? err.message),
+            0 /* DEBUG */
+          );
+          this.handleSocketFailure(err);
+        });
+        sock.on("close", () => {
+          log("socket closed", 0 /* DEBUG */);
+          if (this.pending.size > 0) {
+            this.handleSocketFailure(
+              new Error("connection closed")
+            );
+          }
+          this.socket = null;
+        });
+        this.socket = sock;
         resolve2();
       });
-      this.socket.on("error", (err) => {
-        reject(err);
-      });
-      this.socket.on("data", (chunk) => {
+      sock.on("error", reject);
+      sock.on("data", (chunk) => {
         this.handleData(chunk.toString());
       });
     });
   }
-  /** Destroys the IPC socket and clears the connection state. */
-  disconnect() {
-    if (this.socket) {
-      this.socket.destroy();
-      this.socket = null;
+  /**
+   * Rejects all pending calls and marks the client as
+   * disconnected.
+   */
+  handleSocketFailure(err) {
+    log(
+      "socket failure: pending=" + this.pending.size.toString() + " err=" + err.message,
+      0 /* DEBUG */
+    );
+    const sock = this.socket;
+    this.socket = null;
+    for (const [id, call] of this.pending) {
+      this.pending.delete(id);
+      if (call.timer) clearTimeout(call.timer);
+      call.reject(err);
     }
+    if (sock) sock.destroy();
   }
   /**
    * Searches the knowledge base.
@@ -54,7 +260,10 @@ var WorkerClient = class {
    * @returns paginated search results with metadata
    */
   async search(params) {
-    return this.call("search", params);
+    return this.call("search", {
+      ...params,
+      algo: params.algo
+    });
   }
   /**
    * Retrieves full content and context for one or more sections by
@@ -305,7 +514,20 @@ var WorkerClient = class {
    */
   async export(params) {
     return this.call("export", {
-      targetPath: params?.path || void 0
+      targetPath: params?.path || void 0,
+      format: params?.format
+    });
+  }
+  /**
+   * Imports an exported database from the given path.
+   *
+   * @param params - source path and dry-run flag
+   * @returns import report with counts and timing
+   */
+  async import(params) {
+    return this.call("importDb", {
+      sourcePath: params.from,
+      dryRun: params.dryRun
     });
   }
   /**
@@ -322,14 +544,35 @@ var WorkerClient = class {
       throw new Error("not connected");
     }
     const id = this.nextId++;
+    log(
+      "call: method=" + method + " id=" + id.toString(),
+      0 /* DEBUG */
+    );
     const request = {
       jsonrpc: "2.0",
       id,
       method,
       params: { ctx: this.contextId, ...params }
     };
+    const timeoutMs = this.requestTimeoutMs;
     return new Promise((resolve2, reject) => {
-      this.pending.set(id, { resolve: resolve2, reject });
+      const call = { resolve: resolve2, reject };
+      if (timeoutMs) {
+        call.timer = setTimeout(() => {
+          if (!this.pending.has(id)) return;
+          this.pending.delete(id);
+          log(
+            "request timeout after " + String(timeoutMs) + "ms",
+            2 /* WARNING */
+          );
+          const err = new Error(
+            `request timeout after ${String(timeoutMs)}ms`
+          );
+          err.code = "REQUEST_TIMEOUT";
+          reject(err);
+        }, timeoutMs);
+      }
+      this.pending.set(id, call);
       socket.write(JSON.stringify(request) + "\n");
     });
   }
@@ -350,15 +593,33 @@ var WorkerClient = class {
         const pending = this.pending.get(response.id);
         if (pending) {
           this.pending.delete(response.id);
+          if (pending.timer) clearTimeout(pending.timer);
           if (response.error) {
+            log(
+              "response error: id=" + response.id.toString() + " code=" + response.error.code.toString(),
+              0 /* DEBUG */
+            );
             const err = new Error(response.error.message);
             err.code = response.error.code;
             pending.reject(err);
           } else {
+            log(
+              "response ok: id=" + response.id.toString(),
+              0 /* DEBUG */
+            );
             pending.resolve(response.result);
           }
+        } else {
+          log(
+            "unmatched response id=" + response.id.toString(),
+            0 /* DEBUG */
+          );
         }
-      } catch {
+      } catch (parseErr) {
+        log(
+          "json parse error: " + parseErr.message,
+          0 /* DEBUG */
+        );
       }
     }
   }
@@ -370,13 +631,15 @@ import { join as join5 } from "node:path";
 import { tmpdir as tmpdir4 } from "node:os";
 
 // src/shared/worker-client/functions/resolve-db-path.function.ts
-import { existsSync } from "node:fs";
-import { join, resolve } from "node:path";
+import { existsSync as existsSync2 } from "node:fs";
+import { join as join2, resolve } from "node:path";
 function resolveDbPath(targetDir) {
   const base = targetDir ? resolve(targetDir) : process.cwd();
-  const dbPath = join(base, ".kbdb");
-  if (!existsSync(dbPath)) {
-    throw new Error(`database not found: ${dbPath}`);
+  const dbPath = join2(base, ".kbdb");
+  if (!existsSync2(dbPath)) {
+    const msg = `database not found: ${dbPath}`;
+    log(msg, 3 /* ERROR */);
+    throw new Error(msg);
   }
   return dbPath;
 }
@@ -395,53 +658,22 @@ async function computeContextId(absolutePath) {
   return hash.slice(0, 16);
 }
 
-// src/shared/worker-client/functions/discover-daemon.function.ts
-import { existsSync as existsSync2, readFileSync, unlinkSync } from "node:fs";
-import { join as join2 } from "node:path";
-import { tmpdir } from "node:os";
-
-// src/shared/platform/functions/is-process-alive.function.ts
-function isProcessAlive(pid) {
-  try {
-    process.kill(pid, 0);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-// src/shared/worker-client/functions/discover-daemon.function.ts
-function discoverDaemon(contextId) {
-  const pidPath = join2(tmpdir(), `kbdb-${contextId}.pid`);
-  if (!existsSync2(pidPath)) return null;
-  const pidStr = readFileSync(pidPath, "utf-8").trim();
-  const pid = parseInt(pidStr, 10);
-  if (isNaN(pid) || !isProcessAlive(pid)) {
-    try {
-      unlinkSync(pidPath);
-    } catch {
-    }
-    return null;
-  }
-  const socketPath = join2(tmpdir(), `kbdb-${contextId}.sock`);
-  const crashPath = join2(tmpdir(), `kbdb-${contextId}.crash`);
-  try {
-    unlinkSync(crashPath);
-  } catch {
-  }
-  return { pid, socketPath };
-}
-
 // src/shared/worker-client/functions/spawn-daemon.function.ts
 import { spawn } from "node:child_process";
 function spawnDaemon(contextPath, runtime, workerScript) {
   if (!workerScript) {
-    throw new Error(
-      "workerScript must be provided (resolve at entry point)"
-    );
+    const msg = "workerScript must be provided (resolve at entry point)";
+    log(msg, 3 /* ERROR */);
+    throw new Error(msg);
   }
   const execPath = runtime === "deno" ? "deno" : process.execPath;
-  const args = runtime === "deno" ? ["run", "--allow-all", workerScript, contextPath] : [workerScript, contextPath];
+  const logLevelEnv = process.env["KBDB_LOG_LEVEL"];
+  const logArgs = logLevelEnv ? ["--log-level", logLevelEnv] : [];
+  const args = runtime === "deno" ? ["run", "--allow-all", workerScript, contextPath, ...logArgs] : [workerScript, contextPath, ...logArgs];
+  log(
+    "spawning daemon: " + execPath + " " + args.join(" "),
+    0 /* DEBUG */
+  );
   const child = spawn(execPath, args, {
     detached: true,
     stdio: "ignore"
@@ -456,12 +688,30 @@ import { tmpdir as tmpdir2 } from "node:os";
 var DEFAULT_TIMEOUT_MS = 1e4;
 var POLL_INTERVAL_MS = 100;
 async function waitForDaemon(contextId, timeoutMs = DEFAULT_TIMEOUT_MS) {
+  log("waiting for daemon: contextId=" + contextId, 0 /* DEBUG */);
   const pidPath = join3(tmpdir2(), `kbdb-${contextId}.pid`);
   const start = Date.now();
+  let iteration = 0;
   while (Date.now() - start < timeoutMs) {
-    if (existsSync3(pidPath)) return true;
+    if (existsSync3(pidPath)) {
+      log("daemon PID file appeared", 0 /* DEBUG */);
+      return true;
+    }
+    iteration++;
+    if (iteration % 10 === 0) {
+      const elapsed2 = Date.now() - start;
+      log(
+        "still waiting for daemon: elapsed=" + elapsed2.toString() + "ms",
+        0 /* DEBUG */
+      );
+    }
     await new Promise((r) => setTimeout(r, POLL_INTERVAL_MS));
   }
+  const elapsed = Date.now() - start;
+  log(
+    "timed out waiting for daemon: elapsed=" + elapsed.toString() + "ms",
+    0 /* DEBUG */
+  );
   return false;
 }
 
@@ -494,20 +744,33 @@ function getIpcPath(ctx) {
 async function createWorkerClient(options) {
   const dbPath = options?.contextPath ?? resolveDbPath(options?.dbPath);
   const contextId = await computeContextId(dbPath);
+  log("create-worker-client: contextId=" + contextId, 0 /* DEBUG */);
   const socketPath = getIpcPath(contextId);
   let daemon = discoverDaemon(contextId);
+  if (daemon) {
+    log("daemon found: pid=" + daemon.pid.toString(), 0 /* DEBUG */);
+  } else {
+    log("no daemon found", 0 /* DEBUG */);
+  }
   if (!daemon && options?.autoSpawn !== false) {
     const runtime = detectRuntime();
+    log("auto-spawning daemon", 0 /* DEBUG */);
     spawnDaemon(dbPath, runtime, options?.workerScript);
+    log("waiting for daemon after spawn", 0 /* DEBUG */);
     await waitForDaemon(contextId, options?.connectTimeoutMs);
     daemon = discoverDaemon(contextId);
   }
   if (!daemon) {
-    throw new Error(
-      `kbdb worker daemon did not start: ${readCrashReason(contextId)}`
-    );
-  }
-  const client = new WorkerClient(socketPath, contextId);
+    const msg = `kbdb worker daemon did not start: ${readCrashReason(contextId)}`;
+    log(msg, 3 /* ERROR */);
+    throw new Error(msg);
+  }
+  log("connecting to daemon", 0 /* DEBUG */);
+  const client = new WorkerClient(
+    socketPath,
+    contextId,
+    options?.requestTimeoutMs
+  );
   await client.connect();
   return client;
 }
@@ -525,10 +788,28 @@ function readCrashReason(contextId) {
     return "daemon failed to start (crash log unreadable)";
   }
 }
+
+// src/shared/worker-client/functions/get-or-create-client.function.ts
+var cache = /* @__PURE__ */ new Map();
+async function getOrCreateClient(options) {
+  log("getOrCreateClient called", 0 /* DEBUG */);
+  const dbPath = options?.contextPath ?? resolveDbPath(options?.dbPath);
+  const cached = cache.get(dbPath);
+  if (cached?.isConnected) {
+    log("returning cached client for: " + dbPath, 0 /* DEBUG */);
+    return cached;
+  }
+  cache.delete(dbPath);
+  log("creating new client for: " + dbPath, 0 /* DEBUG */);
+  const client = await createWorkerClient(options);
+  cache.set(dbPath, client);
+  return client;
+}
 export {
   WorkerClient,
   computeContextId,
   createWorkerClient,
+  getOrCreateClient,
   resolveDbPath,
   VERSION as version
 };