@dikolab/kbdb 0.5.0 → 0.6.0

package/dist/src/shared/cli/functions/format-db-not-found.function.d.ts

@@ -0,0 +1,20 @@
+/** Options controlling the "database not found" diagnostic. */
+interface FormatDbNotFoundOptions {
+    /** Explicit `--db` flag value, if provided. */
+    dbPath?: string;
+    /** When true, omits the cwd traversal line and init hint. */
+    skipTraversal?: boolean;
+}
+/**
+ * Formats the error message shown when no `.kbdb` database
+ * directory can be resolved.
+ *
+ * When `options.dbPath` is set, an explicit `--db` flag failed
+ * to resolve and a single-line message is returned. Otherwise a
+ * multi-line diagnostic lists each fallback that was checked so
+ * the user can see why resolution failed.
+ *
+ * @param options - resolution context that produced the failure
+ */
+export declare function formatDbNotFound(options: FormatDbNotFoundOptions): string;
+export type { FormatDbNotFoundOptions };

package/dist/src/shared/cli/functions/format-output.function.d.ts

@@ -6,6 +6,7 @@ import type { PagedSearchDisplay } from '../typings/search-display.model.ts';
  *
  * - `'json'` -- pretty-printed JSON envelope
  * - `'text'` -- numbered human-readable list with paging footer
+ * - `'rec'` -- recfile field records, one per result
  * - `'mcp'` -- JSON envelope compatible with MCP protocol
  *
  * @param paged - paginated search results to format

package/dist/src/shared/cli/functions/format-recfile-output.function.d.ts

@@ -0,0 +1,11 @@
+import type { RecfileFieldMap } from '../typings/recfile-field-map.type.ts';
+/**
+ * Formats one or more records as recfile (GNU recutils style)
+ * output: `Field: Value` pairs, blank-line separated records,
+ * and `+ ` continuation lines for multi-line values.
+ *
+ * @param data - a single record or an array of records
+ * @param fields - ordered field map controlling which
+ *   properties are rendered and in what order
+ */
+export declare function formatRecfileOutput(data: unknown, fields: RecfileFieldMap): string;

package/dist/src/shared/cli/functions/render-recfile-value.function.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Renders a value for recfile output, or returns `null` when the
+ * value is absent and the field should be omitted.
+ *
+ * Arrays render comma-separated; booleans render as `'true'` or
+ * `'false'`; `null`, `undefined`, empty strings, and empty
+ * arrays are treated as absent.
+ *
+ * @param value - the value to render
+ */
+export declare function renderRecfileValue(value: unknown): string | null;

package/dist/src/shared/cli/functions/resolve-db-dir.function.d.ts

@@ -0,0 +1,24 @@
+import type { DbResolution } from '../typings/db-resolution.interface.ts';
+/** Options controlling database directory resolution. */
+interface ResolveDbDirOptions {
+    /** Explicit `--db` flag value, if provided. */
+    dbPath?: string;
+    /** When true, skips cwd upward traversal. */
+    skipTraversal?: boolean;
+}
+/**
+ * Resolves the `.kbdb` database directory using a strict
+ * priority chain: explicit `--db` flag, then upward cwd
+ * traversal, then the `KBDB_DB_DIR` environment variable.
+ *
+ * An explicit `--db` flag that fails to resolve returns
+ * `null` immediately -- it never falls through to
+ * traversal or the environment variable.
+ *
+ * @param findDb - locates a `.kbdb` directory. Called with
+ *   a base path to resolve from, or with no argument to
+ *   trigger upward traversal from the current working
+ *   directory.
+ */
+export declare function resolveDbDir(options: ResolveDbDirOptions, findDb: (basePath?: string) => string | null): DbResolution | null;
+export type { ResolveDbDirOptions };

package/dist/src/shared/cli/functions/resolve-recfile-key.function.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Resolves a dot-notation property path (e.g.
+ * `'cacheStats.contentCount'`) against an object, returning
+ * `undefined` if any segment along the path is missing.
+ *
+ * @param obj - the object to traverse
+ * @param key - dot-separated property path
+ */
+export declare function resolveRecfileKey(obj: unknown, key: string): unknown;

package/dist/src/shared/cli/functions/run-db-path.function.d.ts

