@dikolab/kbdb 0.1.0

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

@@ -0,0 +1,13 @@
+/**
+ * Resolves the absolute path to the `.kbdb` database directory
+ * under the given base path (or the current working directory).
+ *
+ * Unlike `ensureDb`, this function is purely read-only: it never
+ * creates the directory. Returns `null` when the `.kbdb` directory
+ * does not exist.
+ *
+ * @param dbPath - optional path to the knowledge-base root directory
+ * @returns absolute path to the `.kbdb` directory, or `null` when
+ *   it does not exist
+ */
+export declare function findDb(dbPath?: string): string | null;

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

@@ -0,0 +1,15 @@
+import type { OutputFormat } from '../typings/cli-options.interface.ts';
+import type { SearchDisplay } from '../typings/search-display.model.ts';
+/**
+ * Serialises an array of search results into the requested output
+ * format string.
+ *
+ * - `'json'` -- pretty-printed JSON array
+ * - `'text'` -- numbered human-readable list
+ * - `'mcp'` -- JSON envelope compatible with MCP protocol consumers
+ *
+ * @param results - ranked search results to format
+ * @param format - target output format
+ * @returns formatted string ready for stdout
+ */
+export declare function formatOutput(results: SearchDisplay[], format: OutputFormat): string;

package/dist/src/shared/cli/functions/generate-help.function.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Returns `true` when `cmd` is a recognised command name.
+ *
+ * Accepts both simple top-level names (`'learn'`, `'db'`)
+ * and the hyphenated compound form produced by `parseArgs`
+ * when a group + subcommand precedes `--help`
+ * (e.g. `'db-init'`, `'skill-learn'`).
+ */
+export declare function isKnownCommand(cmd: string): boolean;
+/**
+ * Generates contextual help text for the `kbdb` CLI.
+ *
+ * Three levels of detail are produced depending on
+ * how many command tokens are supplied:
+ *
+ * - No arguments: global help listing all commands.
+ * - `command` only: command-level help. When `command`
+ *   is a hyphenated compound (`'db-init'`), it is split
+ *   into group + subcommand automatically.  Group
+ *   commands show a subcommand listing; leaf commands
+ *   show detailed help; unknown commands show an error
+ *   prefix followed by global help.
+ * - `command` + `subcommand`: detailed help for that
+ *   specific subcommand (falls back to group help when
+ *   the subcommand is not recognised).
+ *
+ * @param command - optional top-level command token,
+ *   or a hyphenated compound such as `'db-init'`
+ * @param subcommand - optional subcommand token
+ */
+export declare function generateHelp(command?: string, subcommand?: string): string;

package/dist/src/shared/cli/functions/is-stdin-tty.function.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Returns `true` when stdin is an interactive terminal.
+ *
+ * @param stdin - readable stream to check (defaults to
+ *   `process.stdin`)
+ */
+export declare function isStdinTty(stdin?: NodeJS.ReadStream): boolean;

package/dist/src/shared/cli/functions/parse-args.function.d.ts

@@ -0,0 +1,25 @@
+import type { CliOptions } from '../typings/cli-options.interface.ts';
+/**
+ * Parses a raw argument vector into a structured `CliOptions` object.
+ *
+ * Recognises `--help` / `-h` and `--version` / `-v` as early-exit
+ * flags that set the command and return immediately. All other flags
+ * consume the next token as their value. The first non-flag token
+ * becomes the command; subsequent non-flag tokens become `args`.
+ *
+ * Compound commands are supported: when the first positional token is
+ * a group name (`db`, `skill`, or `agent`), the next positional token
+ * is joined with a hyphen to form the compound command
+ * (e.g. `db init` → `'db-init'`).
+ *
+ * Context-aware `--help`: when `--help` or `-h` appears after a
+ * command has been set, the existing command is moved to `args[0]`
+ * and the command is set to `'help'`, enabling per-command help.
+ *
+ * Deprecated flags `--init` and `--migrate` emit a warning to stderr
+ * before setting the corresponding command.
+ *
+ * @param argv - argument strings (typically `process.argv.slice(2)`)
+ * @returns fully populated `CliOptions` with defaults applied
+ */
+export declare function parseArgs(argv: string[]): CliOptions;

