@dikolab/kbdb 0.3.1 → 0.4.0

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

@@ -1,17 +0,0 @@
-import type { McpLogLevel } from './log-types.interface.ts';
-
-/**
- * Mutable runtime state shared by `McpServer` and its request
- * handler. Extracted as an interface so the handler can be
- * tested independently of the full server class.
- */
-export interface McpServerState {
-   /** Advertised capabilities received from the MCP host. */
-   hostCapabilities: Record<string, unknown> | null;
-   /** Currently configured log level, or `null` when unset. */
-   logLevel: McpLogLevel | null;
-   /** Set of URI strings that the host has subscribed to. */
-   readonly subscriptions: Set<string>;
-   /** Filesystem path used as the KB context root. */
-   readonly contextPath: string;
-}

package/src/shared/mcp/typings/mcp-tool-annotations.interface.ts

@@ -1,32 +0,0 @@
-/**
- * Optional behavioral hints for an MCP tool, used by clients to
- * decide how to present or invoke the tool safely.
- */
-export interface McpToolAnnotations {
-   /**
-    * Human-readable title for the tool, suitable for display
-    * in client UIs.
-    */
-   readonly title?: string;
-   /**
-    * When `true`, the tool only reads data and does not modify
-    * any server-side state.
-    */
-   readonly readOnlyHint?: boolean;
-   /**
-    * When `true`, the tool may cause data loss or irreversible
-    * changes.
-    */
-   readonly destructiveHint?: boolean;
-   /**
-    * When `true`, calling the tool multiple times with the same
-    * arguments produces the same result with no additional side
-    * effects.
-    */
-   readonly idempotentHint?: boolean;
-   /**
-    * When `true`, the tool may interact with systems or data
-    * outside the immediate knowledge base context.
-    */
-   readonly openWorldHint?: boolean;
-}

package/src/shared/mcp/typings/mcp-tool-definition.interface.ts

@@ -1,16 +0,0 @@
-import type { McpToolAnnotations } from './mcp-tool-annotations.interface.ts';
-
-/** Definition of a single MCP tool exposed by the server. */
-export interface McpToolDefinition {
-   /** Unique tool name used to invoke it. */
-   readonly name: string;
-   /** Human-readable description of what the tool does. */
-   readonly description: string;
-   /** JSON Schema object describing the tool's input parameters. */
-   readonly inputSchema: Record<string, unknown>;
-   /**
-    * Optional behavioral hints that describe how the tool
-    * interacts with state.
-    */
-   readonly annotations?: McpToolAnnotations;
-}

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

@@ -1,19 +0,0 @@
-/**
- * Result returned by `handleToolCall`. Successful tool responses
- * carry `isError: true` for application-level failures rather than
- * using JSON-RPC error responses.
- */
-export interface McpToolResult {
-   /** One or more text content items describing the result. */
-   readonly content: readonly {
-      /** Content type identifier, always 'text'. */
-      readonly type: string;
-      /** Text payload of the content item. */
-      readonly text: string;
-   }[];
-   /**
-    * Set to `true` when the tool encountered an application-level
-    * error. Absent or `false` on success.
-    */
-   readonly isError?: boolean;
-}

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

