@dikolab/kbdb 0.3.2 → 0.4.0

package/src/shared/mcp/functions/should-emit-log.function.ts

@@ -1,38 +0,0 @@
-import type { McpLogLevel } from '../typings/log-types.interface.ts';
-
-/**
- * Ordered list of MCP log severity levels, from least severe
- * (`debug`) to most severe (`emergency`). Used to compare levels
- * when filtering log output.
- */
-export const LOG_LEVEL_ORDER: McpLogLevel[] = [
-   'debug',
-   'info',
-   'notice',
-   'warning',
-   'error',
-   'critical',
-   'alert',
-   'emergency',
-];
-
-/**
- * Determines whether a log message at `messageLevel` should be
- * emitted when the server's log threshold is `threshold`.
- *
- * Returns `true` when `messageLevel` is at the same severity as
- * `threshold` or higher. Returns `false` when the message level is
- * below the threshold.
- *
- * @param messageLevel - severity of the log message to evaluate
- * @param threshold - minimum severity level required to emit
- * @returns `true` if the message meets or exceeds the threshold
- */
-export function shouldEmitLog(
-   messageLevel: McpLogLevel,
-   threshold: McpLogLevel,
-): boolean {
-   const messageIndex = LOG_LEVEL_ORDER.indexOf(messageLevel);
-   const thresholdIndex = LOG_LEVEL_ORDER.indexOf(threshold);
-   return messageIndex >= thresholdIndex;
-}

package/src/shared/mcp/index.ts

@@ -1,28 +0,0 @@
-export { McpServer } from './classes/mcp-server.class.ts';
-export { createMcpServer } from './functions/create-mcp-server.function.ts';
-export { createToolDefinitions } from './functions/create-tool-definitions.function.ts';
-export { createResourceTemplates } from './functions/create-resource-templates.function.ts';
-export { handleToolCall } from './functions/handle-tool-call.function.ts';
-export { handleResourceRead } from './functions/handle-resource-read.function.ts';
-export {
-   PARSE_ERROR,
-   METHOD_NOT_FOUND,
-   INVALID_PARAMS,
-   INTERNAL_ERROR,
-   RESOURCE_NOT_FOUND,
-} from './constants/mcp-error-codes.constant.ts';
-export type {
-   McpRequest,
-   McpResponse,
-   McpNotification,
-   McpToolDefinition,
-   McpResourceTemplate,
-   McpServerInfo,
-   McpCapabilities,
-   McpToolResult,
-   McpResourceResult,
-} from './typings/mcp-types.interface.ts';
-export type {
-   McpWorkerClient,
-   RemoveSectionResult,
-} from './typings/mcp-client.interface.ts';

package/src/shared/mcp/typings/agent-types.interface.ts

@@ -1,39 +0,0 @@
-/**
- * A reference from an agent document to a skill section,
- * carrying the skill's position within the agent's ordered
- * skill list.
- */
-export interface AgentSkillRef {
-   /** Knowledge-base identifier of the referenced skill section. */
-   readonly kbid: string;
-   /**
-    * Human-readable name of the skill, or `null` when the
-    * referenced section no longer exists (dangling reference).
-    */
-   readonly name: string | null;
-   /** Zero-based position of this skill within the agent's list. */
-   readonly position: number;
-}
-
-/**
- * Full definition of an agent, including its persona text and
- * ordered list of skill references.
- */
-export interface AgentDefinition {
-   /** Unique document identifier for the agent. */
-   readonly docid: string;
-   /** Human-readable name of the agent. */
-   readonly name: string;
-   /**
-    * Short description of what the agent does, used for discovery
-    * and disambiguation.
-    */
-   readonly description: string;
-   /**
-    * Persona text that governs how the agent behaves when
-    * executing tasks.
-    */
-   readonly persona: string;
-   /** Ordered list of skill references the agent can delegate to. */
-   readonly skills: readonly AgentSkillRef[];
-}

package/src/shared/mcp/typings/log-types.interface.ts