package/dist/src/shared/cli/functions/prompt-user.function.d.ts

@@ -0,0 +1,13 @@
+/** Injectable I/O for testing without real stdin. */
+export interface PromptIO {
+    ask: (question: string) => Promise<string>;
+}
+/**
+ * Prompts the user on stdin (TTY only) and returns the
+ * trimmed reply.
+ *
+ * @param question - the prompt text to display
+ * @param io - injectable I/O (defaults to readline on
+ *   process.stdin/stdout)
+ */
+export declare function promptUser(question: string, io?: PromptIO): Promise<string>;

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

@@ -0,0 +1,58 @@
+import type { CliOptions } from '../typings/cli-options.interface.ts';
+import type { CommandResult } from '../typings/command-result.model.ts';
+import type { AddSectionResult } from '../../worker-client/typings/add-section-result.model.ts';
+/**
+ * Minimal client interface required by `runAgentCreate`.
+ *
+ * Decouples the CLI function from the concrete `WorkerClient`
+ * implementation, making it straightforward to test with mocks.
+ */
+export interface AgentCreateClient {
+    /**
+     * Ingests a content section into the knowledge base.
+     *
+     * @param params - section type label, raw content, and optional
+     *   metadata
+     * @returns result object containing the assigned knowledge-base
+     *   identifier
+     */
+    addSection(params: {
+        readonly sectionType: string;
+        readonly content: string;
+        readonly title?: string;
+        readonly description?: string;
+    }): Promise<AddSectionResult>;
+    /**
+     * Groups a set of sections under a named document.
+     *
+     * @param title - human-readable document title
+     * @param kbids - identifiers of the sections to group
+     * @param docType - application-level document type tag; omit or
+     *   pass an empty string for untagged documents
+     * @returns the assigned document identifier
+     */
+    groupSections(title: string, kbids: string[], docType?: string): Promise<string>;
+    /**
+     * Retrieves one or more sections by their identifiers.
+     *
+     * @param kbids - list of knowledge-base identifiers to fetch
+     * @returns sections found; missing kbids are omitted from the result
+     */
+    readSections(kbids: string[]): Promise<{
+        kbid: string;
+    }[]>;
+}
+/**
+ * Creates a new agent in the knowledge base.
+ *
+ * Validates `--name` and `--persona` options, verifies that all
+ * referenced skill kbids exist, stores agent metadata as a JSON
+ * section, and groups all sections under a single document.
+ *
+ * @param client - agent create client to delegate operations to
+ * @param options - parsed CLI options providing `name`, `persona`,
+ *   optional `description`, and optional `skills` kbid list
+ * @returns a `CommandResult` with serialised creation info or an
+ *   error message and a non-zero exit code
+ */
+export declare function runAgentCreate(client: AgentCreateClient, options: CliOptions): Promise<CommandResult>;

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

@@ -0,0 +1,32 @@
+import type { CliOptions } from '../typings/cli-options.interface.ts';
+import type { CommandResult } from '../typings/command-result.model.ts';
+/**
+ * Minimal client interface required by `runAgentDelete`.
+ *
+ * Decouples the CLI function from the concrete `WorkerClient`
+ * implementation, making it straightforward to test with mocks.
+ */
+export interface AgentDeleteClient {
+    /**
+     * Removes the document grouping for the given document.
+     *
+     * The sections themselves are not deleted; only the grouping
+     * record is removed.
+     *
+     * @param docid - identifier of the document grouping to remove
+     */
+    removeGrouping(docid: string): Promise<void>;
+}
+/**
+ * Deletes an agent from the knowledge base.
+ *
+ * Removes the document grouping identified by `options.args[0]`.
+ * Skill sections referenced by the agent are not deleted; only
+ * the grouping record is removed.
+ *
+ * @param client - agent delete client to delegate removal to
+ * @param options - parsed CLI options; `args[0]` must be the docid
+ * @returns a `CommandResult` confirming removal or an error message
+ *   with a non-zero exit code
+ */
+export declare function runAgentDelete(client: AgentDeleteClient, options: CliOptions): Promise<CommandResult>;

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