@@ -0,0 +1,10 @@
+import type { CommandResult } from '../typings/command-result.model.ts';
+import type { CliOptions } from '../typings/cli-options.interface.ts';
+/**
+ * Handles the `kbdb db path` subcommand.
+ *
+ * Prints the resolved `.kbdb` directory path. With
+ * `--format json`, outputs a full diagnostic object
+ * showing which source provided the resolution.
+ */
+export declare function runDbPath(options: Pick<CliOptions, 'dbPath' | 'format'>, findDb: (basePath?: string) => string | null): CommandResult;

package/dist/src/shared/cli/functions/run-export.function.d.ts

@@ -10,8 +10,9 @@ export interface ExportClient {
     /**
      * Exports the database to the given directory path.
      *
-     * @param params - optional target path; the daemon defaults to
-     *   `./kbdb-export/` when `path` is `undefined`
+     * @param params - optional absolute target path; the daemon
+     *   picks its own default, relative to the database directory,
+     *   when `path` is `undefined`
      * @returns export report with the resolved path and file counts
      */
     export(params: {
@@ -22,8 +23,11 @@ export interface ExportClient {
  * Exports the knowledge-base database to a target directory via the
  * provided client.
  *
- * The target path is taken from `options.args[0]`. When no argument
- * is given the daemon resolves its own default (`./kbdb-export/`).
+ * The target path is taken from `options.args[0]` and resolved
+ * against the current working directory so that the daemon --
+ * which may run with a different working directory -- always
+ * receives an absolute path. When no argument is given, the daemon
+ * picks its own default.
  *
  * @param client - export client to delegate to
  * @param options - parsed CLI options whose first positional

package/dist/src/shared/cli/functions/run-import.function.d.ts

@@ -19,6 +19,10 @@ export interface ImportClient {
  * Imports an exported knowledge-base from the path specified by
  * `--from`, delegating to the worker client.
  *
+ * The path is resolved against the current working directory so
+ * that the daemon -- which may run with a different working
+ * directory -- always receives an absolute path.
+ *
  * @param client - import client to delegate to
  * @param options - parsed CLI options with `from` path
  * @returns the import result with section/document counts

package/dist/src/shared/cli/functions/run-learn.function.d.ts

@@ -50,6 +50,12 @@ export interface LearnClient {
          * via source key when `replace` is `true`.
          */
         sourcePath?: string;
+        /**
+         * Hierarchical level (1-6). Explicitly set via `--level`, or
+         * auto-detected from directory depth. `undefined` means no
+         * level (the engine defaults to 1).
+         */
+        level?: number;
     }): Promise<AddSectionResult>;
 }
 /** Injectable I/O for testing without real stdin. */
@@ -65,6 +71,12 @@ export interface LearnIO {
  * silently skipped. The `-` argument reads content from stdin
  * (consumed only once).
  *
+ * When `options.level` is unset, the level sent for each file is
+ * auto-detected from its depth relative to the target argument
+ * (root = 1, each subdirectory +1, capped at 6). Stdin input has no
+ * directory to derive a level from, so it is sent unset unless
+ * `options.level` is explicit.
+ *
  * @param client - learn client to delegate ingestion to
  * @param options - parsed CLI options whose `args` list targets to
  *   ingest

package/dist/src/shared/cli/index.d.ts

@@ -1,5 +1,7 @@
 export { parseArgs } from './functions/parse-args.function.ts';
 export { formatOutput } from './functions/format-output.function.ts';
+export { formatCommandOutput } from './functions/format-command-output.function.ts';
+export { formatRecfileOutput } from './functions/format-recfile-output.function.ts';
 export { runSearch } from './functions/run-search.function.ts';
 export { runRecall } from './functions/run-recall.function.ts';
 export { runExport } from './functions/run-export.function.ts';
@@ -23,7 +25,8 @@ export { runWorkerRestart } from './functions/run-worker-restart.function.ts';
 export { HELP_TEXT } from './constants/help-text.constant.ts';
 export type { CliOptions, OutputFormat, SearchMode, } from './typings/cli-options.interface.ts';
 export type { LearnResult } from './typings/learn-result.model.ts';
-export type { SearchDisplay, PagedSearchDisplay, } from './typings/search-display.model.ts';
+export type { RecfileFieldEntry, RecfileFieldMap, } from './typings/recfile-field-map.type.ts';
+export type { PagedSearchDisplay, SearchDisplay, } from './typings/search-display.model.ts';
 export type { SearchClient } from './functions/run-search.function.ts';
 export type { RecallClient } from './functions/run-recall.function.ts';
 export type { ExportClient } from './functions/run-export.function.ts';

package/dist/src/shared/cli/typings/cli-options.interface.d.ts

@@ -3,9 +3,11 @@
  *
  * - `'json'` -- machine-readable JSON array
  * - `'text'` -- human-readable numbered list
+ * - `'rec'` -- recfile (GNU recutils style) field records;
+ *   the default format
  * - `'mcp'` -- JSON envelope for MCP protocol consumers
  */
-export type OutputFormat = 'json' | 'text' | 'mcp';
+export type OutputFormat = 'json' | 'text' | 'rec' | 'mcp';
 /**
  * Controls which entity type is returned by a search query.
  *
@@ -24,12 +26,17 @@ export interface CliOptions {
      * Defaults to the current working directory when omitted.
      */
     dbPath?: string;
-    /** Output format for results. Defaults to `'json'`. */
+    /** Output format for results. Defaults to `'rec'`. */
     format: OutputFormat;
     /** When `true`, the user explicitly passed `--format`. */
     formatExplicit?: boolean;
     /** Search mode passed to the worker daemon. Defaults to `'sections'`. */
     mode: SearchMode;
+    /**
+     * Hierarchical level (1-6). Level 1 is broadest scope,
+     * level 6 is narrowest.
+     */
+    level?: number;
     /** Search algorithm: `'lexical'`, `'vector'`, or `'hybrid'`. */
     algo?: string;
     /** Maximum number of results to return. Defaults to 20. */

package/dist/src/shared/cli/typings/db-resolution.interface.d.ts

@@ -0,0 +1,9 @@
+/** Identifies which source resolved the database directory. */
+export type DbSource = 'flag' | 'traversal' | 'env';
+/** Successful database directory resolution result. */
+export interface DbResolution {
+    /** Absolute path to the resolved `.kbdb` directory. */
+    path: string;
+    /** Which source provided the resolution. */
+    source: DbSource;
+}

package/dist/src/shared/cli/typings/recfile-field-map.type.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Mapping entry from an object property path to a recfile
+ * field name.
+ */
+export type RecfileFieldEntry = readonly [field: string, key: string];
+/**
+ * Ordered list of field mappings for a command's recfile
+ * output. Fields are rendered in array order.
+ */
+export type RecfileFieldMap = readonly RecfileFieldEntry[];

package/dist/src/shared/version/constants/version.constant.d.ts

@@ -1,2 +1,2 @@
 /** Current package version, kept in sync with package.json. */
-export declare const VERSION = "0.5.0";
+export declare const VERSION = "0.6.0";

package/dist/src/shared/wasm-codec/functions/decode-option-u8.function.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Decodes an `Option<u8>` from WASM binary output.
+ *
+ * Wire format: `0x00` = None, `0x01 <byte>` = Some.
+ */
+export declare function decodeOptionU8(bytes: Uint8Array, offset: number): {
+    value: number | null;
+    bytesRead: number;
+};

package/dist/src/shared/wasm-codec/functions/decode-section-records.function.d.ts

@@ -63,6 +63,10 @@ export interface SectionRecord {
      * `null` on first creation or non-superseding additions.
      */
     supersedes: string | null;
+    /**
+     * Hierarchical level (1-6). `null` when not set.
+     */
+    level?: number | null;
 }
 /**
  * Decodes a list of `SectionRecord` values from WASM binary output.

package/dist/src/shared/wasm-codec/functions/encode-add-section-params.function.d.ts

@@ -1,48 +1,4 @@
-/**
- * Parameters for adding a new section to the knowledge base.
- *
- * Maps to the Rust `AddSectionParams` struct encoded for the
- * `worker_add_section` WASM export.
- */
-export interface AddSectionInput {
-    /** Semantic content category. */
-    sectionType: 'text' | 'code' | 'image';
-    /** MIME type; required for `code` and `image` section types. */
-    mimeType?: string;
-    /** Raw section content. */
-    content: string;
-    /** Optional section heading. */
-    title?: string | null;
-    /** Optional description summary. */
-    description?: string | null;
-    /** Optional document identifier to attach the section to. */
-    docid?: string | null;
-    /**
-     * Application-level type name for the section (e.g. `'skill'`,
-     * `'fact'`). `null` means no custom type.
-     */
-    typeName?: string | null;
-    /**
-     * Absolute path of the source file being learned. `undefined`
-     * means stdin input or programmatic API call.
-     */
-    sourcePath?: string;
-    /**
-     * ISO 8601 modified time of the source file. `undefined` means
-     * no source file exists.
-     */
-    sourceMtime?: string;
-    /**
-     * User-supplied tags for scoping and filtering. Defaults to
-     * an empty list when not provided.
-     */
-    tags?: string[];
-    /**
-     * When `true`, supersede any existing section with the same
-     * source key. Defaults to `false`.
-     */
-    replace?: boolean;
-}
+import type { AddSectionInput } from '../typings/add-section-input.model.ts';
 /**
  * Encodes `AddSectionInput` as the binary format expected by the
  * `worker_add_section` WASM export.
@@ -58,5 +14,6 @@ export interface AddSectionInput {
  * - `sourceMtime`: `u8` flag + optional `String`
  * - `tags`: `u32` count + each `String`
  * - `replace`: `u8` (0 or 1)
+ * - `level`: `u8` flag + optional `u8` (`Option<u8>`)
  */
 export declare function encodeAddSectionParams(params: AddSectionInput): Uint8Array;

package/dist/src/shared/wasm-codec/functions/encode-update-section-params.function.d.ts

@@ -1,2 +1,11 @@
-import type { AddSectionInput } from './encode-add-section-params.function.ts';
+import type { AddSectionInput } from '../typings/add-section-input.model.ts';
+/**
+ * Encodes parameters for updating an existing section as the
+ * binary format expected by the `worker_update_section` WASM
+ * export.
+ *
+ * Wire format: the target section's `kbid` `String`, followed
+ * by the same `AddSectionInput` encoding used by
+ * {@link encodeAddSectionParams}.
+ */
 export declare function encodeUpdateSectionParams(oldKbid: string, params: AddSectionInput): Uint8Array;

package/dist/src/shared/wasm-codec/index.d.ts

@@ -25,7 +25,7 @@ export { encodeRecallParams } from './functions/encode-recall-params.function.ts
 export { decodeRecallResult } from './functions/decode-recall-result.function.ts';
 export { decodeAddSectionResult } from './functions/decode-add-section-result.function.ts';
 export type { DecodeResult } from './functions/decode-string.function.ts';
-export type { AddSectionInput } from './functions/encode-add-section-params.function.ts';
+export type { AddSectionInput } from './typings/add-section-input.model.ts';
 export type { AddSectionResult, NearDuplicate, } from './functions/decode-add-section-result.function.ts';
 export type { SectionMatch, PagedSearchResult, } from './functions/decode-scored-results.function.ts';
 export type { SectionRecord } from './functions/decode-section-records.function.ts';

package/dist/src/shared/wasm-codec/typings/add-section-input.model.d.ts

@@ -42,4 +42,10 @@ export interface AddSectionInput {
      * source key. Defaults to `false`.
      */
     replace?: boolean;
+    /**
+     * Hierarchical level (1-6). Level 1 is the broadest
+     * scope, level 6 the narrowest. `undefined` means
+     * no explicit level (defaults to 1 in the engine).
+     */
+    level?: number;
 }

package/dist/src/shared/wasm-codec/typings/section-record-trailing.model.d.ts

@@ -33,6 +33,11 @@ export interface SectionRecordTrailing {
      * `null` on first creation or non-superseding additions.
      */
     supersedes: string | null;
+    /**
+     * Hierarchical level (1-6). `null` when not set (defaults
+     * to 1 in the engine).
+     */
+    level: number | null;
     /** Number of bytes consumed from the buffer. */
     bytesRead: number;
 }

package/dist/src/shared/wasm-codec/typings/section-record.model.d.ts

@@ -63,4 +63,9 @@ export interface SectionRecord {
      * `null` on first creation or non-superseding additions.
      */
     supersedes: string | null;
+    /**
+     * Hierarchical level (1-6). `null` when not set (defaults
+     * to 1 in the engine).
+     */
+    level?: number | null;
 }

package/dist/src/shared/worker-client/functions/build-deno-permissions.function.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Deno permission flags for the worker daemon.
+ *
+ * - read: WASM modules, DB files, config
+ * - write: DB files, IPC socket, crash logs, exports
+ * - env: KBDB_LOG_LEVEL, HOME, TMPDIR, XDG_RUNTIME_DIR
+ * - run: not used by daemon itself (CLI needs it to
+ *   spawn the daemon, included for symmetry)
+ * - sys: os.tmpdir(), os.hostname() via node:os compat
+ */
+export declare function buildDenoPermissions(): string[];

package/dist/src/shared/worker-client/functions/read-crash-reason.function.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Reads and clears the crash log written by a worker daemon that
+ * failed to start, returning a human-readable reason.
+ *
+ * @param contextId - the 16-char hex context ID for the daemon
+ * @returns the recorded crash error, or a fallback message when no
+ *   usable crash log is found
+ */
+export declare function readCrashReason(contextId: string): string;

package/dist/src/shared/worker-client/functions/resolve-spawn-script.function.d.ts

@@ -0,0 +1,6 @@
+import type { Runtime } from '../../runtime/typings/runtime.ts';
+/**
+ * Resolves the worker daemon script path from within
+ * the worker-client module.
+ */
+export declare function resolveSpawnScript(runtime: Runtime): string;

package/dist/src/shared/worker-client/functions/spawn-daemon.function.d.ts

@@ -6,6 +6,6 @@ import type { Runtime } from '../../runtime/typings/runtime.ts';
  *   daemon should serve
  * @param runtime - the current JavaScript runtime environment
  * @param workerScript - absolute path to the worker daemon script,
- *   resolved at the entry point by `resolveWorkerScript`
+ *   resolved by `resolveSpawnScript`
  */
 export declare function spawnDaemon(contextPath: string, runtime: Runtime, workerScript?: string): void;

package/dist/src/shared/worker-client/typings/section.model.d.ts

@@ -39,4 +39,9 @@ export interface AddSectionParams {
      * via source key when `replace` is `true`.
      */
     readonly sourcePath?: string;
+    /**
+     * Hierarchical level (1-6). Higher-level sections
+     * (lower number) represent broader scope.
+     */
+    readonly level?: number;
 }

package/dist/src/shared/worker-client/typings/worker-client-options.interface.d.ts

@@ -21,12 +21,6 @@ export interface WorkerClientOptions {
      * appear after spawning. Defaults to 10 000 ms.
      */
     readonly connectTimeoutMs?: number;
-    /**
-     * Absolute path to the worker daemon script. Resolved
-     * once at the entry point and injected here so that
-     * `spawnDaemon` needs no runtime-specific path logic.
-     */
-    readonly workerScript?: string;
     /**
      * Per-request timeout in milliseconds for daemon IPC
      * calls. When a request exceeds this duration, the

package/dist/src/shared/worker-daemon/functions/count-files.function.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Counts files with a given extension inside a directory tree,
+ * including nested subdirectories.
+ *
+ * Returns `0` when `dir` does not exist rather than throwing, so
+ * callers can size dry-run import reports without first checking
+ * directory existence themselves.
+ *
+ * @param dir - directory to search
+ * @param ext - file extension to match, including the leading dot
+ */
+export declare function countFiles(dir: string, ext: string): number;

package/dist/src/shared/worker-daemon/functions/handle-import.function.d.ts

@@ -10,5 +10,7 @@ import type { ImportResult } from '../../worker-client/typings/import-result.mod
  * @param ctx - handler context with WASM modules
  * @param params - `sourcePath` and `dryRun` flag
  * @returns import report with counts and timing
+ * @throws {IpcError} when `sourcePath` is missing, relative, or
+ *   contains a `..` traversal segment
  */
 export declare function handleImport(ctx: HandlerContext, params: Record<string, unknown>): Promise<ImportResult>;

package/dist/src/shared/worker-daemon/functions/handle-read-ops.function.d.ts

@@ -54,5 +54,13 @@ export declare function handleListDocsByType(ctx: HandlerContext, params: Record
 export declare function handleRecall(ctx: HandlerContext, params: Record<string, unknown>): unknown;
 /**
  * Handles the `export` and `exportDb` IPC methods.
+ *
+ * When `targetPath`/`path` is not supplied, defaults to a
+ * `kbdb-export` directory next to the database directory, since
+ * the daemon's own working directory is not meaningful to the
+ * client that issued the request.
+ *
+ * @throws {IpcError} when the resolved target path is relative, or
+ *   contains a `..` traversal segment
  */
 export declare function handleExport(ctx: HandlerContext, params: Record<string, unknown>): unknown;

package/dist/src/shared/worker-daemon/functions/validate-daemon-path.function.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Validates that a daemon-received path is absolute and free of
+ * `..` traversal segments.
+ *
+ * The daemon trusts paths sent by IPC clients to read from and
+ * write to the filesystem. Rejecting relative and traversal paths
+ * here, at the boundary, prevents a malformed or malicious client
+ * from escaping the intended target directory.
+ *
+ * @param path - path received from an IPC request
+ * @returns the same path, unchanged, when valid
+ * @throws {IpcError} with code `-32602` when `path` is not
+ *   absolute, or contains a `..` segment
+ */
+export declare function validateDaemonPath(path: string): string;

package/dist/src/worker.d.ts

@@ -1,8 +1 @@
-/**
- * @module
- *
- * Worker daemon executable for kbdb. Runs as a detached
- * background process that loads WASM modules and serves
- * JSON-RPC 2.0 requests over local IPC.
- */
 export {};

package/dist/wasm/default-embedding/package.json

@@ -2,7 +2,7 @@
   "name": "kbdb-default-embedding",
   "description": "Built-in TF-IDF embedding for kbdb -- compiles to default-embedding.wasm",
   "version": "0.0.1",
-  "license": "ISC",
+  "license": "AGPL-3.0-only",
   "files": [
     "kbdb_default_embedding_bg.wasm",
     "kbdb_default_embedding.js",

package/dist/wasm/fs-database/package.json

@@ -2,7 +2,7 @@
   "name": "kbdb-fs-database",
   "description": "Filesystem storage engine for kbdb -- compiles to fs-database.wasm",
   "version": "0.0.1",
-  "license": "ISC",
+  "license": "AGPL-3.0-only",
   "files": [
     "kbdb_fs_database_bg.wasm",
     "kbdb_fs_database.js",

package/dist/wasm/fs-migration/package.json

@@ -2,7 +2,7 @@
   "name": "kbdb-fs-migration",
   "description": "Database migration engine for kbdb -- compiles to fs-migration.wasm",
   "version": "0.0.1",
-  "license": "ISC",
+  "license": "AGPL-3.0-only",
   "files": [
     "kbdb_fs_migration_bg.wasm",
     "kbdb_fs_migration.js",

package/dist/wasm/kb-worker/package.json

@@ -2,7 +2,7 @@
   "name": "kbdb-worker",
   "description": "Worker orchestration and cache for kbdb -- compiles to kb-worker.wasm",
   "version": "0.0.1",
-  "license": "ISC",
+  "license": "AGPL-3.0-only",
   "files": [
     "kbdb_worker_bg.wasm",
     "kbdb_worker.js",

package/dist/wasm/query-parser/package.json

@@ -2,7 +2,7 @@
   "name": "kbdb-query-parser",
   "description": "Query processing and tokenization for kbdb -- compiles to query-parser.wasm",
   "version": "0.0.1",
-  "license": "ISC",
+  "license": "AGPL-3.0-only",
   "files": [
     "kbdb_query_parser_bg.wasm",
     "kbdb_query_parser.js",

package/dist/worker.d.ts

@@ -1,8 +1 @@
-/**
- * @module
- *
- * Worker daemon executable for kbdb. Runs as a detached
- * background process that loads WASM modules and serves
- * JSON-RPC 2.0 requests over local IPC.
- */
 export {};