@dikolab/kbdb 0.3.2 → 0.4.1

package/src/shared/worker-client/functions/create-worker-client.function.ts

@@ -1,70 +0,0 @@
-import { existsSync, readFileSync, unlinkSync } from 'node:fs';
-import { join } from 'node:path';
-import { tmpdir } from 'node:os';
-import { WorkerClient } from '../classes/worker-client.class.ts';
-import { resolveDbPath } from './resolve-db-path.function.ts';
-import { computeContextId } from './compute-context-id.function.ts';
-import { discoverDaemon } from './discover-daemon.function.ts';
-import { spawnDaemon } from './spawn-daemon.function.ts';
-import { waitForDaemon } from './wait-for-daemon.function.ts';
-import { detectRuntime } from '../../runtime/functions/detect-runtime.ts';
-import { getIpcPath } from '../../platform/functions/get-ipc-path.function.ts';
-import type { WorkerClientOptions } from '../typings/worker-client-options.interface.ts';
-
-/**
- * Creates and connects a `WorkerClient` to the worker daemon.
- *
- * Resolves the context path, derives a stable context identifier,
- * and checks whether a daemon is already running. If no daemon is
- * found and `autoSpawn` is not `false`, a new daemon process is
- * spawned and the factory waits for its PID file to appear before
- * connecting.
- *
- * @param options - optional configuration for path resolution,
- *   auto-spawn behaviour, and connection timeout
- * @returns a connected `WorkerClient` ready to send requests
- * @throws {Error} if the `.kbdb` directory cannot be found
- * @throws {Error} if the socket connection cannot be established
- */
-export async function createWorkerClient(
-   options?: WorkerClientOptions,
-): Promise<WorkerClient> {
-   const dbPath =
-      options?.contextPath ?? resolveDbPath(options?.dbPath);
-   const contextId = await computeContextId(dbPath);
-   const socketPath = getIpcPath(contextId);
-
-   let daemon = discoverDaemon(contextId);
-
-   if (!daemon && options?.autoSpawn !== false) {
-      const runtime = detectRuntime();
-      spawnDaemon(dbPath, runtime, options?.workerScript);
-      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);
-   await client.connect();
-   return client;
-}
-
-function readCrashReason(contextId: string): string {
-   const crashPath = join(tmpdir(), `kbdb-${contextId}.crash`);
-   if (!existsSync(crashPath)) {
-      return 'daemon failed to start (no details available)';
-   }
-   try {
-      const raw = readFileSync(crashPath, 'utf-8');
-      const crash = JSON.parse(raw) as { error?: string };
-      unlinkSync(crashPath);
-      return crash.error ?? 'unknown error (crash log empty)';
-   } catch {
-      return 'daemon failed to start (crash log unreadable)';
-   }
-}

package/src/shared/worker-client/functions/discover-daemon.function.ts

@@ -1,47 +0,0 @@
-import { existsSync, readFileSync, unlinkSync } from 'node:fs';
-import { join } from 'node:path';
-import { tmpdir } from 'node:os';
-import { isProcessAlive } from '../../platform/functions/is-process-alive.function.ts';
-import type { DaemonInfo } from '../typings/daemon-info.model.ts';
-
-export type { DaemonInfo };
-
-/**
- * Discovers a running worker daemon for the given context.
- *
- * Reads the PID file at `<tmpdir>/kbdb-<contextId>.pid`. If the
- * file exists and the process is alive, returns its PID and the
- * expected socket path. If the file is stale (process dead or PID
- * unparseable), removes the PID file and returns `null`.
- *
- * @param contextId - the 16-character context identifier
- * @returns daemon location info, or `null` if no live daemon found
- */
-export function discoverDaemon(contextId: string): DaemonInfo | null {
-   const pidPath = join(tmpdir(), `kbdb-${contextId}.pid`);
-
-   if (!existsSync(pidPath)) return null;
-
-   const pidStr = readFileSync(pidPath, 'utf-8').trim();
-   const pid = parseInt(pidStr, 10);
-
-   if (isNaN(pid) || !isProcessAlive(pid)) {
-      try {
-         unlinkSync(pidPath);
-      } catch {
-         // Stale PID file removal is best-effort
-      }
-      return null;
-   }
-
-   const socketPath = join(tmpdir(), `kbdb-${contextId}.sock`);
-
-   const crashPath = join(tmpdir(), `kbdb-${contextId}.crash`);
-   try {
-      unlinkSync(crashPath);
-   } catch {
-      // stale crash file removal is best-effort
-   }
-
-   return { pid, socketPath };
-}