@@ -0,0 +1,46 @@
+import type { CliOptions } from '../typings/cli-options.interface.ts';
+import type { CommandResult } from '../typings/command-result.model.ts';
+/** A section record as returned by `readSections`. */
+interface SectionRecord {
+    /** Knowledge-base identifier of the section. */
+    readonly kbid: string;
+    /** Raw text content stored in the section. */
+    readonly content: string;
+}
+/**
+ * Minimal client interface required by `runAgentGet`.
+ *
+ * Decouples the CLI function from the concrete `WorkerClient`
+ * implementation, making it straightforward to test with mocks.
+ */
+export interface AgentGetClient {
+    /**
+     * Retrieves a full document record including its ordered sections.
+     *
+     * @param docid - identifier of the document to retrieve
+     * @returns the document record
+     */
+    retrieveDocument(docid: string): Promise<unknown>;
+    /**
+     * Retrieves one or more sections by their identifiers.
+     *
+     * @param kbids - list of knowledge-base identifiers to fetch
+     * @returns sections found; missing kbids are omitted from the result
+     */
+    readSections(kbids: string[]): Promise<SectionRecord[]>;
+}
+/**
+ * Retrieves a full agent definition from the knowledge base.
+ *
+ * Reads the agent document identified by `options.args[0]`, extracts
+ * metadata (name, description, persona) from the first section, and
+ * resolves skill names from the remaining sections. Dangling skill
+ * references appear with `name: null`.
+ *
+ * @param client - agent get client to delegate retrieval to
+ * @param options - parsed CLI options; `args[0]` must be the docid
+ * @returns a `CommandResult` with serialised agent definition or an
+ *   error message and a non-zero exit code
+ */
+export declare function runAgentGet(client: AgentGetClient, options: CliOptions): Promise<CommandResult>;
+export {};

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

@@ -0,0 +1,45 @@
+import type { CliOptions } from '../typings/cli-options.interface.ts';
+import type { CommandResult } from '../typings/command-result.model.ts';
+/** A document summary as returned by `listDocumentsByType`. */
+interface DocumentSummary {
+    /** Unique document identifier. */
+    readonly docid: string;
+    /** Human-readable document title used as the agent name. */
+    readonly title: string;
+    /** Ordered list of section references for this document. */
+    readonly sections: readonly {
+        kbid: string;
+        position: number;
+    }[];
+}
+/**
+ * Minimal client interface required by `runAgentList`.
+ *
+ * Decouples the CLI function from the concrete `WorkerClient`
+ * implementation, making it straightforward to test with mocks.
+ */
+export interface AgentListClient {
+    /**
+     * Retrieves all documents whose type name matches the given string.
+     *
+     * @param docType - the application-level document type to filter by
+     * @returns all document summaries with a matching type name
+     */
+    listDocumentsByType(docType: string): Promise<DocumentSummary[]>;
+}
+/**
+ * Lists all agents stored in the knowledge base.
+ *
+ * Retrieves all documents with `doc_type: 'agent'` and returns a
+ * summary list. The `skillCount` for each agent is
+ * `Math.max(0, sections.length - 1)` because the first section
+ * always holds the agent's metadata JSON rather than a skill
+ * reference.
+ *
+ * @param client - agent list client to delegate retrieval to
+ * @param _options - parsed CLI options (unused; reserved for future
+ *   filtering flags)
+ * @returns a `CommandResult` with serialised agent summary list
+ */
+export declare function runAgentList(client: AgentListClient, _options: CliOptions): Promise<CommandResult>;
+export {};

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

