@dikolab/kbdb 0.4.3 → 0.6.0

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

@@ -1,110 +0,0 @@
-# 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
-└── log/               ← Structured logging
-```
-
-## 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.
-- **[log/](log/module.md)** -- Structured logging with
-  configurable levels, ANSI colors, and per-level
-  Unicode icons.
-
-## 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/log/
-
-shared/worker-daemon/
-  ├── shared/platform/
-  └── shared/log/
-
-shared/cli/
-  └── shared/log/
-
-shared/mcp/
-  └── shared/log/
-
-mod.ts
-  └── shared/version/
-```
-
-Utility modules (`version`, `runtime`, `platform`,
-`hash`, `log`) 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.
-`shared/log/` is a standalone utility with no
-dependencies; `cli/`, `mcp/`, `worker-daemon/`, and
-`worker-client/` all depend on it for structured
-output.

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

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

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

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

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

@@ -1,27 +0,0 @@
-# runtime -- Runtime Detection
-
-**Source:** `src/shared/runtime/`
-
-## Responsibility
-
-Detect whether the process is running on Deno or
-Node.js, and provide cross-runtime access to CLI
-arguments.
-
-## Directory Layout
-
-```
-src/shared/runtime/
-   index.ts
-   functions/
-      detect-runtime.function.ts
-      get-args.function.ts
-   typings/
-      runtime.type.ts
-```
-
-## Exports
-
-- [Functions](functions.md) -- `detectRuntime`,
-  `getArgs`
-- [Typings](typings.md) -- `Runtime`

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

@@ -1,13 +0,0 @@
-# runtime/typings -- Runtime Type Definitions
-
-**Source:** `src/shared/runtime/typings/`
-
-## Runtime
-
-```ts
-type Runtime = 'deno' | 'node';
-```
-
-Discriminant for the two supported JavaScript runtimes.
-
-No spec -- typings are compile-time only.

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

@@ -1,27 +0,0 @@
-# version -- Package Version
-
-**Source:** `src/shared/version/`
-
-## Responsibility
-
-Exposes the current package version as a constant.
-Exported from the library API (`mod.ts`). Currently the
-only public export.
-
-## Exports
-
-- `version` -- `'0.0.1'`
-
-## Directory Layout
-
-```
-src/shared/version/
-   index.ts
-   constants/
-      version.constant.ts
-```
-
-## Spec
-
-- `version.spec.ts` -- Validates the version string
-  format.

package/docs/modules/typescript/shared/wasm-codec/functions.md

