@dikolab/kbdb 0.1.5 → 0.2.0

package/docs/modules/typescript/kbdb-worker.md

@@ -0,0 +1,135 @@
+# src/worker.ts -- Worker Daemon Executable
+
+*Thin entry point for the detached daemon process that
+loads WASM modules and serves IPC requests.*
+
+## File
+
+`src/worker.ts`
+
+## Built To
+
+| Format | Output                   | Notes   |
+|--------|--------------------------|---------|
+| ESM    | `dist/worker.mjs`        | shebang |
+| CJS    | `dist/worker.cjs`        | shebang |
+| `.d.ts`| `dist/worker.d.ts`       |         |
+
+Not registered as an npm `bin` -- this executable is
+not invoked directly by users. It is spawned as a
+detached child process by `shared/worker-client/`.
+
+## How It Is Spawned
+
+The worker-client module spawns this executable when
+no running daemon is found for the target database:
+
+**Node.js:**
+
+```ts
+spawn(
+   'node',
+   ['kbdb-worker.js', contextPath],
+   { detached: true, stdio: ['ignore', 'ignore', 'pipe'] },
+).unref();
+```
+
+**Deno:**
+
+```ts
+new Deno.Command('deno', {
+   args: [
+      'run', '--allow-all',
+      'src/worker.ts', contextPath,
+   ],
+   stdin: 'null',
+   stdout: 'null',
+   stderr: 'piped',
+}).spawn().unref();
+```
+
+The sole command-line argument is the **context path**
+-- the absolute path to the `.kbdb` database directory.
+
+## Execution Flow
+
+```
+src/worker.ts
+  │
+  ├─ import startDaemon from shared/worker-daemon/
+  │
+  ├─ read contextPath from argv[0]
+  ├─ validate contextPath exists
+  │
+  └─ await startDaemon(contextPath)
+       │
+       ├─ readConfig(contextPath)
+       │    └─ parse .kbdb/worker.toml
+       │
+       ├─ loadWasmModules(config)
+       │    ├─ allocate shared WebAssembly.Memory
+       │    ├─ compile query-parser.wasm (standalone)
+       │    ├─ compile fs-database.wasm (standalone)
+       │    └─ compile kb-worker.wasm
+       │         (imports both modules)
+       │
+       ├─ write PID file
+       │    └─ kb-worker-{ctx}.pid in tmpdir
+       │
+       ├─ createIpcServer(ctx, handler)
+       │    └─ Unix socket or named pipe
+       │
+       ├─ listen for connections
+       │    └─ JSON-RPC 2.0, newline-delimited
+       │
+       └─ on idle timeout or signal:
+            ├─ stop accepting connections
+            ├─ wait for in-flight requests
+            ├─ purge cache
+            ├─ remove PID file
+            ├─ remove IPC socket
+            └─ exit
+```
+
+## Imports
+
+```ts
+import {
+   startDaemon,
+} from './src/shared/worker-daemon/functions/start-daemon.function.ts';
+```
+
+## No Business Logic
+
+This file contains **only** argument reading and a
+single function call. All daemon logic lives in
+`shared/worker-daemon/`:
+
+| Concern            | Module                      |
+|--------------------|-----------------------------|
+| WASM loading       | `shared/worker-daemon/`     |
+| IPC server         | `shared/worker-daemon/`     |
+| Config reading     | `shared/worker-daemon/`     |
+| Cache management   | WASM (`kb-worker.wasm`)     |
+| Query orchestration| WASM (`kb-worker.wasm`)     |
+| Index operations   | WASM (`fs-database.wasm`)   |
+| Tokenization       | WASM (`query-parser.wasm`)  |
+| Platform helpers   | `shared/platform/`          |
+
+## Lifecycle
+
+1. Spawned by worker-client as detached child process
+2. Loads and compiles 3 WASM modules (once)
+3. Serves IPC requests from any connected client
+4. Shuts down after idle timeout (`timeout_ms`) or
+   OS signal (SIGTERM, SIGINT)
+5. Cleans up PID file and IPC socket on exit
+
+Multiple daemons can run simultaneously on the same
+machine, each serving a different database directory.
+Each daemon is identified by its **context ID**
+(SHA-256 of the database path, truncated to 16 hex
+chars).
+
+See [Worker Daemon](../../goals/worker-daemon.md) for
+the full behavioral specification.

package/docs/modules/typescript/overview.md

@@ -0,0 +1,378 @@
+# 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 three 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
+```
+
+## 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
+```
+
+`module.md` = `index.ts` (module entry point).
+Category files document the implementations within
+each subdirectory.

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

@@ -0,0 +1,23 @@
+# 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`  |