@@ -0,0 +1,64 @@
+import type { CliOptions } from '../typings/cli-options.interface.ts';
+/** A single integrity error found during a database check. */
+interface IntegrityError {
+    /**
+     * The category of integrity violation detected.
+     *
+     * - `'checksum_mismatch'` -- stored content does not match its hash
+     * - `'orphan_section'` -- section not referenced by any document
+     * - `'orphan_document'` -- document references no existing sections
+     * - `'broken_reference'` -- a marker references a non-existent entity
+     * - `'type_mismatch'` -- stored MIME type conflicts with content
+     * - `'circular_reference'` -- marker chain contains a cycle
+     */
+    readonly type: 'checksum_mismatch' | 'orphan_section' | 'orphan_document' | 'broken_reference' | 'type_mismatch' | 'circular_reference';
+    /** Identifier of the entity (kbid or docid) that has the issue. */
+    readonly entity: string;
+    /** Human-readable description of the specific problem. */
+    readonly detail: string;
+}
+/**
+ * Integrity check report returned by the daemon.
+ */
+interface IntegrityCheckResult {
+    /** `true` when all checks passed and no errors were found. */
+    readonly ok: boolean;
+    /** All integrity errors found; empty when `ok` is `true`. */
+    readonly errors: IntegrityError[];
+    /** Total number of sections examined. */
+    readonly sections_checked: number;
+    /** Total number of documents examined. */
+    readonly documents_checked: number;
+    /** Total number of marker references checked. */
+    readonly references_checked: number;
+    /** Time taken to complete the check, in milliseconds. */
+    readonly elapsed_ms: number;
+}
+/**
+ * Minimal client interface required by `runCheck`.
+ *
+ * Decouples the CLI function from the concrete `WorkerClient`
+ * implementation, making it straightforward to test with mocks.
+ */
+export interface CheckClient {
+    /**
+     * Runs an integrity check on the knowledge-base database.
+     *
+     * @returns a report of all issues found; `ok` is `true` when
+     *   no errors were detected
+     */
+    integrityCheck(): Promise<IntegrityCheckResult>;
+}
+/**
+ * Runs an integrity check on the database and returns the report.
+ *
+ * Delegates to `client.integrityCheck()`. The caller is responsible
+ * for printing the result to stdout and setting the process exit code
+ * based on `result.ok`.
+ *
+ * @param client - check client to delegate to
+ * @param _options - parsed CLI options (unused; reserved for future flags)
+ * @returns the integrity check report from the daemon
+ */
+export declare function runCheck(client: CheckClient, _options: CliOptions): Promise<IntegrityCheckResult>;
+export {};

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

@@ -0,0 +1,39 @@
+import type { CliOptions } from '../typings/cli-options.interface.ts';
+import type { CommandResult } from '../typings/command-result.model.ts';
+import type { InitResult } from './run-init.function.ts';
+import type { VersionStatus } from '../../worker-client/typings/version-status.model.ts';
+import type { MigrateResult } from '../../worker-client/typings/migrate-result.model.ts';
+import type { DispatchClient } from './dispatch-command.function.ts';
+export interface DisconnectableClient extends DispatchClient {
+    checkVersion(targetPath: string): Promise<VersionStatus>;
+    migrateDatabase(targetPath: string): Promise<MigrateResult>;
+    disconnect(): void;
+}
+/**
+ * Injectable dependencies for the CLI orchestrator.
+ *
+ * Every external side-effect is injected so the function
+ * is fully testable without touching process globals,
+ * filesystem, or network.
+ */
+export interface CliDeps {
+    isStdinTty: () => boolean;
+    promptUser: (question: string) => Promise<string>;
+    createWorkerClient: (opts: {
+        contextPath: string;
+    }) => Promise<DisconnectableClient>;
+    findDb: (basePath?: string) => string | null;
+    runInit: (options: CliOptions) => InitResult;
+    startMcpServer?: (contextPath: string) => Promise<void>;
+}
+/**
+ * Full CLI orchestrator extracted from `src/cli.ts`.
+ *
+ * Parses arguments, routes to the appropriate sub-flow
+ * (help, version, init, mcp, migrate, data commands), and
+ * returns a `CommandResult` without touching process globals.
+ *
+ * @param argv - raw CLI arguments (typically `process.argv.slice(2)`)
+ * @param deps - injectable dependencies
+ */
+export declare function runCli(argv: string[], deps: CliDeps): Promise<CommandResult>;

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

