@dikolab/kbdb 0.1.6 → 0.2.1

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

@@ -0,0 +1,125 @@
+# cli -- CLI Command Module
+
+*Parses command-line arguments, delegates operations
+to the worker daemon via worker-client, and prints
+results to stdout.*
+
+## Source
+
+`src/shared/cli/`
+
+## Responsibility
+
+Thin pass-through between the user's shell and the
+worker daemon. Parses arguments, validates input,
+creates a `WorkerClient`, calls the appropriate client
+method, formats the result, and prints to stdout.
+Errors go to stderr.
+
+The CLI does **not** perform keyword extraction,
+indexing, ranking, or database I/O. All processing is
+delegated to the worker daemon.
+
+See [CLI](../../../../goals/cli.md) for the full
+behavioral specification.
+
+## Directory Layout
+
+```
+src/shared/cli/
+├── index.ts
+├── constants/
+│   ├── defaults.constant.ts
+│   └── help-text.constant.ts
+├── functions/
+│   ├── dispatch-command.function.ts
+│   ├── ensure-db.function.ts
+│   ├── error-to-message.function.ts
+│   ├── find-db.function.ts
+│   ├── format-output.function.ts
+│   ├── is-stdin-tty.function.ts
+│   ├── parse-args.function.ts
+│   ├── prompt-user.function.ts
+│   ├── run-agent-create.function.ts
+│   ├── run-agent-delete.function.ts
+│   ├── run-agent-get.function.ts
+│   ├── run-agent-list.function.ts
+│   ├── run-check.function.ts
+│   ├── run-cli.function.ts
+│   ├── run-content.function.ts
+│   ├── run-db-init.function.ts
+│   ├── run-db-migrate.function.ts
+│   ├── run-gc.function.ts
+│   ├── run-init.function.ts
+│   ├── run-learn.function.ts
+│   ├── run-migrate.function.ts
+│   ├── run-rebuild.function.ts
+│   ├── run-search.function.ts
+│   ├── run-skill-delete.function.ts
+│   ├── run-skill-get.function.ts
+│   ├── run-skill-learn.function.ts
+│   ├── run-skill-list.function.ts
+│   └── run-unlearn.function.ts
+├── typings/
+│   ├── cli-options.interface.ts
+│   ├── command-result.model.ts
+│   ├── learn-result.model.ts
+│   └── search-display.model.ts
+└── *.spec.ts
+```
+
+## Exports
+
+- **[functions.md](functions.md)** -- `runCli`,
+  `dispatchCommand`, `parseArgs`, `findDb`,
+  `runInit`, `runMigrate`, `runLearn`, `runUnlearn`,
+  `runSearch`, `runContent`, `runCheck`, `runGc`,
+  `runRebuild`, `ensureDb`, `formatOutput`,
+  `errorToMessage`, `isStdinTty`, `promptUser`,
+  `runDbInit`, `runDbMigrate`, `runSkillLearn`,
+  `runSkillList`, `runSkillGet`, `runSkillDelete`,
+  `runAgentCreate`, `runAgentList`, `runAgentGet`,
+  `runAgentDelete`.
+- **[typings.md](typings.md)** -- `CliOptions`,
+  `CommandResult`, `LearnResult`, `SearchDisplay`,
+  `SearchMode`, `OutputFormat`.
+- **[constants.md](constants.md)** -- `DEFAULT_LIMIT`,
+  `DEFAULT_FORMAT`.
+
+## Execution Flow
+
+```
+cli.ts (entry point)
+  │
+  ├─ runCli(argv, deps)
+  │    ├─ parseArgs(argv) → CliOptions
+  │    ├─ command === 'help'       → print HELP_TEXT
+  │    ├─ command === 'version'    → print VERSION
+  │    ├─ command === 'init'       → runInit(options)
+  │    ├─ command === 'mcp'        → startMcpServer
+  │    ├─ command === 'migrate'    → runMigrate(client, options)
+  │    ├─ command === 'db-init'    → runDbInit(options)
+  │    ├─ command === 'db-migrate' → runDbMigrate(client, options)
+  │    └─ data command:
+  │         ├─ findDb(options.dbPath) → dbDir
+  │         ├─ if not found: isStdinTty() / promptUser()
+  │         ├─ createWorkerClient({ contextPath: dbDir })
+  │         ├─ version gate (checkVersion)
+  │         └─ dispatchCommand(client, options)
+  │              ├─ learn         → runLearn(client, options)
+  │              ├─ unlearn       → runUnlearn(client, options)
+  │              ├─ search        → runSearch(client, options)
+  │              ├─ content       → runContent(client, options)
+  │              ├─ check         → runCheck(client, options)
+  │              ├─ gc            → runGc(client, options)
+  │              ├─ rebuild       → runRebuild(client, options)
+  │              ├─ skill-learn   → runSkillLearn(client, options)
+  │              ├─ skill-list    → runSkillList(client, options)
+  │              ├─ skill-get     → runSkillGet(client, options)
+  │              ├─ skill-delete  → runSkillDelete(client, options)
+  │              ├─ agent-create  → runAgentCreate(client, options)
+  │              ├─ agent-list    → runAgentList(client, options)
+  │              ├─ agent-get     → runAgentGet(client, options)
+  │              └─ agent-delete  → runAgentDelete(client, options)
+  └─ returns CommandResult { output?, error?, exitCode }
+```

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

