@dikolab/kbdb 0.5.0 → 0.6.0

package/docs/modules/typescript/overview.md

@@ -1,400 +0,0 @@
-# TypeScript Layer -- Overview
-
-*Module structure, file conventions, and source layout
-for the TypeScript executables and shared modules.*
-
-## Architecture
-
-Two thin executables, all logic in `src/shared/`
-sub-modules. Heavy computation (keyword extraction,
-indexing, ranking) runs in the Rust/WASM engine.
-TypeScript handles CLI parsing, MCP protocol, IPC
-transport, and WASM module loading.
-
-```
-src/cli.ts ──────────────────────────────────┐
-  │  (CLI mode or MCP mode)                  │
-  ├─ imports shared/cli/                     │
-  ├─ imports shared/mcp/                     │
-  └─ imports shared/worker-client/ ──IPC──→  │
-                                             │
-src/worker.ts ───────────────────────────────┤
-  │  (detached daemon process)               │
-  └─ imports shared/worker-daemon/           │
-       └─ loads WASM modules                 │
-          (query-parser, fs-database,        │
-           kb-worker)                        │
-                                             │
-mod.ts ──→ library API (npm/JSR)             │
-  └─ re-exports from shared/version/         │
-```
-
-## Entry Points
-
-Two executable entry points at the project root. Both
-are bundled by esbuild into `dist/` as ESM + CJS.
-
-| Entry                 | Purpose                | Lifecycle   |
-|-----------------------|------------------------|-------------|
-| `src/cli.ts`          | CLI + MCP executable   | Short or long-lived |
-| `src/worker.ts`       | Worker daemon          | Detached background |
-| `mod.ts`              | Library API (npm/JSR)  | Import only |
-
-### `src/cli.ts`
-
-The `kbdb` command. Detects the run mode from the
-first argument:
-
-- `kbdb mcp [--db <path>]` → MCP server mode
-  (long-lived, stdio JSON-RPC 2.0)
-- `kbdb <command> [options]` → CLI mode
-  (short-lived, runs one command and exits)
-
-Both modes create a `WorkerClient` and delegate all
-operations to the daemon. The executable itself
-contains no business logic -- it dispatches to
-`shared/cli/` or `shared/mcp/`.
-
-### `src/worker.ts`
-
-The worker daemon. Spawned as a detached child process
-by the worker-client module. Loads the four WASM
-modules, listens on a local IPC socket, and serves
-JSON-RPC 2.0 requests until idle timeout.
-
-Contains no business logic -- dispatches to
-`shared/worker-daemon/`.
-
-## Source Layout
-
-```
-src/cli.ts                           ← executable
-src/worker.ts                        ← executable
-mod.ts                               ← library API
-
-src/shared/
-├── cli/                             ← CLI commands
-│   ├── 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
-│
-├── mcp/                             ← MCP server
-│   ├── index.ts
-│   ├── classes/
-│   │   └── mcp-server.class.ts
-│   ├── functions/
-│   │   ├── create-mcp-server.function.ts
-│   │   ├── create-prompt-definitions.function.ts
-│   │   ├── create-resource-templates.function.ts
-│   │   ├── create-tool-definitions.function.ts
-│   │   ├── handle-agent-create.function.ts
-│   │   ├── handle-agent-delete.function.ts
-│   │   ├── handle-agent-get.function.ts
-│   │   ├── handle-agent-list.function.ts
-│   │   ├── handle-completion.function.ts
-│   │   ├── handle-prompt-get.function.ts
-│   │   ├── handle-resource-read.function.ts
-│   │   ├── handle-skill-delete.function.ts
-│   │   ├── handle-skill-get.function.ts
-│   │   ├── handle-skill-learn.function.ts
-│   │   ├── handle-skill-list.function.ts
-│   │   ├── handle-tool-call.function.ts
-│   │   ├── parse-skill-content.function.ts
-│   │   └── serialize-skill-content.function.ts
-│   └── typings/
-│       ├── mcp-client.interface.ts
-│       └── mcp-types.interface.ts
-│
-├── worker-client/                   ← IPC client
-│   ├── index.ts
-│   ├── classes/
-│   │   └── worker-client.class.ts
-│   ├── functions/
-│   │   ├── compute-context-id.function.ts
-│   │   ├── create-worker-client.function.ts
-│   │   ├── discover-daemon.function.ts
-│   │   ├── resolve-db-path.function.ts
-│   │   ├── spawn-daemon.function.ts
-│   │   └── wait-for-daemon.function.ts
-│   └── typings/
-│       ├── add-section-result.model.ts
-│       ├── content-result.model.ts
-│       ├── daemon-info.model.ts
-│       ├── gc-result.model.ts
-│       ├── integrity-check-result.model.ts
-│       ├── migrate-result.model.ts
-│       ├── rebuild-result.model.ts
-│       ├── remove-section-result.model.ts
-│       ├── search-params.model.ts
-│       ├── search-result.model.ts
-│       ├── section.model.ts
-│       ├── status-result.model.ts
-│       ├── version-status.model.ts
-│       ├── worker-client-error.interface.ts
-│       └── worker-client-options.interface.ts
-│
-├── worker-daemon/                   ← Daemon process
-│   ├── index.ts
-│   ├── classes/
-│   │   └── worker-daemon.class.ts
-│   ├── functions/
-│   │   ├── create-host-imports.function.ts
-│   │   ├── create-ipc-server.function.ts
-│   │   ├── load-wasm-modules.function.ts
-│   │   ├── read-config.function.ts
-│   │   ├── run-worker.function.ts
-│   │   └── start-daemon.function.ts
-│   ├── typings/
-│   │   ├── daemon-config.interface.ts
-│   │   ├── ipc-handler.interface.ts
-│   │   └── wasm-modules.interface.ts
-│   └── constants/
-│       └── daemon-defaults.constant.ts
-│
-├── wasm-codec/                      ← WASM binary codec
-│   ├── index.ts
-│   └── functions/
-│       ├── decode-compose-output.function.ts
-│       ├── decode-document-manifest.function.ts
-│       ├── decode-f32.function.ts
-│       ├── decode-key-value-text.function.ts
-│       ├── decode-remove-flag.function.ts
-│       ├── decode-scored-results.function.ts
-│       ├── decode-section-records.function.ts
-│       ├── decode-string.function.ts
-│       ├── decode-u32.function.ts
-│       ├── decode-u64.function.ts
-│       ├── encode-add-section-params.function.ts
-│       ├── encode-group-params.function.ts
-│       ├── encode-identifier-list.function.ts
-│       ├── encode-kbid-list.function.ts
-│       ├── encode-option-string.function.ts
-│       ├── encode-search-params.function.ts
-│       ├── encode-section-type.function.ts
-│       ├── encode-string.function.ts
-│       ├── encode-u32.function.ts
-│       └── encode-update-section-params.function.ts
-│
-├── version/                         ← Package version
-│   ├── index.ts
-│   └── constants/
-│       └── version.constant.ts
-│
-├── runtime/                         ← Runtime detection
-│   ├── index.ts
-│   ├── functions/
-│   │   ├── detect-runtime.function.ts
-│   │   └── get-args.function.ts
-│   └── typings/
-│       └── runtime.type.ts
-│
-├── platform/                        ← OS abstractions
-│   ├── index.ts
-│   └── functions/
-│       ├── get-ipc-path.function.ts
-│       ├── get-tmpdir.function.ts
-│       └── is-process-alive.function.ts
-│
-├── hash/                            ← SHA-256 hashing
-│   ├── index.ts
-│   └── functions/
-│       └── compute-sha256.function.ts
-│
-└── log/                             ← Structured logging
-    ├── index.ts
-    ├── constants/
-    │   ├── log-colors.constant.ts
-    │   ├── log-defaults.constant.ts
-    │   └── log-icons.constant.ts
-    ├── functions/
-    │   ├── configure-log.function.ts
-    │   ├── log.function.ts
-    │   ├── parse-log-level.function.ts
-    │   ├── resolve-log-level.function.ts
-    │   └── write-stderr.function.ts
-    └── typings/
-        ├── log-config.interface.ts
-        ├── log-level.type.ts
-        └── log-output.interface.ts
-```
-
-## Module Conventions
-
-Every module follows the directory structure defined
-in the TypeScript skill (`.claude/skills/typescript.md`).
-
-### Directory Roles
-
-| Directory     | Contents                   | File suffix         |
-|---------------|----------------------------|---------------------|
-| `classes/`    | One class per file         | `.class.ts`         |
-| `functions/`  | One function per file      | `.function.ts`      |
-| `constants/`  | Related constants grouped  | `.constant.ts`      |
-| `typings/`    | Type declarations          | `.type.ts`, `.enum.ts`, `.interface.ts`, `.model.ts` |
-| `tests/`      | BDD module integration     | `.spec.ts`          |
-| (root)        | TDD unit specs + barrel    | `.spec.ts`, `index.ts` |
-
-### Import Conventions
-
-All imports go to `src/shared/[module]/` -- there is
-**no** `src/shared/index.ts` barrel.
-
-```ts
-// Import from sub-module barrel
-import {
-   WorkerClient,
-} from './shared/worker-client/index.ts';
-
-// Import from specific file
-import {
-   createWorkerClient,
-} from './shared/worker-client/functions/create-worker-client.function.ts';
-
-// Import shared utility
-import {
-   computeSha256,
-} from './shared/hash/functions/compute-sha256.function.ts';
-
-// Type-only imports (separate statement)
-import type {
-   WorkerClientOptions,
-} from './shared/worker-client/typings/worker-client-options.interface.ts';
-```
-
-All imports use `.ts` extensions (Deno requires them).
-Type-only imports use separate `import type`
-statements.
-
-### File Naming
-
-| Category   | Convention          | Example                    |
-|------------|---------------------|----------------------------|
-| Module dir | kebab-case          | `worker-client/`           |
-| Class file | `<name>.class.ts`   | `worker-client.class.ts`   |
-| Function   | `<name>.function.ts`| `spawn-daemon.function.ts` |
-| Constant   | `<name>.constant.ts`| `defaults.constant.ts`     |
-| Interface  | `<name>.interface.ts`| `cli-options.interface.ts` |
-| Type alias | `<name>.type.ts`    | `daemon-status.type.ts`    |
-| Enum       | `<name>.enum.ts`    | `output-format.enum.ts`    |
-| Model      | `<name>.model.ts`   | `search-result.model.ts`   |
-| TDD spec   | `<name>.spec.ts`    | `spawn-daemon.spec.ts`     |
-| BDD spec   | `<scenario>.spec.ts`| `search-workflow.spec.ts`  |
-| Barrel     | `index.ts`          | `index.ts`                 |
-
-### Dual Runtime
-
-All code must work on both Deno and Node.js >= 20:
-
-- No `node:` protocol in library code
-- No Deno-specific APIs (`Deno.readTextFile`) in
-  library code
-- Runtime detection via `typeof Deno !== 'undefined'`
-- Platform abstractions in `shared/platform/`
-
-## Build Output
-
-```
-dist/
-├── mod.mjs          ← ESM library
-├── mod.cjs          ← CJS library
-├── mod.d.ts         ← declarations
-├── cli.mjs          ← ESM CLI+MCP (shebang)
-├── cli.cjs          ← CJS CLI+MCP (shebang)
-├── worker.mjs       ← ESM daemon (shebang)
-├── worker.cjs       ← CJS daemon (shebang)
-├── chunk-*.mjs      ← shared code chunks
-└── src/
-    └── **/*.d.ts    ← per-file declarations
-```
-
-## Doc Directory Structure
-
-Documentation mirrors the source layout. All module
-docs live under `shared/`, matching the source tree.
-
-```
-docs/modules/typescript/
-├── overview.md              ← this file
-└── shared/
-    ├── module.md            ← shared overview
-    ├── cli/
-    │   ├── module.md
-    │   ├── functions.md
-    │   ├── typings.md
-    │   └── constants.md
-    ├── mcp/
-    │   ├── module.md
-    │   ├── classes.md
-    │   ├── functions.md
-    │   └── typings.md
-    ├── worker-client/
-    │   ├── module.md
-    │   ├── classes.md
-    │   ├── functions.md
-    │   └── typings.md
-    ├── worker-daemon/
-    │   ├── module.md
-    │   ├── classes.md
-    │   ├── functions.md
-    │   ├── typings.md
-    │   └── constants.md
-    ├── wasm-codec/
-    │   ├── module.md
-    │   └── functions.md
-    ├── version/
-    │   └── module.md
-    ├── runtime/
-    │   ├── module.md
-    │   ├── functions.md
-    │   └── typings.md
-    ├── platform/
-    │   ├── module.md
-    │   └── functions.md
-    ├── hash/
-    │   ├── module.md
-    │   └── functions.md
-    └── log/
-        ├── module.md
-        ├── functions.md
-        ├── typings.md
-        └── constants.md
-```
-
-`module.md` = `index.ts` (module entry point).
-Category files document the implementations within
-each subdirectory.