@@ -0,0 +1,40 @@
+import type { CliOptions } from '../typings/cli-options.interface.ts';
+/** Result returned by content composition. */
+interface ContentResult {
+    /** MIME type of the composed output, always `'text/markdown'`. */
+    readonly type: 'text/markdown';
+    /** The composed Markdown string. */
+    readonly data: string;
+    /** Character count of `data` (not byte count). */
+    readonly total: number;
+}
+/**
+ * Minimal client interface required by `runContent`.
+ *
+ * Decouples the CLI function from the concrete `WorkerClient`
+ * implementation, making it straightforward to test with mocks.
+ */
+export interface ContentClient {
+    /**
+     * Composes a rendered Markdown document from one or more kbid
+     * or docid identifiers.
+     *
+     * @param ids - list of kbid or docid identifiers (may be mixed)
+     * @returns composed Markdown result with character count
+     */
+    content(ids: string[]): Promise<ContentResult>;
+}
+/**
+ * Composes and returns a rendered Markdown document from the
+ * identifiers listed in `options.args`.
+ *
+ * Delegates to `client.content(ids)`. The caller is responsible for
+ * writing the result to stdout.
+ *
+ * @param client - content client to delegate composition to
+ * @param options - parsed CLI options whose `args` list the kbid or
+ *   docid identifiers to compose
+ * @returns the composed content result from the daemon
+ */
+export declare function runContent(client: ContentClient, options: CliOptions): Promise<ContentResult>;
+export {};

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

@@ -0,0 +1,23 @@
+import type { CliOptions } from '../typings/cli-options.interface.ts';
+import type { CommandResult } from '../typings/command-result.model.ts';
+import type { InitResult } from './run-init.function.ts';
+/**
+ * Callable signature for the init operation injected into
+ * `runDbInit`.
+ */
+export type RunInitFn = (options: CliOptions) => InitResult;
+/**
+ * Executes the `db init` compound command by delegating to the
+ * provided `runInit` function and mapping the result to a
+ * `CommandResult`.
+ *
+ * Accepts `runInit` as an injectable parameter so the function
+ * can be tested without touching the filesystem.
+ *
+ * @param options - parsed CLI options (forwarded to `runInitFn`)
+ * @param runInitFn - function that performs the actual
+ *   initialisation
+ * @returns a `CommandResult` with JSON output on success or an
+ *   error message on failure
+ */
+export declare function runDbInit(options: CliOptions, runInitFn: RunInitFn): CommandResult;

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

@@ -0,0 +1,32 @@
+import type { CliOptions } from '../typings/cli-options.interface.ts';
+import type { MigrateResult } from '../../worker-client/typings/migrate-result.model.ts';
+/**
+ * Minimal client interface required by `runDbMigrate`.
+ *
+ * Intentionally narrower than `MigrateClient` from
+ * `run-migrate.function.ts` — this variant skips the version
+ * check and unconditionally runs migrations. Callers that need
+ * version-aware migration should use `runMigrate` instead.
+ */
+export interface DbMigrateClient {
+    /**
+     * Runs all pending database migrations.
+     *
+     * @param targetPath - absolute path to the `.kbdb` database root
+     */
+    migrateDatabase(targetPath: string): Promise<MigrateResult>;
+}
+/**
+ * Runs database migrations unconditionally via `client.migrateDatabase`.
+ *
+ * Resolves the target path from `options.dbPath` when provided,
+ * falling back to `process.cwd()`. Does not perform a version
+ * compatibility check before migrating — use `runMigrate` for
+ * version-aware migration flows.
+ *
+ * @param client - database migration client to delegate to
+ * @param options - parsed CLI options supplying the optional
+ *   `dbPath`
+ * @returns the migration report returned by the daemon
+ */
+export declare function runDbMigrate(client: DbMigrateClient, options: CliOptions): Promise<MigrateResult>;

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