package/src/shared/worker-client/functions/handle-ipc-data.function.ts

@@ -1,49 +0,0 @@
-import type { PendingCall } from '../typings/pending-call.interface.ts';
-import type { JsonRpcResponse } from '../typings/json-rpc-response.interface.ts';
-
-/**
- * Processes an incoming data chunk from the IPC socket.
- *
- * Appends the chunk to `buffer`, splits on newline boundaries,
- * parses complete JSON-RPC response lines, and resolves or rejects
- * the matching pending call. Returns the updated buffer with any
- * incomplete trailing line retained.
- *
- * @param data - raw string chunk received from the socket
- * @param buffer - partial line buffer from the previous call
- * @param pending - map of outstanding request IDs to their
- *   resolve/reject pairs; mutated by this function
- * @returns the updated buffer (incomplete trailing line, if any)
- */
-export function handleIpcData(
-   data: string,
-   buffer: string,
-   pending: Map<number, PendingCall>,
-): string {
-   const combined = buffer + data;
-   const lines = combined.split('\n');
-   const nextBuffer = lines.pop() ?? '';
-
-   for (const line of lines) {
-      if (!line.trim()) continue;
-      try {
-         const response = JSON.parse(line) as JsonRpcResponse;
-         const call = pending.get(response.id);
-         if (call !== undefined) {
-            pending.delete(response.id);
-            if (response.error !== undefined) {
-               const err = new Error(response.error.message);
-               (err as unknown as Record<string, unknown>)['code'] =
-                  response.error.code;
-               call.reject(err);
-            } else {
-               call.resolve(response.result);
-            }
-         }
-      } catch {
-         // Ignore unparseable lines
-      }
-   }
-
-   return nextBuffer;
-}

package/src/shared/worker-client/functions/resolve-db-path.function.ts

@@ -1,21 +0,0 @@
-import { existsSync } from 'node:fs';
-import { join, resolve } from 'node:path';
-
-/**
- * Resolves the absolute path to the `.kbdb` database directory.
- *
- * Searches for a `.kbdb` sub-directory inside `targetDir`. When
- * `targetDir` is omitted, `process.cwd()` is used as the base.
- *
- * @param targetDir - directory to search in; defaults to cwd
- * @throws {Error} if no `.kbdb` directory exists at the resolved
- *   path
- */
-export function resolveDbPath(targetDir?: string): string {
-   const base = targetDir ? resolve(targetDir) : process.cwd();
-   const dbPath = join(base, '.kbdb');
-   if (!existsSync(dbPath)) {
-      throw new Error(`database not found: ${dbPath}`);
-   }
-   return dbPath;
-}

package/src/shared/worker-client/functions/send-ipc-request.function.ts

@@ -1,39 +0,0 @@
-import type { Socket } from 'node:net';
-import type { PendingCall } from '../typings/pending-call.interface.ts';
-
-/**
- * Sends a JSON-RPC 2.0 request over `socket` and registers the
- * `resolve`/`reject` pair in `pending` so the response can be
- * matched back.
- *
- * @param socket - connected IPC socket
- * @param pending - map of outstanding request IDs to their
- *   resolve/reject pairs; mutated by this function
- * @param nextId - the request ID to assign; must be the current
- *   value of the caller's monotonic counter
- * @param contextId - 16-character context identifier sent as `ctx`
- * @param method - JSON-RPC method name
- * @param params - method parameters (merged with `ctx`)
- * @throws {Error} when the socket is not connected (`socket` is
- *   null) -- call the check before invoking this function
- */
-export function sendIpcRequest(
-   socket: Socket,
-   pending: Map<number, PendingCall>,
-   nextId: number,
-   contextId: string,
-   method: string,
-   params: unknown,
-): Promise<unknown> {
-   const request = {
-      jsonrpc: '2.0',
-      id: nextId,
-      method,
-      params: { ctx: contextId, ...(params as object) },
-   };
-
-   return new Promise<unknown>((resolve, reject) => {
-      pending.set(nextId, { resolve, reject });
-      socket.write(JSON.stringify(request) + '\n');
-   });
-}

package/src/shared/worker-client/functions/spawn-daemon.function.ts