@@ -0,0 +1,172 @@
+# cli/typings -- CLI Type Definitions
+
+*Interfaces, type aliases, and data models for CLI
+argument parsing, command results, and display output.*
+
+## Source
+
+`src/shared/cli/typings/`
+
+## Typings
+
+### `CliOptions`
+
+**File:** `cli-options.interface.ts`
+
+Parsed representation of all CLI arguments for a
+single invocation.
+
+```ts
+interface CliOptions {
+   command: string;
+   args: string[];
+   dbPath?: string;
+   format: OutputFormat;
+   mode: SearchMode;
+   limit: number;
+   title?: string;
+   description?: string;
+   docid?: string;
+   content?: boolean;
+   name?: string;
+   persona?: string;
+   body?: string;
+   skills?: string[];
+}
+```
+
+| Property      | Description                           |
+|---------------|---------------------------------------|
+| `command`     | CLI sub-command. Simple commands:     |
+|               | `'search'`, `'learn'`, `'unlearn'`,   |
+|               | `'content'`, `'check'`, `'gc'`,       |
+|               | `'rebuild'`, `'mcp'`, `'status'`.     |
+|               | Compound commands: `'db-init'`,       |
+|               | `'db-migrate'`, `'skill-learn'`,      |
+|               | `'skill-list'`, `'skill-get'`,        |
+|               | `'skill-delete'`, `'agent-create'`,   |
+|               | `'agent-list'`, `'agent-get'`,        |
+|               | `'agent-delete'`.                     |
+| `args`        | Positional arguments                  |
+| `dbPath`      | Database directory (`--db`)           |
+| `format`      | Output format flag                    |
+| `mode`        | Search result mode (`--mode`)         |
+| `limit`       | Max results (`--limit`)               |
+| `title`       | Section title (`--title`)             |
+| `description` | Section description                   |
+| `docid`       | Document ID for learn command         |
+| `content`     | Hydrate search results with           |
+|               | section content when `true`           |
+| `name`        | Skill or agent name (`--name`)        |
+| `persona`     | Agent persona file path (`--persona`) |
+| `body`        | Skill body file path (`--body`)       |
+| `skills`      | Ordered skill kbid list (`--skills`)  |
+
+### `OutputFormat`
+
+**File:** `cli-options.interface.ts`
+
+Type alias for supported output formats.
+
+```ts
+type OutputFormat = 'json' | 'text' | 'mcp';
+```
+
+| Value  | Description                     |
+|--------|---------------------------------|
+| `json` | Machine-readable JSON array     |
+| `text` | Human-readable numbered list    |
+| `mcp`  | JSON envelope for MCP consumers |
+
+### `SearchMode`
+
+**File:** `cli-options.interface.ts`
+
+Controls which entity type is returned by a search
+query.
+
+```ts
+type SearchMode = 'sections' | 'documents' | 'stats';
+```
+
+### `CommandResult`
+
+**File:** `command-result.model.ts`
+
+Result of dispatching a CLI command. Encapsulates
+output, error text, and exit code so the caller can
+decide how to present them without touching process
+globals.
+
+```ts
+interface CommandResult {
+   output?: string;
+   error?: string;
+   exitCode: number;
+}
+```
+
+| Property   | Description                          |
+|------------|--------------------------------------|
+| `output`   | Text to write to stdout (if any)     |
+| `error`    | Error message for stderr (if any)    |
+| `exitCode` | Process exit code (`0` = success)    |
+
+### `LearnResult`
+
+**File:** `learn-result.model.ts`
+
+Result record produced for each file processed by the
+learn command.
+
+```ts
+interface LearnResult {
+   kbid: string;
+   path: string;
+   size: number;
+   skipped: boolean;
+}
+```
+
+| Property  | Description                           |
+|-----------|---------------------------------------|
+| `kbid`    | Knowledge-base identifier assigned    |
+| `path`    | Absolute path to the source file      |
+| `size`    | Size of file content in bytes         |
+| `skipped` | `true` when file was skipped          |
+
+### `SearchDisplay`
+
+**File:** `search-display.model.ts`
+
+A single search result formatted for display to the
+user.
+
+```ts
+interface SearchDisplay {
+   kbid: string;
+   heading: string | null;
+   type: string;
+   docids: readonly string[];
+   score: number;
+   snippet: string;
+   matched_terms: readonly string[];
+   preview: string;
+}
+```
+
+| Property        | Description                          |
+|-----------------|--------------------------------------|
+| `kbid`          | Knowledge-base identifier            |
+| `heading`       | Section heading, or `null`           |
+| `type`          | Semantic section type label          |
+| `docids`        | Parent document IDs for the section  |
+| `score`         | Relevance score from ranking engine  |
+| `snippet`       | Short excerpt highlighting matched   |
+|                 | terms                                |
+| `matched_terms` | Terms from the query that matched    |
+|                 | this section                         |
+| `preview`       | Formatted preview string for         |
+|                 | terminal output                      |
+
+No spec -- typings are compile-time only.

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