@@ -1,26 +0,0 @@
-/**
- * Severity levels for MCP log messages, ordered from least severe
- * (`debug`) to most severe (`emergency`).
- */
-export type McpLogLevel =
-   | 'debug'
-   | 'info'
-   | 'notice'
-   | 'warning'
-   | 'error'
-   | 'critical'
-   | 'alert'
-   | 'emergency';
-
-/**
- * A structured log message emitted by the MCP server via the
- * `notifications/message` notification method.
- */
-export interface McpLogMessage {
-   /** Severity level of the log entry. */
-   readonly level: McpLogLevel;
-   /** Optional logger name identifying the source component. */
-   readonly logger?: string;
-   /** Optional structured payload associated with the log entry. */
-   readonly data?: unknown;
-}

package/src/shared/mcp/typings/mcp-capabilities.interface.ts

@@ -1,16 +0,0 @@
-/** MCP capability flags advertised during initialization. */
-export interface McpCapabilities {
-   /** Indicates the server supports the tools capability. */
-   readonly tools?: Record<string, unknown>;
-   /** Indicates the server supports the resources capability. */
-   readonly resources?: Record<string, unknown>;
-   /** Indicates the server supports the prompts capability. */
-   readonly prompts?: Record<string, unknown>;
-   /** Indicates the server supports the logging capability. */
-   readonly logging?: Record<string, unknown>;
-   /**
-    * Indicates the server supports the completions capability,
-    * providing argument auto-completion for prompts and resources.
-    */
-   readonly completions?: Record<string, unknown>;
-}

package/src/shared/mcp/typings/mcp-client.interface.ts