@@ -1,158 +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>;
-}
-
-/** 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;
-   };
-}
-
-/** 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>;
-}
-
-/**
- * Optional behavioral hints for an MCP tool, used by clients to
- * decide how to present or invoke the tool safely.
- */
-export interface McpToolAnnotations {
-   /**
-    * Human-readable title for the tool, suitable for display
-    * in client UIs.
-    */
-   readonly title?: string;
-   /**
-    * When `true`, the tool only reads data and does not modify
-    * any server-side state.
-    */
-   readonly readOnlyHint?: boolean;
-   /**
-    * When `true`, the tool may cause data loss or irreversible
-    * changes.
-    */
-   readonly destructiveHint?: boolean;
-   /**
-    * When `true`, calling the tool multiple times with the same
-    * arguments produces the same result with no additional side
-    * effects.
-    */
-   readonly idempotentHint?: boolean;
-   /**
-    * When `true`, the tool may interact with systems or data
-    * outside the immediate knowledge base context.
-    */
-   readonly openWorldHint?: boolean;
-}
-
-/** Definition of a single MCP tool exposed by the server. */
-export interface McpToolDefinition {
-   /** Unique tool name used to invoke it. */
-   readonly name: string;
-   /** Human-readable description of what the tool does. */
-   readonly description: string;
-   /** JSON Schema object describing the tool's input parameters. */
-   readonly inputSchema: Record<string, unknown>;
-   /**
-    * Optional behavioral hints that describe how the tool
-    * interacts with state.
-    */
-   readonly annotations?: McpToolAnnotations;
-}
-
-/** 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;
-}
-
-/** 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;
-}
-
-/** 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>;
-}
-
-/**
- * Result returned by `handleToolCall`. Successful tool responses
- * carry `isError: true` for application-level failures rather than
- * using JSON-RPC error responses.
- */
-export interface McpToolResult {
-   /** One or more text content items describing the result. */
-   readonly content: readonly {
-      /** Content type identifier, always 'text'. */
-      readonly type: string;
-      /** Text payload of the content item. */
-      readonly text: string;
-   }[];
-   /**
-    * Set to `true` when the tool encountered an application-level
-    * error. Absent or `false` on success.
-    */
-   readonly isError?: boolean;
-}
-
-/** 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-worker-client.interface.ts

@@ -1,243 +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';
-import type { McpContentResult } from './mcp-content-result.model.ts';
-import type { McpIntegrityCheckResult } from './mcp-integrity-check-result.model.ts';
-import type { McpGcResult } from './mcp-gc-result.model.ts';
-import type { McpRebuildResult } from './mcp-rebuild-result.model.ts';
-import type { McpExportResult } from './mcp-export-result.model.ts';
-
-/**
- * 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;
-      /**
-       * Search algorithm: `'lexical'`, `'vector'`, or `'hybrid'`.
-       * Defaults to `'lexical'` when omitted.
-       */
-      readonly algo?: string;
-      /** Maximum number of results to return. */
-      readonly limit?: number;
-      /** Number of results to skip for pagination. */
-      readonly offset?: number;
-   }): 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;
-}

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

@@ -1,39 +0,0 @@
-/** A single argument definition for an MCP prompt. */
-export interface McpPromptArgument {
-   /** Argument name used as the placeholder key. */
-   readonly name: string;
-   /** Human-readable description of the argument. */
-   readonly description?: string;
-   /** Whether the argument must be supplied at invocation time. */
-   readonly required?: boolean;
-}
-
-/** An MCP prompt entry returned by `prompts/list`. */
-export interface McpPrompt {
-   /** Unique prompt name used to invoke it via `prompts/get`. */
-   readonly name: string;
-   /** Human-readable description of what the prompt does. */
-   readonly description?: string;
-   /**
-    * Declared arguments the prompt accepts.
-    * Absent or empty when the prompt takes no arguments.
-    */
-   readonly arguments?: readonly McpPromptArgument[];
-}
-
-/** A single message in an MCP prompt response. */
-export interface McpPromptMessage {
-   /**
-    * Conversation role for this message.
-    * `'assistant'` for persona/system context, `'user'` for
-    * instructions directed at the model.
-    */
-   readonly role: 'user' | 'assistant';
-   /** Text content of the message. */
-   readonly content: {
-      /** Content type identifier, always `'text'`. */
-      readonly type: 'text';
-      /** The text payload. */
-      readonly text: string;
-   };
-}

package/src/shared/mcp/typings/remove-section-result.model.ts

@@ -1,10 +0,0 @@
-/**
- * Result returned by `McpWorkerClient.removeSection`. Reports
- * whether the section was removed and the elapsed operation time.
- */
-export interface RemoveSectionResult {
-   /** `true` when the section was found and removed. */
-   readonly removed: boolean;
-   /** Elapsed time for the remove operation in milliseconds. */
-   readonly elapsed_ms: number;
-}

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