package/docs/modules/typescript/shared/auto-capture/module.md

@@ -1,73 +0,0 @@
-# auto-capture -- MCP Sampling-Based Automatic Knowledge Capture
-
-**Source:** `src/shared/auto-capture/`
-
-## Responsibility
-
-Automatic knowledge capture from AI agent conversations. Uses MCP
-`sampling/createMessage` to ask the host LLM to identify knowledge
-worth storing, then feeds extracted knowledge into kbdb via `learn`.
-Operates as an MCP server-side feature -- the server proactively
-requests captures based on configurable triggers.
-
-## Directory Layout
-
-```
-src/shared/auto-capture/
-   index.ts
-   auto-capture.controller.ts
-   trigger.ts
-   sampling-prompt.ts
-   rate-limiter.ts
-```
-
-## Components
-
-- **AutoCaptureController** (`auto-capture.controller.ts`) --
-  Orchestrates the capture flow. Tracks tool call count, checks
-  trigger conditions, invokes sampling, and feeds results to
-  `learn`. Stateful per MCP session.
-- **Trigger logic** (`trigger.ts`) -- Evaluates whether a capture
-  check should fire. Conditions: (a) after N tool calls (default:
-  10), (b) configurable time interval, (c) explicit
-  `auto-capture-review` tool invocation. Multiple triggers can be
-  active simultaneously.
-- **Sampling prompts** (`sampling-prompt.ts`) -- Prompt templates
-  sent via `sampling/createMessage`. The prompt asks the host LLM
-  to extract knowledge from the conversation that matches the
-  `memory-protocol` skill's storage criteria: facts, decisions,
-  rationale, procedures.
-- **Rate limiter** (`rate-limiter.ts`) -- Prevents excessive
-  capture attempts. Enforces minimum interval between captures
-  (default: 60 s) and maximum captures per session (default: 20).
-
-## Configuration
-
-Configured via the `[auto_capture]` section of `worker.toml`:
-
-```toml
-[auto_capture]
-enabled = false
-trigger_after_tool_calls = 10
-min_interval_seconds = 60
-max_captures_per_session = 20
-dry_run = false
-```
-
-When `dry_run = true`, the controller logs what would be captured
-without actually writing to the database. Useful for tuning
-triggers.
-
-## Dependency Direction
-
-```
-shared/auto-capture/
-  └── (no shared module deps -- uses MCP sampling API)
-
-shared/mcp/
-  └── shared/auto-capture/   (controller lifecycle)
-```
-
-The auto-capture module is instantiated by the MCP server module.
-It uses the MCP protocol's sampling capability -- not direct imports
-of other shared modules.

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

@@ -1,23 +0,0 @@
-# cli/constants -- CLI Defaults
-
-*Default values for CLI options.*
-
-## Source
-
-`src/shared/cli/constants/`
-
-### `defaults`
-
-**File:** `defaults.constant.ts`
-
-```ts
-const DEFAULT_LIMIT = 20;
-const DEFAULT_FORMAT = OutputFormat.Json;
-const DEFAULT_MODE = 'sections';
-```
-
-| Constant         | Value        | Used by      |
-|------------------|-------------|--------------|
-| `DEFAULT_LIMIT`  | `20`        | `parseArgs`  |
-| `DEFAULT_FORMAT` | `'json'`    | `parseArgs`  |
-| `DEFAULT_MODE`   | `'sections'`| `parseArgs`  |