@@ -1,317 +0,0 @@
-import type { AddSectionResult } from '../../worker-client/typings/add-section-result.model.ts';
-import type { RemoveSectionResult } from './remove-section-result.model.ts';
-import type { SectionRecord } from '../../wasm-codec/functions/decode-section-records.function.ts';
-import type { DocumentManifest } from '../../wasm-codec/functions/decode-document-manifest.function.ts';
-
-/** Result returned by content composition. */
-export interface McpContentResult {
-   /** 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;
-}
-
-/** A single integrity error found during a database check. */
-export interface McpIntegrityError {
-   /** The category of integrity violation detected. */
-   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;
-}
-
-/** Integrity check report returned by the daemon. */
-export interface McpIntegrityCheckResult {
-   /** `true` when all checks passed and no errors were found. */
-   readonly ok: boolean;
-   /** All integrity errors found; empty when `ok` is `true`. */
-   readonly errors: McpIntegrityError[];
-   /** 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;
-}
-
-/** Export report returned by the daemon. */
-export interface McpExportResult {
-   /** 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;
-   /** Time taken to complete the export, in milliseconds. */
-   readonly elapsed_ms: number;
-}
-
-/** Garbage collection report returned by the daemon. */
-export interface McpGcResult {
-   /** 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;
-}
-
-/** Index rebuild report returned by the daemon. */
-export interface McpRebuildResult {
-   /** 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;
-}
-
-/**
- * Interface for the worker client dependency consumed by the MCP
- * server. Defines the knowledge-base operations the server exposes
- * as MCP tools and resources without coupling to the concrete
- * `WorkerClient` class.
- */
-export interface McpWorkerClient {
-   /**
-    * Searches the knowledge base using the given parameters.
-    *
-    * @param params - query string and optional search options
-    * @returns ranked list of matching section summaries
-    */
-   search(params: {
-      /** Natural language query text. */
-      readonly query: string;
-      /** Search mode: 'sections', 'documents', or 'stats'. */
-      readonly mode?: string;
-      /** Maximum number of results to return. */
-      readonly limit?: number;
-      /** Number of results to skip for pagination. */
-      readonly offset?: number;
-      /** Search algorithm: 'lexical', 'vector', or 'hybrid'. */
-      readonly algo?: string;
-   }): Promise<{
-      readonly items: readonly {
-         readonly kbid: string;
-         readonly heading: string | null;
-         readonly type: string;
-         readonly docids: readonly string[];
-         readonly score: number;
-         readonly snippet: string;
-         readonly matched_terms: readonly string[];
-         /** Fields that contained matches (heading, body, code). */
-         readonly matched_fields?: readonly string[];
-         /** ISO 8601 creation timestamp of the section. */
-         readonly created_at?: string;
-      }[];
-      readonly total: number;
-      readonly offset: number;
-      readonly limit: number;
-      readonly has_more: boolean;
-      /**
-       * `true` when results came from an automatic AND-to-OR
-       * fallback query relaxation.
-       */
-      readonly relaxed?: boolean;
-   }>;
-
-   /**
-    * Adds a new section to the knowledge base.
-    *
-    * @param params - content type, raw content, and optional metadata
-    * @returns the assigned knowledge-base identifier
-    */
-   addSection(params: {
-      /** Semantic type label for the section content. */
-      readonly sectionType: string;
-      /** Raw text or base64-encoded content for the section. */
-      readonly content: string;
-      /** Optional section title. Required for image/* types. */
-      readonly title?: string;
-      /** Optional section description. */
-      readonly description?: string;
-      /** Optional document ID to group this section under. */
-      readonly docid?: string;
-      /** Optional tags for scoping and filtering. */
-      readonly tags?: string[];
-      /**
-       * When `true`, replaces an existing section that has the same
-       * source key (supersession).
-       */
-      readonly replace?: boolean;
-   }): Promise<AddSectionResult>;
-
-   /**
-    * Removes a section from the knowledge base.
-    *
-    * @param kbid - knowledge-base identifier of the section to remove
-    * @returns removal result with `removed` flag and elapsed time
-    */
-   removeSection(kbid: string): Promise<RemoveSectionResult>;
-
-   /**
-    * Retrieves one or more sections by their identifiers.
-    *
-    * @param kbids - list of knowledge-base identifiers to fetch
-    * @returns sections in the order their IDs were requested
-    */
-   readSections(kbids: string[]): Promise<
-      {
-         /** Knowledge-base identifier for this section. */
-         kbid: string;
-         /** Semantic type label assigned to the section. */
-         sectionType: string;
-         /** Raw text content of the section. */
-         content: string;
-         /** Byte size of the stored content. */
-         size: number;
-      }[]
-   >;
-
-   /**
-    * Retrieves a full document record including its ordered sections.
-    *
-    * @param docid - identifier of the document to retrieve
-    * @returns the document record as returned by the daemon
-    */
-   retrieveDocument(docid: string): Promise<unknown>;
-
-   /**
-    * Composes a rendered Markdown document from one or more kbid
-    * or docid identifiers.
-    *
-    * @param ids - list of kbid or docid identifiers (may be mixed)
-    * @returns composed Markdown result with character count
-    */
-   content(ids: string[]): Promise<McpContentResult>;
-
-   /**
-    * Returns database metadata and status from the daemon.
-    *
-    * @returns document count, section count, and timing statistics
-    */
-   dbStatus(): Promise<{
-      /** Whether the daemon has finished loading its WASM modules. */
-      initialized: boolean;
-      /** Absolute path to the context directory the daemon serves. */
-      contextPath: string;
-      /** In-memory cache statistics. */
-      cacheStats: {
-         /** Number of content entries currently cached. */
-         contentCount: number;
-         /** Number of index entries currently cached. */
-         indexCount: number;
-      };
-   }>;
-
-   /**
-    * Runs an integrity check on the knowledge-base database.
-    *
-    * @returns a report of all issues found; `ok` is `true` when
-    *   no errors were detected
-    */
-   integrityCheck(): Promise<McpIntegrityCheckResult>;
-
-   /**
-    * Removes unreferenced sections from the database.
-    *
-    * @returns a report of sections removed and bytes freed
-    */
-   gc(): Promise<McpGcResult>;
-
-   /**
-    * Reconstructs all index files from section files and document
-    * manifests on disk.
-    *
-    * @returns a report of sections and terms re-indexed
-    */
-   rebuildIndexes(): Promise<McpRebuildResult>;
-
-   /**
-    * Retrieves all sections whose type name matches the given string.
-    *
-    * @param sectionType - the application-level type name to filter by
-    * @returns all section records with a matching type name
-    */
-   listByType(sectionType: string): Promise<SectionRecord[]>;
-
-   /**
-    * Retrieves all documents whose type name matches the given string.
-    *
-    * @param docType - the application-level document type to filter by
-    * @returns all document manifests with a matching type name
-    */
-   listDocumentsByType(docType: string): Promise<DocumentManifest[]>;
-
-   /**
-    * Groups a set of sections under a named document.
-    *
-    * @param title - human-readable document title
-    * @param kbids - identifiers of the sections to group
-    * @returns the assigned document identifier
-    */
-   groupSections(
-      title: string,
-      kbids: string[],
-      docType?: string,
-   ): Promise<string>;
-
-   /**
-    * Removes the document grouping for the given document.
-    *
-    * The sections themselves are not deleted; only the grouping
-    * record is removed.
-    *
-    * @param docid - identifier of the document grouping to remove
-    */
-   removeGrouping(docid: string): Promise<void>;
-
-   /**
-    * Retrieves full content and context for one or more sections by
-    * their knowledge-base identifiers.
-    *
-    * @param params - section identifier(s) and optional expansion depth
-    * @returns a single result or array of results depending on input
-    */
-   recall(params: {
-      /** Single section identifier. */
-      readonly kbid?: string;
-      /** Batch section identifiers. */
-      readonly kbids?: readonly string[];
-      /** Expansion depth (0-3, default: 0). */
-      readonly depth?: number;
-   }): Promise<unknown>;
-
-   /**
-    * Exports the database to a target directory as a self-contained
-    * snapshot (sections, documents, catalog -- no indexes).
-    *
-    * @param params - optional export parameters
-    * @returns export report with the resolved path and file counts
-    */
-   export(params?: {
-      readonly path?: string;
-   }): Promise<McpExportResult>;
-
-   /** Destroys the IPC socket and clears the connection state. */
-   disconnect(): void;
-}
-
-export type { RemoveSectionResult };

package/src/shared/mcp/typings/mcp-completion.interface.ts

@@ -1,45 +0,0 @@
-/**
- * Discriminated reference used in MCP completion requests.
- * Identifies whether the completion target is a prompt or a resource.
- */
-export interface McpCompletionRef {
-   /**
-    * The reference type: `'ref/prompt'` for named prompts (skills
-    * and agents) or `'ref/resource'` for resource URIs.
-    */
-   readonly type: 'ref/prompt' | 'ref/resource';
-   /** Prompt name, present when `type` is `'ref/prompt'`. */
-   readonly name?: string;
-   /** Resource URI, present when `type` is `'ref/resource'`. */
-   readonly uri?: string;
-}
-
-/**
- * Completion argument supplied by the client, describing which
- * argument is being completed and the current partial value.
- */
-export interface McpCompletionArgument {
-   /** The argument name being completed. */
-   readonly name: string;
-   /** The partial value typed so far; used for prefix filtering. */
-   readonly value: string;
-}
-
-/**
- * Result returned by `handleCompletion`, containing the list of
- * matching completion values and pagination metadata.
- */
-export interface McpCompletionResult {
-   /** Completion payload. */
-   readonly completion: {
-      /** Matching completion strings for the given prefix. */
-      readonly values: string[];
-      /**
-       * Whether more results are available beyond what is returned.
-       * Always `false` in this implementation.
-       */
-      readonly hasMore: boolean;
-      /** Total number of values returned. */
-      readonly total: number;
-   };
-}

package/src/shared/mcp/typings/mcp-content-result.model.ts

@@ -1,9 +0,0 @@
-/** Result returned by content composition. */
-export interface McpContentResult {
-   /** 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/mcp/typings/mcp-export-result.model.ts

@@ -1,11 +0,0 @@
-/** Export report returned by the daemon. */
-export interface McpExportResult {
-   /** 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;
-   /** Time taken to complete the export, in milliseconds. */
-   readonly elapsed_ms: number;
-}

package/src/shared/mcp/typings/mcp-gc-result.model.ts

@@ -1,15 +0,0 @@
-/** Garbage collection report returned by the daemon. */
-export interface McpGcResult {
-   /** 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/mcp/typings/mcp-integrity-check-result.model.ts

@@ -1,17 +0,0 @@
-import type { McpIntegrityError } from './mcp-integrity-error.model.ts';
-
-/** Integrity check report returned by the daemon. */
-export interface McpIntegrityCheckResult {
-   /** `true` when all checks passed and no errors were found. */
-   readonly ok: boolean;
-   /** All integrity errors found; empty when `ok` is `true`. */
-   readonly errors: McpIntegrityError[];
-   /** 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/mcp/typings/mcp-integrity-error.model.ts

@@ -1,15 +0,0 @@
-/** A single integrity error found during a database check. */
-export interface McpIntegrityError {
-   /** The category of integrity violation detected. */
-   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;
-}

package/src/shared/mcp/typings/mcp-notification.interface.ts

@@ -1,9 +0,0 @@
-/** A JSON-RPC 2.0 notification with no expected response. */
-export interface McpNotification {
-   /** JSON-RPC protocol version. Must always be '2.0'. */
-   readonly jsonrpc: '2.0';
-   /** Notification method name. */
-   readonly method: string;
-   /** Optional notification parameters. */
-   readonly params?: Record<string, unknown>;
-}

package/src/shared/mcp/typings/mcp-rebuild-result.model.ts

@@ -1,9 +0,0 @@
-/** Index rebuild report returned by the daemon. */
-export interface McpRebuildResult {
-   /** 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/mcp/typings/mcp-request.interface.ts

@@ -1,11 +0,0 @@
-/** A JSON-RPC 2.0 request message sent to the MCP server. */
-export interface McpRequest {
-   /** JSON-RPC protocol version. Must always be '2.0'. */
-   readonly jsonrpc: '2.0';
-   /** Request identifier; absent for notifications. */
-   readonly id?: number | string;
-   /** RPC method name. */
-   readonly method: string;
-   /** Optional method parameters. */
-   readonly params?: Record<string, unknown>;
-}

package/src/shared/mcp/typings/mcp-resource-result.interface.ts

@@ -1,12 +0,0 @@
-/** Result returned by `handleResourceRead`. */
-export interface McpResourceResult {
-   /** One or more content items for the requested resource URI. */
-   readonly contents: readonly {
-      /** The resource URI that was read. */
-      readonly uri: string;
-      /** MIME type of the content body. */
-      readonly mimeType: string;
-      /** Text body of the resource. */
-      readonly text: string;
-   }[];
-}

package/src/shared/mcp/typings/mcp-resource-template.interface.ts

@@ -1,11 +0,0 @@
-/** A URI template describing an MCP resource the server serves. */
-export interface McpResourceTemplate {
-   /** RFC 6570 URI template for the resource. */
-   readonly uriTemplate: string;
-   /** Human-readable resource name. */
-   readonly name: string;
-   /** Human-readable description of the resource. */
-   readonly description: string;
-   /** Optional MIME type for the resource content. */
-   readonly mimeType?: string;
-}

package/src/shared/mcp/typings/mcp-response.interface.ts

@@ -1,18 +0,0 @@
-/** A JSON-RPC 2.0 response message sent from the MCP server. */
-export interface McpResponse {
-   /** JSON-RPC protocol version. Must always be '2.0'. */
-   readonly jsonrpc: '2.0';
-   /** Echoes the request identifier. */
-   readonly id: number | string;
-   /** Successful result payload; absent when error is set. */
-   readonly result?: unknown;
-   /** Error payload; absent when result is set. */
-   readonly error?: {
-      /** Numeric error code as defined by JSON-RPC or MCP. */
-      readonly code: number;
-      /** Human-readable error message. */
-      readonly message: string;
-      /** Optional additional error data. */
-      readonly data?: unknown;
-   };
-}

package/src/shared/mcp/typings/mcp-server-info.interface.ts

@@ -1,7 +0,0 @@
-/** Identity information for the MCP server. */
-export interface McpServerInfo {
-   /** Server name reported during MCP initialization. */
-   readonly name: string;
-   /** Server version string reported during MCP initialization. */
-   readonly version: string;
-}