@@ -1,35 +0,0 @@
-import { spawn } from 'node:child_process';
-import type { Runtime } from '../../runtime/typings/runtime.ts';
-
-/**
- * Spawns a detached worker daemon process for the given context.
- *
- * @param contextPath - absolute path to the context directory the
- *   daemon should serve
- * @param runtime - the current JavaScript runtime environment
- * @param workerScript - absolute path to the worker daemon script,
- *   resolved at the entry point by `resolveWorkerScript`
- */
-export function spawnDaemon(
-   contextPath: string,
-   runtime: Runtime,
-   workerScript?: string,
-): void {
-   if (!workerScript) {
-      throw new Error(
-         'workerScript must be provided' + ' (resolve at entry point)',
-      );
-   }
-   const execPath = runtime === 'deno' ? 'deno' : process.execPath;
-
-   const args =
-      runtime === 'deno'
-         ? ['run', '--allow-all', workerScript, contextPath]
-         : [workerScript, contextPath];
-
-   const child = spawn(execPath, args, {
-      detached: true,
-      stdio: 'ignore',
-   });
-   child.unref();
-}

package/src/shared/worker-client/functions/wait-for-daemon.function.ts

@@ -1,34 +0,0 @@
-import { existsSync } from 'node:fs';
-import { join } from 'node:path';
-import { tmpdir } from 'node:os';
-
-/** Default maximum wait time for the daemon PID file to appear. */
-const DEFAULT_TIMEOUT_MS = 10_000;
-
-/** Polling interval in milliseconds between existence checks. */
-const POLL_INTERVAL_MS = 100;
-
-/**
- * Waits for the worker daemon's PID file to appear on disk.
- *
- * Polls every 100 ms until the PID file at
- * `<tmpdir>/kbdb-<contextId>.pid` exists or the timeout elapses.
- *
- * @param contextId - the 16-character context identifier
- * @param timeoutMs - maximum wait time in milliseconds; defaults
- *   to 10 000 ms
- * @returns `true` if the PID file appeared before the timeout,
- *   `false` otherwise
- */
-export async function waitForDaemon(
-   contextId: string,
-   timeoutMs: number = DEFAULT_TIMEOUT_MS,
-): Promise<boolean> {
-   const pidPath = join(tmpdir(), `kbdb-${contextId}.pid`);
-   const start = Date.now();
-   while (Date.now() - start < timeoutMs) {
-      if (existsSync(pidPath)) return true;
-      await new Promise<void>((r) => setTimeout(r, POLL_INTERVAL_MS));
-   }
-   return false;
-}

package/src/shared/worker-client/index.ts

@@ -1,44 +0,0 @@
-export { WorkerClient } from './classes/worker-client.class.ts';
-export { createWorkerClient } from './functions/create-worker-client.function.ts';
-export { resolveDbPath } from './functions/resolve-db-path.function.ts';
-export { computeContextId } from './functions/compute-context-id.function.ts';
-export { discoverDaemon } from './functions/discover-daemon.function.ts';
-export { spawnDaemon } from './functions/spawn-daemon.function.ts';
-export { waitForDaemon } from './functions/wait-for-daemon.function.ts';
-export type { WorkerClientOptions } from './typings/worker-client-options.interface.ts';
-export type { SearchParams } from './typings/search-params.model.ts';
-export type {
-   SearchResult,
-   PagedSearchResult,
-} from './typings/search-result.model.ts';
-export type {
-   Section,
-   AddSectionParams,
-} from './typings/section.model.ts';
-export type { StatusResult } from './typings/status-result.model.ts';
-export type { WorkerClientError } from './typings/worker-client-error.interface.ts';
-export type { DaemonInfo } from './typings/daemon-info.model.ts';
-export type {
-   AddSectionResult,
-   NearDuplicateEntry,
-} from './typings/add-section-result.model.ts';
-export type { RemoveSectionResult } from './typings/remove-section-result.model.ts';
-export type { ContentResult } from './typings/content-result.model.ts';
-export type {
-   IntegrityCheckResult,
-   IntegrityError,
-} from './typings/integrity-check-result.model.ts';
-export type { GcResult } from './typings/gc-result.model.ts';
-export type { RebuildResult } from './typings/rebuild-result.model.ts';
-export type { MigrateResult } from './typings/migrate-result.model.ts';
-export type {
-   VersionCompatibility,
-   VersionStatus,
-} from './typings/version-status.model.ts';
-export type {
-   RecallParams,
-   RecallResult,
-   RecallDocument,
-   RecallSibling,
-   RecallReference,
-} from './typings/recall-result.model.ts';

package/src/shared/worker-client/typings/add-section-result.model.ts