@@ -1,391 +0,0 @@
-# wasm-codec/functions -- Codec Functions
-
-*One encode or decode function per file. Encoders
-build `Uint8Array` buffers; decoders parse them into
-typed TypeScript values.*
-
-## Source
-
-`src/shared/wasm-codec/functions/`
-
----
-
-## Encoder Functions
-
-### `encodeString`
-
-**File:** `encode-string.function.ts`
-
-Encodes a UTF-8 string as a little-endian `u32`
-length prefix followed by the UTF-8 bytes.
-
-```ts
-function encodeString(value: string): Uint8Array;
-```
-
-### `encodeU32`
-
-**File:** `encode-u32.function.ts`
-
-Encodes an unsigned 32-bit integer as 4 bytes,
-little-endian.
-
-```ts
-function encodeU32(value: number): Uint8Array;
-```
-
-### `encodeOptionString`
-
-**File:** `encode-option-string.function.ts`
-
-Encodes an optional string. Writes `0x00` for `null`
-or `undefined`; writes `0x01` followed by the encoded
-string for a present value.
-
-```ts
-function encodeOptionString(
-   value: string | null | undefined,
-): Uint8Array;
-```
-
-### `encodeSectionType`
-
-**File:** `encode-section-type.function.ts`
-
-Encodes a section type discriminant. Writes `0x00`
-for `text` (no MIME), `0x01` + MIME for `code`, or
-`0x02` + MIME for `image`.
-
-```ts
-function encodeSectionType(
-   kind: 'text' | 'code' | 'image',
-   mimeType?: string,
-): Uint8Array;
-```
-
-### `encodeAddSectionParams`
-
-**File:** `encode-add-section-params.function.ts`
-
-Encodes parameters for the `worker_add_section` WASM
-export: section type, content, optional title,
-optional description, and optional docid, in that
-order.
-
-```ts
-function encodeAddSectionParams(
-   params: AddSectionInput,
-): Uint8Array;
-```
-
-```ts
-interface AddSectionInput {
-   sectionType: 'text' | 'code' | 'image';
-   mimeType?: string;
-   content: string;
-   title?: string | null;
-   description?: string | null;
-   docid?: string | null;
-}
-```
-
-### `encodeUpdateSectionParams`
-
-**File:** `encode-update-section-params.function.ts`
-
-Encodes parameters for the `worker_update_section`
-WASM export: the old KB ID as an encoded string
-followed by the full `AddSectionInput` encoding.
-
-```ts
-function encodeUpdateSectionParams(
-   oldKbid: string,
-   params: AddSectionInput,
-): Uint8Array;
-```
-
-### `encodeKbidList`
-
-**File:** `encode-kbid-list.function.ts`
-
-Encodes a list of KB IDs as a `u32` count followed
-by each ID encoded as a length-prefixed string.
-Returns an empty `Uint8Array` for an empty list.
-
-```ts
-function encodeKbidList(kbids: string[]): Uint8Array;
-```
-
-### `encodeGroupParams`
-
-**File:** `encode-group-params.function.ts`
-
-Encodes parameters for the `worker_group_sections`
-WASM export: the document title followed by a
-`encodeKbidList` encoding of the section IDs.
-
-```ts
-function encodeGroupParams(
-   title: string,
-   kbids: string[],
-): Uint8Array;
-```
-
-### `encodeIdentifierList`
-
-**File:** `encode-identifier-list.function.ts`
-
-Encodes a list of arbitrary string identifiers (kbid
-or docid) as a `u32` count followed by each ID as a
-length-prefixed string. Returns an empty `Uint8Array`
-for an empty list.
-
-```ts
-function encodeIdentifierList(
-   ids: string[],
-): Uint8Array;
-```
-
-### `encodeSearchParams`
-
-**File:** `encode-search-params.function.ts`
-
-Encodes search parameters as a newline-delimited
-UTF-8 string: `query\nmode\nlimit`.
-
-```ts
-function encodeSearchParams(
-   query: string,
-   mode?: string,
-   limit?: number,
-): Uint8Array;
-```
-
-`mode` defaults to `'and'`; `limit` defaults to `20`.
-
----
-
-## Decoder Functions
-
-### `decodeString`
-
-**File:** `decode-string.function.ts`
-
-Reads a length-prefixed UTF-8 string from a byte
-buffer at the given offset.
-
-```ts
-function decodeString(
-   bytes: Uint8Array,
-   offset: number,
-): DecodeResult<string>;
-
-interface DecodeResult<T> {
-   value: T;
-   bytesRead: number;
-}
-```
-
-### `decodeU32`
-
-**File:** `decode-u32.function.ts`
-
-Reads a little-endian `u32` from a byte buffer at the
-given offset.
-
-```ts
-function decodeU32(
-   bytes: Uint8Array,
-   offset: number,
-): DecodeResult<number>;
-```
-
-### `decodeF32`
-
-**File:** `decode-f32.function.ts`
-
-Reads a little-endian IEEE 754 `f32` from a byte
-buffer at the given offset.
-
-```ts
-function decodeF32(
-   bytes: Uint8Array,
-   offset: number,
-): DecodeResult<number>;
-```
-
-### `decodeU64`
-
-**File:** `decode-u64.function.ts`
-
-Reads a little-endian `u64` from a byte buffer at the
-given offset. Returns a `bigint`.
-
-```ts
-function decodeU64(
-   bytes: Uint8Array,
-   offset: number,
-): DecodeResult<bigint>;
-```
-
-### `decodeScoredResults`
-
-**File:** `decode-scored-results.function.ts`
-
-Decodes the binary response from `worker_search`
-into an array of scored results.
-
-```ts
-function decodeScoredResults(
-   bytes: Uint8Array,
-): ScoredResult[];
-
-interface ScoredResult {
-   kbid: string;
-   score: number;
-   matches: TermMatch[];
-}
-
-interface TermMatch {
-   term: string;
-   frequency: number;
-}
-```
-
-Wire format: `u32` count, then for each result:
-kbid (length-prefixed string), score (`f32`), match
-count (`u32`), then for each match: term (string),
-frequency (`f32`).
-
-### `decodeSectionRecords`
-
-**File:** `decode-section-records.function.ts`
-
-Decodes the binary response from `worker_read_sections`
-into an array of section records.
-
-```ts
-function decodeSectionRecords(
-   bytes: Uint8Array,
-): SectionRecord[];
-
-interface SectionRecord {
-   kbid: string;
-   docid: string | null;
-   sectionType: string;
-   mimeType?: string;
-   title: string | null;
-   description: string | null;
-   content: string;
-   size: number;
-   createdAt: bigint;
-   checksum: string;
-   tokenCount: number;
-   headingTokenCount: number;
-   bodyTokenCount: number;
-   codeTokenCount: number;
-}
-```
-
-### `decodeDocumentManifest`
-
-**File:** `decode-document-manifest.function.ts`
-
-Decodes the binary response from `worker_retrieve_doc`
-into a document manifest.
-
-```ts
-function decodeDocumentManifest(
-   bytes: Uint8Array,
-): DocumentManifest;
-
-interface DocumentManifest {
-   docid: string;
-   title: string;
-   createdAt: bigint;
-   sections: DocumentSection[];
-}
-
-interface DocumentSection {
-   kbid: string;
-   position: number;
-}
-```
-
-### `decodeComposeOutput`
-
-**File:** `decode-compose-output.function.ts`
-
-Decodes the binary response from `worker_compose`
-into a Markdown string and character count.
-
-```ts
-function decodeComposeOutput(
-   bytes: Uint8Array,
-): ComposeOutput;
-
-interface ComposeOutput {
-   markdown: string;
-   totalChars: bigint;
-}
-```
-
-Wire format: length-prefixed Markdown string followed
-by a `u64` character count.
-
-### `decodeKeyValueText`
-
-**File:** `decode-key-value-text.function.ts`
-
-Parses a newline-delimited `key=value` text response
-into a `Record<string, string>`. Used to decode
-responses from `worker_status`, `worker_check_integrity`,
-and `worker_garbage_collect`.
-
-```ts
-function decodeKeyValueText(
-   text: string,
-): Record<string, string>;
-```
-
-Lines without a `=` separator are silently skipped.
-
-### `decodeRemoveFlag`
-
-**File:** `decode-remove-flag.function.ts`
-
-Decodes a single-byte boolean response from
-`worker_remove_section`. Returns `true` when the
-first byte is `0x01`.
-
-```ts
-function decodeRemoveFlag(bytes: Uint8Array): boolean;
-```
-
-## Testing
-
-Each function has a `.spec.ts` at the module root:
-
-```
-src/shared/wasm-codec/
-├── encode-string.spec.ts
-├── encode-u32.spec.ts
-├── encode-option-string.spec.ts
-├── encode-section-type.spec.ts
-├── encode-add-section-params.spec.ts
-├── encode-update-section-params.spec.ts
-├── encode-kbid-list.spec.ts
-├── encode-group-params.spec.ts
-├── encode-identifier-list.spec.ts
-├── encode-search-params.spec.ts
-├── decode-string.spec.ts
-├── decode-u32.spec.ts
-├── decode-f32.spec.ts
-├── decode-u64.spec.ts
-├── decode-scored-results.spec.ts
-├── decode-section-records.spec.ts
-├── decode-document-manifest.spec.ts
-├── decode-compose-output.spec.ts
-├── decode-key-value-text.spec.ts
-└── decode-remove-flag.spec.ts
-```