@dikolab/kbdb 0.1.0

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 Diko TechSlave
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,270 @@
+# @dikolab/kbdb
+
+A file-based knowledge base database -- no server
+required.
+
+[GitLab](https://gitlab.com/tech-slaves/knowledge-base-db)
+| [NPM](https://www.npmjs.com/package/@dikolab/kbdb)
+| [JSR](https://jsr.io/@dikolab/kbdb)
+| [License: ISC](LICENSE)
+
+---
+
+## What is kbdb?
+
+Storing and searching documentation shouldn't
+require setting up a database server, tuning
+indexes, or managing infrastructure.
+
+**kbdb** is a knowledge base that stores your docs
+in a plain folder on disk. No server to install.
+No cloud account to create. It handles indexing
+and fast search out of the box -- just point it
+at your files and start searching.
+
+It runs anywhere Node.js or Deno runs. Import your
+Markdown files, and kbdb indexes them automatically.
+Search returns ranked results instantly.
+
+As a bonus, kbdb also works as an MCP server --
+giving AI agents like Claude a searchable second
+brain. Store skills, agent profiles, and
+documentation that your AI can query across
+sessions.
+
+---
+
+## Getting Started
+
+### What You Need
+
+One of these (pick whichever you already have):
+
+- **Node.js** version 20 or newer --
+  [Download](https://nodejs.org/)
+- **Deno** version 2 or newer --
+  [Download](https://deno.com/)
+
+That's it. No database server. No extra tools.
+
+### Install
+
+**Using Node.js:**
+
+```sh
+npm install -g @dikolab/kbdb
+```
+
+**Using Deno:**
+
+```sh
+deno install -Agf jsr:@dikolab/kbdb/cli
+```
+
+### Try It Out
+
+**1. Create a knowledge base**
+
+```sh
+kbdb db init --db ./my-kb
+```
+
+This creates a `.kbdb` folder that holds all your
+data.
+
+**2. Feed it your docs**
+
+```sh
+kbdb learn ./docs --db ./my-kb
+```
+
+Point it at a folder of Markdown files. kbdb reads
+them, breaks them into sections, and builds a
+search index.
+
+**3. Search**
+
+```sh
+kbdb search "how does auth work" --db ./my-kb
+```
+
+Results are ranked by relevance. Headings and code
+get extra weight so the most useful sections surface
+first.
+
+---
+
+## What Can It Do?
+
+- **Import** Markdown files and other documents
+- **Search** with ranked results and flexible
+  query syntax
+- **Manage** documents, sections, and metadata
+- **Verify** database integrity and clean up
+  unused data
+- **Rebuild** indexes if anything goes wrong
+- **Check status** of your knowledge base
+
+See the [CLI Reference](docs/details/cli.md)
+for the full command list and examples.
+
+---
+
+## Use It With AI Agents
+
+kbdb runs as an
+[MCP](https://modelcontextprotocol.io/) server,
+so AI agents can search your docs, store reusable
+skills, and build agent profiles -- a second brain
+that persists between sessions.
+
+### Claude Code (CLI)
+
+Create `.mcp.json` in your project root:
+
+```json
+{
+   "mcpServers": {
+      "kbdb": {
+         "command": "npx",
+         "args": [
+            "-y",
+            "@dikolab/kbdb",
+            "mcp",
+            "--db",
+            "/path/to/.kbdb"
+         ]
+      }
+   }
+}
+```
+
+### Claude for VS Code
+
+Create `.vscode/mcp.json` in your project:
+
+```json
+{
+   "servers": {
+      "kbdb": {
+         "command": "npx",
+         "args": [
+            "-y",
+            "@dikolab/kbdb",
+            "mcp",
+            "--db",
+            "${workspaceFolder}/.kbdb"
+         ]
+      }
+   }
+}
+```
+
+### Claude Desktop
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+   "mcpServers": {
+      "kbdb": {
+         "command": "npx",
+         "args": [
+            "-y",
+            "@dikolab/kbdb",
+            "mcp",
+            "--db",
+            "/path/to/.kbdb"
+         ]
+      }
+   }
+}
+```
+
+### Other AI Agents
+
+Any MCP-compatible agent can connect. See the
+[MCP Server Guide](docs/details/mcp-server.md) for
+setup instructions, Deno variants, environment
+variable configuration, and the full list of
+available tools.
+
+---
+
+## For Developers
+
+### Library API
+
+Use kbdb programmatically in your Node.js or Deno
+project:
+
+```typescript
+import { createWorkerClient } from '@dikolab/kbdb';
+
+const client = await createWorkerClient({
+   contextPath: '/path/to/.kbdb',
+});
+
+const results = await client.search({
+   query: 'authentication',
+   limit: 10,
+});
+
+console.log(results);
+client.disconnect();
+```
+
+See the
+[Library API Reference](docs/details/library-api.md)
+for the full API.
+
+### Development Setup
+
+```sh
+git clone https://gitlab.com/tech-slaves/knowledge-base-db.git
+cd knowledge-base-db
+npm install
+npm test
+```
+
+### Docker
+
+A Docker setup is included with all build tools
+(Node.js, Deno, Rust, wasm-pack):
+
+```sh
+HOST_UMASK=$(umask) docker compose run --rm dev bash
+```
+
+See the [Makefile](Makefile) for all available
+build targets.
+
+### Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes and add tests
+4. Run `npm test` and `npm run lint`
+5. Open a merge request
+
+---
+
+## Documentation
+
+- [Detailed Guides](docs/details/) -- CLI
+  reference, MCP setup, search internals, storage
+  format, library API
+- [Release Notes](docs/release-notes/)
+- [Architecture Overview](docs/overview.md)
+
+---
+
+## License
+
+ISC License -- see [LICENSE](LICENSE) for details.
+
+---
+
+[GitLab](https://gitlab.com/tech-slaves/knowledge-base-db)
+| [NPM](https://www.npmjs.com/package/@dikolab/kbdb)
+| [JSR](https://jsr.io/@dikolab/kbdb)

package/dist/chunk-QCCN7OZH.mjs

@@ -0,0 +1,82 @@
+// src/shared/runtime/functions/detect-runtime.ts
+function detectRuntime() {
+  if (typeof globalThis !== "undefined" && "Deno" in globalThis) {
+    return "deno";
+  }
+  return "node";
+}
+
+// src/shared/runtime/functions/get-args.ts
+function getArgs() {
+  if (detectRuntime() === "deno") {
+    const g = globalThis;
+    const deno = g["Deno"];
+    return deno?.args ?? [];
+  }
+  return process.argv.slice(2);
+}
+
+// src/shared/dir-resolver/functions/resolve-base-dir.function.ts
+import { dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+function resolveScriptDir(entryUrl, entryDirname) {
+  if (entryDirname) return entryDirname;
+  if (entryUrl.startsWith("file:"))
+    return dirname(fileURLToPath(entryUrl));
+  return dirname(entryUrl);
+}
+function resolveBaseDir(entryUrl, entryDirname) {
+  const scriptDir = typeof __dirname !== "undefined" ? __dirname : resolveScriptDir(entryUrl, entryDirname);
+  return { scriptDir, cwd: process.cwd() };
+}
+
+// src/shared/dir-resolver/functions/resolve-worker-script.function.ts
+import { join } from "node:path";
+function resolveWorkerScript(scriptDir, runtime) {
+  if (runtime === "deno") {
+    return join(scriptDir, "worker.ts");
+  }
+  return join(scriptDir, "kbdb-worker.cjs");
+}
+
+// src/shared/dir-resolver/functions/resolve-wasm-dir.function.ts
+import { join as join2 } from "node:path";
+function resolveWasmDir(scriptDir) {
+  return join2(scriptDir, "wasm");
+}
+
+// src/shared/hash/functions/compute-sha256.ts
+async function computeSha256(input) {
+  const data = new TextEncoder().encode(input);
+  const hash = await crypto.subtle.digest("SHA-256", data);
+  const bytes = new Uint8Array(hash);
+  return Array.from(bytes).map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+
+// src/shared/platform/functions/get-ipc-path.function.ts
+import { join as join3 } from "node:path";
+
+// src/shared/platform/functions/get-tmpdir.function.ts
+import { tmpdir } from "node:os";
+function getTmpdir() {
+  return tmpdir();
+}
+
+// src/shared/platform/functions/get-ipc-path.function.ts
+function getIpcPath(ctx) {
+  if (process.platform === "win32") {
+    return `\\\\.\\pipe\\kbdb-${ctx}`;
+  }
+  return join3(getTmpdir(), `kbdb-${ctx}.sock`);
+}
+
+export {
+  detectRuntime,
+  getArgs,
+  resolveBaseDir,
+  resolveWorkerScript,
+  resolveWasmDir,
+  computeSha256,
+  getIpcPath
+};
+//# sourceMappingURL=chunk-QCCN7OZH.mjs.map

package/dist/chunk-QCCN7OZH.mjs.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/shared/runtime/functions/detect-runtime.ts", "../src/shared/runtime/functions/get-args.ts", "../src/shared/dir-resolver/functions/resolve-base-dir.function.ts", "../src/shared/dir-resolver/functions/resolve-worker-script.function.ts", "../src/shared/dir-resolver/functions/resolve-wasm-dir.function.ts", "../src/shared/hash/functions/compute-sha256.ts", "../src/shared/platform/functions/get-ipc-path.function.ts", "../src/shared/platform/functions/get-tmpdir.function.ts"],
+  "sourcesContent": ["import type { Runtime } from '../typings/runtime.ts';\n\n/**\n * Detects the current JavaScript runtime environment.\n *\n * Returns `'deno'` when the global `Deno` object is present,\n * otherwise returns `'node'`.\n */\nexport function detectRuntime(): Runtime {\n   if (typeof globalThis !== 'undefined' && 'Deno' in globalThis) {\n      return 'deno';\n   }\n   return 'node';\n}\n", "import { detectRuntime } from './detect-runtime.ts';\n\n/**\n * Returns the command-line arguments for the current runtime.\n *\n * In Deno, reads `Deno.args`; in Node.js, slices `process.argv`\n * past the interpreter and script entries.\n */\nexport function getArgs(): string[] {\n   if (detectRuntime() === 'deno') {\n      const g = globalThis as Record<string, unknown>;\n      const deno = g['Deno'] as { args: string[] } | undefined;\n      return deno?.args ?? [];\n   }\n   return process.argv.slice(2);\n}\n", "import { dirname } from 'node:path';\nimport { fileURLToPath } from 'node:url';\n\nimport type { BaseDir } from '../typings/base-dir.interface.ts';\n\nexport function resolveScriptDir(\n   entryUrl: string,\n   entryDirname?: string,\n): string {\n   if (entryDirname) return entryDirname;\n   if (entryUrl.startsWith('file:'))\n      return dirname(fileURLToPath(entryUrl));\n   return dirname(entryUrl);\n}\n\nexport function resolveBaseDir(\n   entryUrl: string,\n   entryDirname?: string,\n): BaseDir {\n   const scriptDir =\n      typeof __dirname !== 'undefined'\n         ? __dirname\n         : resolveScriptDir(entryUrl, entryDirname);\n   return { scriptDir, cwd: process.cwd() };\n}\n", "import { join } from 'node:path';\n\nimport type { Runtime } from '../../runtime/typings/runtime.ts';\n\nexport function resolveWorkerScript(\n   scriptDir: string,\n   runtime: Runtime,\n): string {\n   if (runtime === 'deno') {\n      return join(scriptDir, 'worker.ts');\n   }\n   return join(scriptDir, 'kbdb-worker.cjs');\n}\n", "import { join } from 'node:path';\n\nexport function resolveWasmDir(scriptDir: string): string {\n   return join(scriptDir, 'wasm');\n}\n", "/**\n * Computes the SHA-256 hash of a UTF-8 string.\n *\n * Uses the Web Crypto API (`crypto.subtle`), which is available\n * in both Deno and Node.js >= 20 without additional imports.\n *\n * @param input - the string to hash\n * @returns lowercase hex-encoded SHA-256 digest (64 characters)\n */\nexport async function computeSha256(input: string): Promise<string> {\n   const data = new TextEncoder().encode(input);\n   const hash = await crypto.subtle.digest('SHA-256', data);\n   const bytes = new Uint8Array(hash);\n   return Array.from(bytes)\n      .map((b) => b.toString(16).padStart(2, '0'))\n      .join('');\n}\n", "import { join } from 'node:path';\nimport { getTmpdir } from './get-tmpdir.function.ts';\n\n/**\n * Returns the platform-appropriate IPC socket path for a given\n * context identifier.\n *\n * On Windows, returns a named pipe path (`\\\\.\\pipe\\kbdb-<ctx>`).\n * On POSIX systems, returns a Unix domain socket path under the\n * system temp directory (`<tmpdir>/kbdb-<ctx>.sock`).\n *\n * @param ctx - unique context identifier embedded in the path\n */\nexport function getIpcPath(ctx: string): string {\n   if (process.platform === 'win32') {\n      return `\\\\\\\\.\\\\pipe\\\\kbdb-${ctx}`;\n   }\n   return join(getTmpdir(), `kbdb-${ctx}.sock`);\n}\n", "import { tmpdir } from 'node:os';\n\n/**\n * Returns the operating system's default temporary directory path.\n */\nexport function getTmpdir(): string {\n   return tmpdir();\n}\n"],
+  "mappings": ";AAQO,SAAS,gBAAyB;AACtC,MAAI,OAAO,eAAe,eAAe,UAAU,YAAY;AAC5D,WAAO;AAAA,EACV;AACA,SAAO;AACV;;;ACLO,SAAS,UAAoB;AACjC,MAAI,cAAc,MAAM,QAAQ;AAC7B,UAAM,IAAI;AACV,UAAM,OAAO,EAAE,MAAM;AACrB,WAAO,MAAM,QAAQ,CAAC;AAAA,EACzB;AACA,SAAO,QAAQ,KAAK,MAAM,CAAC;AAC9B;;;ACfA,SAAS,eAAe;AACxB,SAAS,qBAAqB;AAIvB,SAAS,iBACb,UACA,cACO;AACP,MAAI,aAAc,QAAO;AACzB,MAAI,SAAS,WAAW,OAAO;AAC5B,WAAO,QAAQ,cAAc,QAAQ,CAAC;AACzC,SAAO,QAAQ,QAAQ;AAC1B;AAEO,SAAS,eACb,UACA,cACQ;AACR,QAAM,YACH,OAAO,cAAc,cAChB,YACA,iBAAiB,UAAU,YAAY;AAC/C,SAAO,EAAE,WAAW,KAAK,QAAQ,IAAI,EAAE;AAC1C;;;ACxBA,SAAS,YAAY;AAId,SAAS,oBACb,WACA,SACO;AACP,MAAI,YAAY,QAAQ;AACrB,WAAO,KAAK,WAAW,WAAW;AAAA,EACrC;AACA,SAAO,KAAK,WAAW,iBAAiB;AAC3C;;;ACZA,SAAS,QAAAA,aAAY;AAEd,SAAS,eAAe,WAA2B;AACvD,SAAOA,MAAK,WAAW,MAAM;AAChC;;;ACKA,eAAsB,cAAc,OAAgC;AACjE,QAAM,OAAO,IAAI,YAAY,EAAE,OAAO,KAAK;AAC3C,QAAM,OAAO,MAAM,OAAO,OAAO,OAAO,WAAW,IAAI;AACvD,QAAM,QAAQ,IAAI,WAAW,IAAI;AACjC,SAAO,MAAM,KAAK,KAAK,EACnB,IAAI,CAAC,MAAM,EAAE,SAAS,EAAE,EAAE,SAAS,GAAG,GAAG,CAAC,EAC1C,KAAK,EAAE;AACd;;;AChBA,SAAS,QAAAC,aAAY;;;ACArB,SAAS,cAAc;AAKhB,SAAS,YAAoB;AACjC,SAAO,OAAO;AACjB;;;ADMO,SAAS,WAAW,KAAqB;AAC7C,MAAI,QAAQ,aAAa,SAAS;AAC/B,WAAO,qBAAqB,GAAG;AAAA,EAClC;AACA,SAAOC,MAAK,UAAU,GAAG,QAAQ,GAAG,OAAO;AAC9C;",
+  "names": ["join", "join", "join"]
+}