@@ -0,0 +1,20 @@
+# hash/functions -- Hash Functions
+
+**Source:** `src/shared/hash/functions/`
+
+## computeSha256
+
+```ts
+computeSha256(input: string): Promise<string>
+```
+
+Returns a hex-encoded SHA-256 hash of the input string.
+
+Uses the Web Crypto API
+(`globalThis.crypto.subtle.digest`), which is available
+in both Deno and Node.js >= 20.
+
+### Usage
+
+Used by `compute-context-id.function.ts` (truncated to
+16 hex chars) and content hashing.

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

@@ -0,0 +1,21 @@
+# hash -- Hashing Utilities
+
+**Source:** `src/shared/hash/`
+
+## Responsibility
+
+SHA-256 hashing for context ID computation and
+content-addressable storage.
+
+## Directory Layout
+
+```
+src/shared/hash/
+   index.ts
+   functions/
+      compute-sha256.function.ts
+```
+
+## Exports
+
+- [Functions](functions.md) -- `computeSha256`

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

@@ -0,0 +1,179 @@
+# mcp/classes -- MCP Server Class
+
+*Wraps the MCP protocol layer and routes incoming
+tool calls and resource reads to handler functions.*
+
+## Source
+
+`src/shared/mcp/classes/`
+
+## Classes
+
+### `McpServer`
+
+**File:** `mcp-server.class.ts`
+
+Long-lived MCP server that communicates over stdio.
+Hand-rolled JSON-RPC 2.0 protocol handling over
+stdio using `node:readline`. Implements protocol
+version **2025-11-25**.
+
+```ts
+class McpServer {
+   constructor(client: McpWorkerClient);
+   listen(): Promise<void>;
+   handleLineForTest(line: string): Promise<McpResponse | null>;
+}
+```
+
+#### Constructor
+
+Takes a `McpWorkerClient` instance. Routing happens
+at request dispatch time -- each incoming method
+name is matched to the appropriate handler.
+
+**Properties:**
+
+| Property           | Type                  | Description                  |
+|--------------------|-----------------------|------------------------------|
+| `logLevel`         | `McpLogLevel \| null` | Current log level; `null`    |
+|                    |                       | until `logging/setLevel` is  |
+|                    |                       | received                     |
+| `subscriptions`    | `Set<string>`         | Set of URIs the client has   |
+|                    |                       | subscribed to via            |
+|                    |                       | `resources/subscribe`        |
+| `hostCapabilities` | `object \| null`      | Host capabilities received   |
+|                    |                       | in the `initialize` params;  |
+|                    |                       | `null` until initialized     |
+
+**Protocol methods handled:**
+
+| Method                        | Behavior                         |
+|-------------------------------|----------------------------------|
+| `initialize`                  | Returns protocol version and capabilities |
+| `ping`                        | Returns `{}` (liveness check)    |
+| `notifications/initialized`   | Sets initialized flag            |
+| `notifications/cancelled`     | Silently ignored                 |
+| `tools/list`                  | Returns tool definitions         |
+| `tools/call`                  | Dispatches to `handleToolCall`   |
+| `prompts/list`                | Returns prompt definitions       |
+| `prompts/get`                 | Renders and returns prompt       |
+| `completion/complete`         | Returns completion suggestions   |
+| `logging/setLevel`            | Stores requested log level       |
+| `roots/list`                  | Returns `.kbdb` directory root   |
+| `resources/list`              | Returns `{ resources: [] }`      |
+| `resources/templates/list`    | Returns URI templates            |
+| `resources/read`              | Dispatches to `handleResourceRead` |
+| `resources/subscribe`         | Adds URI to subscriptions set    |
+| `resources/unsubscribe`       | Removes URI from subscriptions   |
+
+**Pre-initialization guard**: all methods except
+`initialize` and `ping` return error `-32002`
+("Server not initialized") until
+`notifications/initialized` is received.
+
+**Tools (via `handleToolCall`):**
+
+| Tool           | Client Method / Handler             |
+|----------------|-------------------------------------|
+| `search`       | `client.search()`                   |
+| `learn`        | `client.addSection()`               |
+| `unlearn`      | `client.removeSection()`            |
+| `retrieve`     | `client.readSections()` or          |
+|                | `client.retrieveDocument()`         |
+| `recall`       | `handleRecall(params, client)`      |
+| `status`       | `client.dbStatus()`                 |
+| `skill-learn`  | `handleSkillLearn(params, client)`  |
+| `skill-list`   | `handleSkillList(client)`           |
+| `skill-get`    | `handleSkillGet(params, client)`    |
+| `skill-delete` | `handleSkillDelete(params, client)` |
+| `agent-create` | `handleAgentCreate(params, client)` |
+| `agent-list`   | `handleAgentList(client)`           |
+| `agent-get`    | `handleAgentGet(params, client)`    |
+| `agent-delete` | `handleAgentDelete(params, client)` |
+
+**Resource URI templates:**
+
+| URI Template                   | MIME Type        |
+|-------------------------------|------------------|
+| `kbdb://section/{kbid}`       | `text/plain`     |
+| `kbdb://document/{docid}`     | `application/json` |
+
+#### `listen()`
+
+Returns a `Promise<void>` that resolves when stdin
+closes. Reads JSON-RPC 2.0 requests from stdin,
+dispatches to the appropriate handler, and writes
+JSON-RPC responses to stdout. Disconnects the
+`McpWorkerClient` when the promise resolves.
+
+#### `handleLineForTest(line)`
+
+Processes a single raw input line and returns the
+JSON-RPC response, or `null` for notifications
+(which have no id and expect no response). Used
+for unit testing protocol handling without stdio.
+
+#### `prompts/list` handler
+
+Calls `client.listByType('skill')` and
+`client.listDocumentsByType('agent')`, then maps
+results to `McpPrompt[]` via
+`createPromptDefinitions(sections)`. Agent prompts
+use the `agent:` name prefix.
+
+#### `prompts/get` handler
+
+Parses the prompt name to determine whether it is
+a skill (no prefix) or agent (`agent:` prefix),
+then calls `handlePromptGet(name, args, client)` to
+render the template and return `McpPromptMessage[]`.
+
+#### `completion/complete` handler
+
+Dispatches to `handleCompletion(ref, argument, client)`
+based on the ref type (`ref/prompt` or `ref/resource`)
+and returns a `McpCompletionResult` with matching
+name or URI suggestions.
+
+#### `logging/setLevel` handler
+
+Stores the requested `McpLogLevel` in `this.logLevel`.
+Subsequent log events emitted at or above this level
+are sent to the client as `notifications/message`
+using the `notify` method.
+
+#### `roots/list` handler
+
+Returns the `.kbdb` directory as a single root entry:
+`{ uri: "file:///path/to/.kbdb", name: "kbdb database" }`.
+
+#### `resources/subscribe` handler
+
+Adds the requested URI to `this.subscriptions`. When
+a subscribed resource is updated (section added,
+modified, or deleted), the server calls `notify` with
+method `notifications/resources/updated`.
+
+#### `resources/unsubscribe` handler
+
+Removes the requested URI from `this.subscriptions`.
+
+#### `notify(method, params)`
+
+Sends a server-initiated JSON-RPC 2.0 notification
+to the client over stdout. Used for log messages
+(`notifications/message`) and resource update events
+(`notifications/resources/updated`).
+
+```ts
+notify(method: string, params: unknown): void;
+```
+
+## Testing
+
+```
+src/shared/mcp/
+├── classes/
+│   └── mcp-server.spec.ts
+```