@@ -1,48 +0,0 @@
-/**
- * A single message in an MCP sampling conversation, sent to or
- * received from a language model.
- */
-export interface McpSamplingMessage {
-   /** Originating role for this message. */
-   readonly role: 'user' | 'assistant';
-   /** Text content of the message. */
-   readonly content: {
-      /** Content type discriminant, always `'text'`. */
-      readonly type: 'text';
-      /** The text body of the message. */
-      readonly text: string;
-   };
-}
-
-/**
- * Request sent by the MCP server to the client to sample a language
- * model. The client is responsible for selecting the model and
- * forwarding the request.
- */
-export interface McpSamplingRequest {
-   /** Ordered list of messages forming the conversation context. */
-   readonly messages: readonly McpSamplingMessage[];
-   /**
-    * Maximum number of tokens the model should generate in its
-    * response.
-    */
-   readonly maxTokens: number;
-}
-
-/**
- * Result returned by the client after sampling a language model,
- * containing the assistant's generated response.
- */
-export interface McpSamplingResult {
-   /** Role of the response message, always `'assistant'`. */
-   readonly role: 'assistant';
-   /** Text content generated by the model. */
-   readonly content: {
-      /** Content type discriminant, always `'text'`. */
-      readonly type: 'text';
-      /** The generated text response. */
-      readonly text: string;
-   };
-   /** Identifier of the model that produced the response. */
-   readonly model: string;
-}

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

@@ -1,29 +0,0 @@
-/** A single argument definition for a skill. */
-export interface SkillArgument {
-   /** Argument name, used as the placeholder key. */
-   readonly name: string;
-   /** The expected value type. Defaults to `'string'` when omitted. */
-   readonly type?: 'string' | 'number' | 'boolean';
-   /** Human-readable description of the argument. */
-   readonly description?: string;
-   /** Whether the argument must be supplied at invocation time. */
-   readonly required?: boolean;
-}
-
-/** A reusable AI agent capability stored in the knowledge base. */
-export interface SkillDefinition {
-   /** Unique skill name used for lookup. */
-   readonly name: string;
-   /** Human-readable description of the skill. */
-   readonly description?: string;
-   /**
-    * Declared arguments for the skill body template.
-    * Extracted from `{{argName}}` placeholders.
-    */
-   readonly arguments?: readonly SkillArgument[];
-   /**
-    * Template body of the skill.
-    * May contain `{{argName}}` placeholders for variable substitution.
-    */
-   readonly body: string;
-}

package/src/shared/mcp/typings/tool-call-result.model.ts

@@ -1,18 +0,0 @@
-/** Shape of a content item in an MCP tool call response. */
-export interface ToolContent {
-   /** Content type identifier, typically `'text'`. */
-   readonly type: string;
-   /** The text payload. */
-   readonly text: string;
-}
-
-/**
- * Result returned by any MCP tool call handler, containing one or
- * more content items and an optional error flag.
- */
-export interface ToolCallResult {
-   /** One or more content items describing the result. */
-   readonly content: ToolContent[];
-   /** Set to `true` when the tool encountered an error. */
-   readonly isError?: boolean;
-}

package/src/shared/mod.ts

@@ -1 +0,0 @@
-export { VERSION as version } from './version/constants/version.constant.ts';

package/src/shared/platform/functions/get-ipc-path.function.ts

@@ -1,19 +0,0 @@
-import { join } from 'node:path';
-import { getTmpdir } from './get-tmpdir.function.ts';
-
-/**
- * Returns the platform-appropriate IPC socket path for a given
- * context identifier.
- *
- * On Windows, returns a named pipe path (`\\.\pipe\kbdb-<ctx>`).
- * On POSIX systems, returns a Unix domain socket path under the
- * system temp directory (`<tmpdir>/kbdb-<ctx>.sock`).
- *
- * @param ctx - unique context identifier embedded in the path
- */
-export function getIpcPath(ctx: string): string {
-   if (process.platform === 'win32') {
-      return `\\\\.\\pipe\\kbdb-${ctx}`;
-   }
-   return join(getTmpdir(), `kbdb-${ctx}.sock`);
-}

package/src/shared/platform/functions/get-tmpdir.function.ts

@@ -1,8 +0,0 @@
-import { tmpdir } from 'node:os';
-
-/**
- * Returns the operating system's default temporary directory path.
- */
-export function getTmpdir(): string {
-   return tmpdir();
-}