@@ -0,0 +1,38 @@
+import type { CliOptions } from '../typings/cli-options.interface.ts';
+/**
+ * Garbage collection report returned by the daemon.
+ */
+interface GcResult {
+    /** Number of unreferenced sections removed. */
+    readonly removed_sections: number;
+    /** Total bytes freed by removing unreferenced sections. */
+    readonly removed_bytes: number;
+    /** Time taken to complete garbage collection, in milliseconds. */
+    readonly elapsed_ms: number;
+}
+/**
+ * Minimal client interface required by `runGc`.
+ *
+ * Decouples the CLI function from the concrete `WorkerClient`
+ * implementation, making it straightforward to test with mocks.
+ */
+export interface GcClient {
+    /**
+     * Removes unreferenced sections from the database.
+     *
+     * @returns a report of sections removed and bytes freed
+     */
+    gc(): Promise<GcResult>;
+}
+/**
+ * Runs garbage collection on the database and returns the report.
+ *
+ * Delegates to `client.gc()`. The caller is responsible for printing
+ * the result to stdout.
+ *
+ * @param client - gc client to delegate to
+ * @param _options - parsed CLI options (unused; reserved for future flags)
+ * @returns the garbage collection report from the daemon
+ */
+export declare function runGc(client: GcClient, _options: CliOptions): Promise<GcResult>;
+export {};

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

@@ -0,0 +1,27 @@
+import type { CliOptions } from '../typings/cli-options.interface.ts';
+/**
+ * Result returned by `runInit` describing whether the directory was
+ * successfully initialised.
+ */
+export interface InitResult {
+    /** `true` when the database directory was created successfully. */
+    readonly ok: boolean;
+    /** Absolute path to the directory that was (or should have been) initialised. */
+    readonly targetPath: string;
+    /**
+     * Human-readable error message when `ok` is `false`.
+     * `undefined` when `ok` is `true`.
+     */
+    readonly errorMessage?: string;
+}
+/**
+ * Initialises a new `.kbdb` database directory.
+ *
+ * Creates the full scaffold directly on disk without requiring a
+ * running worker daemon. Resolves the target path from
+ * `options.dbPath` or `process.cwd()`.
+ *
+ * @param options - parsed CLI options supplying the optional `dbPath`
+ * @returns init result indicating success or failure
+ */
+export declare function runInit(options: CliOptions): InitResult;

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

@@ -0,0 +1,46 @@
+import type { CliOptions } from '../typings/cli-options.interface.ts';
+import type { LearnResult } from '../typings/learn-result.model.ts';
+/**
+ * Minimal client interface required by `runLearn`.
+ *
+ * Decouples the CLI function from the concrete `WorkerClient`
+ * implementation, making it straightforward to test with mocks.
+ */
+export interface LearnClient {
+    /**
+     * Ingests a content section into the knowledge base.
+     *
+     * @param params - section type label and raw text content
+     * @returns result object containing the knowledge-base identifier
+     *   assigned to the section
+     */
+    addSection(params: {
+        sectionType: string;
+        content: string;
+        title?: string;
+        description?: string;
+        docid?: string;
+    }): Promise<{
+        kbid: string;
+    }>;
+}
+/** Injectable I/O for testing without real stdin. */
+export interface LearnIO {
+    readStdin: () => Promise<string>;
+}
+/**
+ * Ingests one or more files or directories listed in `options.args`
+ * into the knowledge base via the provided client.
+ *
+ * Each argument is resolved to a set of supported files. Unsupported
+ * extensions, dotfiles, dot-directories, and non-existent paths are
+ * silently skipped. The `-` argument reads content from stdin
+ * (consumed only once).
+ *
+ * @param client - learn client to delegate ingestion to
+ * @param options - parsed CLI options whose `args` list targets to
+ *   ingest
+ * @param io - injectable I/O (defaults to reading process.stdin)
+ * @returns one `LearnResult` per file successfully ingested
+ */
+export declare function runLearn(client: LearnClient, options: CliOptions, io?: LearnIO): Promise<LearnResult[]>;