@@ -1,39 +0,0 @@
-/**
- * A near-duplicate section reported after adding a new section.
- */
-export interface NearDuplicateEntry {
-   /** Knowledge-base identifier of the near-duplicate section. */
-   readonly kbid: string;
-   /** Jaccard similarity score (0.0--1.0). */
-   readonly similarity: number;
-   /** Detection method that produced this match. */
-   readonly method?: 'jaccard' | 'cosine';
-}
-
-/** Result returned by the daemon after adding a new section. */
-export interface AddSectionResult {
-   /** Knowledge-base identifier assigned to the section. */
-   readonly kbid: string;
-   /**
-    * Number of unique terms indexed for the section.
-    * Present in the current binary-decoded response format.
-    */
-   readonly indexed_terms_count?: number;
-   /**
-    * Wall-clock time the add operation took, in milliseconds.
-    * Present in the current binary-decoded response format.
-    */
-   readonly elapsed_ms?: number;
-   /**
-    * Knowledge-base identifier of the section that was superseded,
-    * or `null` if no supersession occurred.
-    */
-   readonly superseded?: string | null;
-   /** Advisory warnings emitted during indexing. */
-   readonly warnings?: string[];
-   /**
-    * Near-duplicate sections detected above the similarity threshold
-    * (Jaccard >= 0.85).
-    */
-   readonly near_duplicates?: NearDuplicateEntry[];
-}

package/src/shared/worker-client/typings/content-result.model.ts

@@ -1,12 +0,0 @@
-/**
- * Result returned by the daemon after composing a Markdown document
- * from one or more kbid or docid identifiers.
- */
-export interface ContentResult {
-   /** MIME type of the composed output, always `'text/markdown'`. */
-   readonly type: 'text/markdown';
-   /** The composed Markdown string. */
-   readonly data: string;
-   /** Character count of `data` (not byte count). */
-   readonly total: number;
-}

package/src/shared/worker-client/typings/daemon-info.model.ts

@@ -1,7 +0,0 @@
-/** Location information for a running worker daemon process. */
-export interface DaemonInfo {
-   /** PID of the running daemon process. */
-   readonly pid: number;
-   /** Absolute path to the daemon's IPC socket. */
-   readonly socketPath: string;
-}

package/src/shared/worker-client/typings/export-result.model.ts

@@ -1,14 +0,0 @@
-/**
- * Report returned by the daemon after exporting the database to a
- * target directory.
- */
-export interface ExportResult {
-   /** Absolute path to the directory where files were written. */
-   readonly path: string;
-   /** Number of section files copied to the export directory. */
-   readonly sections_exported: number;
-   /** Number of document manifest files copied. */
-   readonly documents_exported: number;
-   /** Wall-clock time the export operation took, in milliseconds. */
-   readonly elapsed_ms: number;
-}

package/src/shared/worker-client/typings/gc-result.model.ts

@@ -1,18 +0,0 @@
-/**
- * Report returned by the daemon after running garbage collection
- * on the knowledge-base database.
- */
-export interface GcResult {
-   /** Number of unreferenced sections removed. */
-   readonly removed_sections: number;
-   /** Total bytes freed by removing unreferenced sections. */
-   readonly removed_bytes: number;
-   /** Time taken to complete garbage collection, in milliseconds. */
-   readonly elapsed_ms: number;
-   /**
-    * Number of sections whose source_path file no longer contains
-    * their heading text. Advisory; not auto-removed by gc.
-    * Absent on older daemon versions.
-    */
-   readonly stale_sources?: number;
-}

package/src/shared/worker-client/typings/integrity-check-result.model.ts

@@ -1,43 +0,0 @@
-/** A single integrity error found during a database check. */
-export interface IntegrityError {
-   /**
-    * The category of integrity violation detected.
-    *
-    * - `'checksum_mismatch'` -- stored content does not match its hash
-    * - `'orphan_section'` -- section not referenced by any document
-    * - `'orphan_document'` -- document references no existing sections
-    * - `'broken_reference'` -- a marker references a non-existent entity
-    * - `'type_mismatch'` -- stored MIME type conflicts with content
-    * - `'circular_reference'` -- marker chain contains a cycle
-    */
-   readonly type:
-      | 'checksum_mismatch'
-      | 'orphan_section'
-      | 'orphan_document'
-      | 'broken_reference'
-      | 'type_mismatch'
-      | 'circular_reference';
-   /** Identifier of the entity (kbid or docid) that has the issue. */
-   readonly entity: string;
-   /** Human-readable description of the specific problem. */
-   readonly detail: string;
-}
-
-/**
- * Report returned by the daemon after running an integrity check
- * on the knowledge-base database.
- */
-export interface IntegrityCheckResult {
-   /** `true` when all checks passed and no errors were found. */
-   readonly ok: boolean;
-   /** All integrity errors found; empty when `ok` is `true`. */
-   readonly errors: IntegrityError[];
-   /** Total number of sections examined. */
-   readonly sections_checked: number;
-   /** Total number of documents examined. */
-   readonly documents_checked: number;
-   /** Total number of marker references checked. */
-   readonly references_checked: number;
-   /** Time taken to complete the check, in milliseconds. */
-   readonly elapsed_ms: number;
-}

