@dikolab/kbdb 0.1.5 → 0.2.0

package/docs/modules/typescript/shared/mcp/typings.md

@@ -0,0 +1,522 @@
+# mcp/typings -- MCP Type Definitions
+
+*Interfaces and type aliases for the MCP server's
+JSON-RPC protocol and worker client contract.*
+
+## Source
+
+`src/shared/mcp/typings/`
+
+## Typings
+
+### `McpWorkerClient`
+
+**File:** `mcp-client.interface.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.
+
+```ts
+interface McpWorkerClient {
+   search(params: {
+      readonly query: string;
+      readonly mode?: string;
+      readonly limit?: number;
+      readonly content?: boolean;
+      readonly offset?: number;
+   }): Promise<PagedSearchResult>;
+
+   addSection(params: {
+      readonly type: string;
+      readonly content: string;
+      readonly title?: string;
+      readonly description?: string;
+      readonly docid?: string;
+   }): Promise<string>;
+
+   removeSection(kbid: string): Promise<RemoveSectionResult>;
+
+   readSections(
+      kbids: string[],
+   ): Promise<Section[]>;
+
+   retrieveDocument(
+      docid: string,
+   ): Promise<unknown>;
+
+   listByType(
+      sectionType: string,
+   ): Promise<Section[]>;
+
+   listDocumentsByType(
+      docType: string,
+   ): Promise<unknown[]>;
+
+   recall(params: {
+      readonly kbid?: string;
+      readonly kbids?: readonly string[];
+      readonly depth?: number;
+   }): Promise<RecallResult | RecallResult[]>;
+
+   dbStatus(): Promise<DbStatus>;
+
+   disconnect(): void;
+}
+```
+
+| Method                  | Description                       |
+|-------------------------|-----------------------------------|
+| `listByType`            | Returns all sections whose        |
+|                         | `sectionType` matches the given   |
+|                         | value (e.g. `'skill'`)            |
+| `listDocumentsByType`   | Returns all document manifests    |
+|                         | whose `type` field matches (e.g.  |
+|                         | `'agent'`)                        |
+
+### `RemoveSectionResult`
+
+**File:** `remove-section-result.model.ts`
+
+Result returned by `McpWorkerClient.removeSection`.
+Reports whether the section was found and removed
+and the elapsed operation time.
+
+```ts
+interface RemoveSectionResult {
+   readonly removed: boolean;
+   readonly elapsed_ms: number;
+}
+```
+
+### `McpRequest`
+
+**File:** `mcp-types.interface.ts`
+
+A JSON-RPC 2.0 request message sent to the MCP
+server. The `id` field is absent for notifications.
+
+```ts
+interface McpRequest {
+   readonly jsonrpc: '2.0';
+   readonly id?: number | string;
+   readonly method: string;
+   readonly params?: Record<string, unknown>;
+}
+```
+
+### `McpResponse`
+
+**File:** `mcp-types.interface.ts`
+
+A JSON-RPC 2.0 response message. Contains either
+`result` (success) or `error` (failure), never both.
+
+```ts
+interface McpResponse {
+   readonly jsonrpc: '2.0';
+   readonly id: number | string;
+   readonly result?: unknown;
+   readonly error?: {
+      readonly code: number;
+      readonly message: string;
+      readonly data?: unknown;
+   };
+}
+```
+
+### `McpNotification`
+
+**File:** `mcp-types.interface.ts`
+
+A JSON-RPC 2.0 notification with no `id` and no
+expected response.
+
+```ts
+interface McpNotification {
+   readonly jsonrpc: '2.0';
+   readonly method: string;
+   readonly params?: Record<string, unknown>;
+}
+```
+
+### `McpToolDefinition`
+
+**File:** `mcp-types.interface.ts`
+
+Definition of a single MCP tool exposed by the
+server via `tools/list`.
+
+```ts
+interface McpToolDefinition {
+   readonly name: string;
+   readonly description: string;
+   readonly inputSchema: Record<string, unknown>;
+   readonly annotations?: McpToolAnnotations;
+}
+```
+
+The optional `annotations` field carries hints for
+MCP clients about the tool's side effects and safety
+characteristics.
+
+### `McpResourceTemplate`
+
+**File:** `mcp-types.interface.ts`
+
+A URI template describing an MCP resource served
+via `resources/templates/list`.
+
+```ts
+interface McpResourceTemplate {
+   readonly uriTemplate: string;
+   readonly name: string;
+   readonly description: string;
+   readonly mimeType?: string;
+}
+```
+
+### `McpServerInfo`
+
+**File:** `mcp-types.interface.ts`
+
+Identity information for the MCP server, reported
+in the `initialize` response.
+
+```ts
+interface McpServerInfo {
+   readonly name: string;
+   readonly version: string;
+}
+```
+
+### `McpCapabilities`
+
+**File:** `mcp-types.interface.ts`
+
+MCP capability flags advertised during
+initialization. Each key enables a group of methods.
+
+```ts
+interface McpCapabilities {
+   readonly tools?: Record<string, never>;
+   readonly resources?: Record<string, never>;
+   readonly prompts?: Record<string, never>;
+   readonly logging?: Record<string, never>;
+   readonly completions?: Record<string, never>;
+}
+```
+
+| Key           | Methods enabled                          |
+|---------------|------------------------------------------|
+| `tools`       | `tools/list`, `tools/call`               |
+| `resources`   | `resources/list`, `resources/read`, etc. |
+| `prompts`     | `prompts/list`, `prompts/get`            |
+| `logging`     | `logging/setLevel`                       |
+| `completions` | `completion/complete`                    |
+
+### `McpToolResult`
+
+**File:** `mcp-types.interface.ts`
+
+Result returned by `handleToolCall`. Tool-level
+errors use `isError: true` in the result rather than
+JSON-RPC error responses.
+
+```ts
+interface McpToolResult {
+   readonly content: readonly {
+      readonly type: string;
+      readonly text: string;
+   }[];
+   readonly isError?: boolean;
+}
+```
+
+### `McpResourceResult`
+
+**File:** `mcp-types.interface.ts`
+
+Result returned by `handleResourceRead`.
+
+```ts
+interface McpResourceResult {
+   readonly contents: readonly {
+      readonly uri: string;
+      readonly mimeType: string;
+      readonly text: string;
+   }[];
+}
+```
+
+### `McpPrompt`
+
+**File:** `mcp-types.interface.ts`
+
+A single prompt entry returned by `prompts/list`.
+Skills use `name` directly; agents use `agent:<name>`.
+
+```ts
+interface McpPrompt {
+   readonly name: string;
+   readonly description?: string;
+   readonly arguments?: readonly McpPromptArgument[];
+}
+```
+
+| Property      | Description                          |
+|---------------|--------------------------------------|
+| `name`        | Prompt name (or `agent:<name>`)      |
+| `description` | Human-readable description           |
+| `arguments`   | Accepted arguments for the prompt    |
+
+### `McpPromptArgument`
+
+**File:** `mcp-types.interface.ts`
+
+A single argument accepted by an MCP prompt.
+
+```ts
+interface McpPromptArgument {
+   readonly name: string;
+   readonly description?: string;
+   readonly required?: boolean;
+}
+```
+
+| Property      | Description                       |
+|---------------|-----------------------------------|
+| `name`        | Argument identifier               |
+| `description` | Human-readable hint               |
+| `required`    | Whether the argument is required  |
+
+### `McpPromptMessage`
+
+**File:** `mcp-types.interface.ts`
+
+A single message in the array returned by `prompts/get`.
+
+```ts
+interface McpPromptMessage {
+   readonly role: 'user' | 'assistant';
+   readonly content: McpPromptMessageContent;
+}
+```
+
+### `McpPromptMessageContent`
+
+**File:** `mcp-types.interface.ts`
+
+Content body of an `McpPromptMessage`.
+
+```ts
+interface McpPromptMessageContent {
+   readonly type: 'text';
+   readonly text: string;
+}
+```
+
+### `McpToolAnnotations`
+
+**File:** `mcp-types.interface.ts`
+
+Hints for MCP clients about a tool's side effects
+and safety characteristics.
+
+```ts
+interface McpToolAnnotations {
+   readonly title?: string;
+   readonly readOnlyHint?: boolean;
+   readonly destructiveHint?: boolean;
+   readonly idempotentHint?: boolean;
+   readonly openWorldHint?: boolean;
+}
+```
+
+| Property          | Description                        |
+|-------------------|------------------------------------|
+| `title`           | Human-readable tool title          |
+| `readOnlyHint`    | `true` if the tool only reads data |
+| `destructiveHint` | `true` if the tool deletes data    |
+| `idempotentHint`  | `true` if repeated calls are safe  |
+| `openWorldHint`   | `true` if side effects may extend  |
+|                   | outside the knowledge base         |
+
+### `McpCompletionRef`
+
+**File:** `mcp-types.interface.ts`
+
+Reference descriptor sent with a `completion/complete`
+request, identifying the kind of value to complete.
+
+```ts
+interface McpCompletionRef {
+   readonly type: 'ref/prompt' | 'ref/resource';
+   readonly name?: string;
+   readonly uri?: string;
+}
+```
+
+| Property | Description                                  |
+|----------|----------------------------------------------|
+| `type`   | `'ref/prompt'` to complete prompt names;     |
+|          | `'ref/resource'` to complete resource URIs   |
+| `name`   | Prompt name prefix (for `ref/prompt`)        |
+| `uri`    | Resource URI prefix (for `ref/resource`)     |
+
+### `McpCompletionResult`
+
+**File:** `mcp-types.interface.ts`
+
+Result returned by `handleCompletion`.
+
+```ts
+interface McpCompletionResult {
+   readonly completion: {
+      readonly values: readonly string[];
+      readonly hasMore?: boolean;
+      readonly total?: number;
+   };
+}
+```
+
+| Property           | Description                      |
+|--------------------|----------------------------------|
+| `completion.values`| Matching completion strings      |
+| `completion.hasMore` | More results exist beyond this list |
+| `completion.total` | Total number of matches          |
+
+### `McpLogLevel`
+
+**File:** `mcp-types.interface.ts`
+
+MCP log severity levels as defined in the MCP spec.
+
+```ts
+type McpLogLevel =
+   | 'debug'
+   | 'info'
+   | 'notice'
+   | 'warning'
+   | 'error'
+   | 'critical'
+   | 'alert'
+   | 'emergency';
+```
+
+### `McpLogMessage`
+
+**File:** `mcp-types.interface.ts`
+
+Parameters for a `notifications/message` server
+notification.
+
+```ts
+interface McpLogMessage {
+   readonly level: McpLogLevel;
+   readonly logger?: string;
+   readonly data?: unknown;
+}
+```
+
+| Property | Description                            |
+|----------|----------------------------------------|
+| `level`  | Severity level of the log entry        |
+| `logger` | Optional logger name (e.g. `'kbdb'`)  |
+| `data`   | Log message or structured data         |
+
+### `SkillDefinition`
+
+**File:** `mcp-types.interface.ts`
+
+A complete skill definition as stored in the knowledge
+base and returned by skill retrieval operations.
+
+```ts
+interface SkillDefinition {
+   readonly name: string;
+   readonly description: string;
+   readonly arguments?: readonly SkillArgument[];
+   readonly body: string;
+}
+```
+
+| Property      | Description                           |
+|---------------|---------------------------------------|
+| `name`        | Skill name in kebab-case              |
+| `description` | What the skill does                   |
+| `arguments`   | Auto-detected template arguments      |
+| `body`        | Template body with `{{arg}}` syntax   |
+
+### `SkillArgument`
+
+**File:** `mcp-types.interface.ts`
+
+A single argument accepted by a skill template.
+
+```ts
+interface SkillArgument {
+   readonly name: string;
+   readonly type?: 'string' | 'number' | 'boolean';
+   readonly description?: string;
+   readonly required?: boolean;
+}
+```
+
+| Property      | Description                        |
+|---------------|------------------------------------|
+| `name`        | Argument identifier                |
+| `type`        | Value type (defaults to `string`)  |
+| `description` | Human-readable argument hint       |
+| `required`    | Whether the argument is required   |
+
+### `AgentDefinition`
+
+**File:** `mcp-types.interface.ts`
+
+A complete agent definition as returned by agent
+retrieval operations. Skills are resolved from kbid
+references; missing skills appear with `name: null`.
+
+```ts
+interface AgentDefinition {
+   readonly docid: string;
+   readonly name: string;
+   readonly description: string;
+   readonly persona: string;
+   readonly skills: readonly {
+      readonly kbid: string;
+      readonly name: string | null;
+      readonly position: number;
+   }[];
+}
+```
+
+| Property      | Description                          |
+|---------------|--------------------------------------|
+| `docid`       | Agent document identifier            |
+| `name`        | Agent name in kebab-case             |
+| `description` | What the agent does                  |
+| `persona`     | System prompt text for the agent     |
+| `skills`      | Ordered skill references (resolved)  |
+
+## Error Code Constants
+
+**File:** `src/shared/mcp/constants/mcp-error-codes.constant.ts`
+
+Named constants for JSON-RPC 2.0 and MCP-specific
+error codes. Use these instead of inline numbers.
+
+| Constant            | Value   | Meaning                        |
+|---------------------|---------|--------------------------------|
+| `PARSE_ERROR`       | -32700  | Malformed JSON in request      |
+| `METHOD_NOT_FOUND`  | -32601  | Method not implemented         |
+| `INVALID_PARAMS`    | -32602  | Invalid or missing parameters  |
+| `INTERNAL_ERROR`    | -32603  | Unexpected server error        |
+| `RESOURCE_NOT_FOUND`| -32002  | Resource not found (MCP-specific); also used for pre-initialization guard |
+
+No spec -- typings are compile-time only. Constants
+have a spec (`mcp-error-codes.spec.ts`) that verifies
+the exported values.

package/docs/modules/typescript/shared/module.md

@@ -0,0 +1,94 @@
+# shared -- All TypeScript Modules
+
+*Every TypeScript module lives under `src/shared/`.
+The two entry points (`src/cli.ts`,
+`src/worker.ts`) are thin executables that import
+from these sub-modules.*
+
+## Source
+
+`src/shared/`
+
+## Responsibility
+
+Contains all TypeScript logic. There is **no**
+top-level `shared/index.ts` barrel -- consumers import
+directly from `shared/[module]/index.ts` or from
+specific files.
+
+```ts
+import {
+   createWorkerClient,
+} from './shared/worker-client/functions/create-worker-client.function.ts';
+```
+
+## Directory Layout
+
+```
+src/shared/
+├── cli/               ← CLI commands
+├── mcp/               ← MCP server
+├── worker-client/     ← IPC client to daemon
+├── worker-daemon/     ← Daemon process logic
+├── version/           ← Package version constant
+├── runtime/           ← Deno / Node.js detection
+├── platform/          ← OS abstractions
+└── hash/              ← SHA-256 hashing
+```
+
+## Modules
+
+### Application Modules
+
+- **[cli/](cli/module.md)** -- CLI argument parsing,
+  command handlers (`learn`, `unlearn`, `search`),
+  and output formatting.
+- **[mcp/](mcp/module.md)** -- MCP server, tool
+  handlers (`search`, `learn`, `unlearn`, `retrieve`,
+  `status`), and resource handlers.
+- **[worker-client/](worker-client/module.md)** --
+  IPC client. Discovers or spawns the daemon, provides
+  typed async API for all operations.
+- **[worker-daemon/](worker-daemon/module.md)** --
+  Daemon process. Loads WASM modules, listens on IPC,
+  serves JSON-RPC 2.0 requests.
+
+### Utility Modules
+
+- **[version/](version/module.md)** -- Package version
+  constant.
+- **[runtime/](runtime/module.md)** -- Deno / Node.js
+  runtime detection and argument access.
+- **[platform/](platform/module.md)** -- Cross-platform
+  helpers (tmpdir, PID checks, IPC socket paths).
+- **[hash/](hash/module.md)** -- SHA-256 hashing via
+  Web Crypto API.
+
+## Dependency Direction
+
+```
+src/cli.ts
+  ├── shared/cli/
+  │     └── shared/worker-client/
+  └── shared/mcp/
+        └── shared/worker-client/
+
+src/worker.ts
+  └── shared/worker-daemon/
+
+shared/worker-client/
+  ├── shared/platform/
+  └── shared/hash/
+
+shared/worker-daemon/
+  └── shared/platform/
+
+mod.ts
+  └── shared/version/
+```
+
+Utility modules (`version`, `runtime`, `platform`,
+`hash`) have no dependencies on application modules.
+Application modules may depend on utility modules
+but not on each other, except through the
+worker-client which both `cli` and `mcp` share.

package/docs/modules/typescript/shared/platform/functions.md

@@ -0,0 +1,42 @@
+# platform/functions -- Platform Functions
+
+**Source:** `src/shared/platform/functions/`
+
+## getTmpdir
+
+```ts
+getTmpdir(): string
+```
+
+Returns the OS temp directory path.
+
+- **Node:** `os.tmpdir()`
+- **Deno:** `Deno.env.get("TMPDIR")`, or
+  `Deno.env.get("TEMP")` on Windows.
+
+## isProcessAlive
+
+```ts
+isProcessAlive(pid: number): boolean
+```
+
+Checks whether a process with the given PID is still
+running.
+
+- **Node:** `process.kill(pid, 0)`
+- **Deno (Linux/macOS):** `Deno.kill(pid, "SIGCONT")`
+- **Deno (Windows):** Spawns a `tasklist` subprocess.
+
+Returns `true` if alive, `false` if not.
+
+## getIpcPath
+
+```ts
+getIpcPath(ctx: string): string
+```
+
+Returns the IPC socket or named-pipe path for a given
+context identifier.
+
+- **Unix:** `${tmpdir}/kb-worker-${ctx}.sock`
+- **Windows:** `\\.\pipe\kb-worker-${ctx}`

package/docs/modules/typescript/shared/platform/module.md

@@ -0,0 +1,25 @@
+# platform -- Platform Abstractions
+
+**Source:** `src/shared/platform/`
+
+## Responsibility
+
+Cross-platform helpers for temp directories, process
+checks, and IPC socket paths. Abstracts OS + runtime
+differences.
+
+## Directory Layout
+
+```
+src/shared/platform/
+   index.ts
+   functions/
+      get-tmpdir.function.ts
+      is-process-alive.function.ts
+      get-ipc-path.function.ts
+```
+
+## Exports
+
+- [Functions](functions.md) -- `getTmpdir`,
+  `isProcessAlive`, `getIpcPath`

package/docs/modules/typescript/shared/runtime/functions.md

@@ -0,0 +1,26 @@
+# runtime/functions -- Runtime Functions
+
+**Source:** `src/shared/runtime/functions/`
+
+## detectRuntime
+
+```ts
+detectRuntime(): Runtime
+```
+
+Returns the current `Runtime` type
+(`'deno'` | `'node'`).
+
+Detection logic:
+checks `typeof Deno !== 'undefined'`.
+
+## getArgs
+
+```ts
+getArgs(): string[]
+```
+
+Returns CLI arguments as a string array.
+
+- **Deno:** `Deno.args`
+- **Node:** `process.argv.slice(2)`