package/src/shared/worker-client/typings/json-rpc-response.interface.ts

@@ -1,17 +0,0 @@
-/** Shape of a JSON-RPC 2.0 error object from the daemon. */
-export interface JsonRpcError {
-   /** Numeric JSON-RPC error code. */
-   readonly code: number;
-   /** Human-readable error message. */
-   readonly message: string;
-}
-
-/** Shape of a JSON-RPC 2.0 response from the daemon. */
-export interface JsonRpcResponse {
-   /** Monotonically increasing request identifier. */
-   readonly id: number;
-   /** Result payload; present on success. */
-   readonly result?: unknown;
-   /** Error detail; present on failure. */
-   readonly error?: JsonRpcError;
-}

package/src/shared/worker-client/typings/migrate-result.model.ts

@@ -1,11 +0,0 @@
-/**
- * Report returned by the daemon after running database migrations.
- */
-export interface MigrateResult {
-   /** The database format version before migration. */
-   readonly oldVersion: number;
-   /** The database format version after migration. */
-   readonly newVersion: number;
-   /** Number of individual migration steps that were applied. */
-   readonly migrationsRun: number;
-}

package/src/shared/worker-client/typings/pending-call.interface.ts

@@ -1,7 +0,0 @@
-/** Pending JSON-RPC call awaiting a response from the daemon. */
-export interface PendingCall {
-   /** Resolves with the result when the daemon responds. */
-   resolve: (v: unknown) => void;
-   /** Rejects with an error when the daemon returns an error. */
-   reject: (e: Error) => void;
-}

package/src/shared/worker-client/typings/rebuild-result.model.ts

@@ -1,12 +0,0 @@
-/**
- * Report returned by the daemon after rebuilding all database indexes
- * from section files and document manifests.
- */
-export interface RebuildResult {
-   /** Number of text and code sections that were re-indexed. */
-   readonly sections_reindexed: number;
-   /** Total number of unique terms written to the rebuilt indexes. */
-   readonly terms_indexed: number;
-   /** Time taken to complete the rebuild, in milliseconds. */
-   readonly elapsed_ms: number;
-}

package/src/shared/worker-client/typings/recall-document.model.ts

@@ -1,16 +0,0 @@
-/** A document record included at depth >= 1. */
-export interface RecallDocument {
-   /** Unique document identifier. */
-   readonly docid: string;
-   /** Human-readable document title. */
-   readonly title: string;
-   /** Ordered list of section summaries belonging to this document. */
-   readonly sections: readonly {
-      /** Knowledge-base identifier of the section. */
-      readonly kbid: string;
-      /** Section heading text, or `null` when absent. */
-      readonly heading: string | null;
-      /** Semantic type label for the section. */
-      readonly type: string;
-   }[];
-}

package/src/shared/worker-client/typings/recall-params.model.ts

@@ -1,15 +0,0 @@
-/** Parameters for a recall operation. */
-export interface RecallParams {
-   /** Single section identifier to recall. */
-   readonly kbid?: string;
-   /** Batch of section identifiers to recall. */
-   readonly kbids?: readonly string[];
-   /**
-    * Context expansion depth (0-3).
-    *
-    * At depth 0 only the section itself is returned.
-    * Higher values include progressively more context:
-    * documents, siblings, and references.
-    */
-   readonly depth?: number;
-}

package/src/shared/worker-client/typings/recall-reference.model.ts

@@ -1,32 +0,0 @@
-/**
- * A section that references or is referenced by the recalled
- * section.
- */
-export interface RecallReference {
-   /**
-    * Knowledge-base identifier of the referencing/referenced
-    * section.
-    */
-   readonly kbid: string;
-   /**
-    * Heading text of the referencing section, or `null` when
-    * absent.
-    */
-   readonly heading: string | null;
-   /** Semantic type label of the referencing section. */
-   readonly type: string;
-   /**
-    * Application-level marker type (e.g. `'see_also'`, `'link'`).
-    */
-   readonly marker_type: string;
-   /**
-    * Short excerpt from the referencing section surrounding the
-    * marker.
-    */
-   readonly context_snippet: string;
-   /**
-    * Whether the reference is `'forward'` (outgoing) or `'back'`
-    * (incoming).
-    */
-   readonly direction: 'forward' | 'back';
-}