@dikolab/kbdb 0.3.1 → 0.4.0

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

@@ -1,299 +0,0 @@
-import { VERSION } from '../../version/index.ts';
-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 { parseArgs } from './parse-args.function.ts';
-import { errorToMessage } from './error-to-message.function.ts';
-import { dispatchCommand } from './dispatch-command.function.ts';
-import type { DispatchClient } from './dispatch-command.function.ts';
-import {
-   generateHelp,
-   isKnownCommand,
-} from './generate-help.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 async function runCli(
-   argv: string[],
-   deps: CliDeps,
-): Promise<CommandResult> {
-   const options = parseArgs(argv);
-
-   if (options.command === 'help' || !options.command) {
-      const helpCommand = options.args[0];
-      const helpSubcommand = options.args[1];
-      const helpText = generateHelp(helpCommand, helpSubcommand);
-      if (helpCommand && !isKnownCommand(helpCommand)) {
-         return { output: helpText, exitCode: 1 };
-      }
-      return { output: helpText, exitCode: 0 };
-   }
-
-   if (options.command === 'version') {
-      return { output: VERSION, exitCode: 0 };
-   }
-
-   if (options.command === 'init' || options.command === 'db-init') {
-      return handleInit(options, deps);
-   }
-
-   if (options.command === 'mcp') {
-      return handleMcp(options, deps);
-   }
-
-   if (
-      options.command === 'migrate' ||
-      options.command === 'db-migrate'
-   ) {
-      return handleMigrate(options, deps);
-   }
-
-   return handleDataCommand(options, deps);
-}
-
-function handleInit(options: CliOptions, deps: CliDeps): CommandResult {
-   const result = deps.runInit(options);
-   if (result.ok) {
-      return {
-         output: result.targetPath,
-         exitCode: 0,
-      };
-   }
-   return {
-      error: `error: ${result.errorMessage ?? 'init failed'}`,
-      exitCode: 1,
-   };
-}
-
-async function handleMcp(
-   options: CliOptions,
-   deps: CliDeps,
-): Promise<CommandResult> {
-   const rawDbPath = options.dbPath ?? process.env['KBDB_DIR'];
-   if (!rawDbPath) {
-      return {
-         error: 'error: --db or KBDB_DIR required in MCP mode',
-         exitCode: 1,
-      };
-   }
-   const dbDir = deps.findDb(rawDbPath);
-   if (!dbDir) {
-      return {
-         error: `error: no .kbdb database found at ${rawDbPath}`,
-         exitCode: 1,
-      };
-   }
-
-   let client: DisconnectableClient;
-   try {
-      client = await deps.createWorkerClient({
-         contextPath: dbDir,
-      });
-   } catch (err) {
-      return {
-         error: `error: ${errorToMessage(err)}`,
-         exitCode: 1,
-      };
-   }
-
-   try {
-      const gateResult = await versionGate(client, dbDir);
-      if (gateResult) return gateResult;
-
-      if (deps.startMcpServer) {
-         await deps.startMcpServer(dbDir);
-      }
-      return { exitCode: 0 };
-   } catch (err) {
-      return {
-         error: `error: mcp failed: ${errorToMessage(err)}`,
-         exitCode: 1,
-      };
-   } finally {
-      client.disconnect();
-   }
-}
-
-async function handleMigrate(
-   options: CliOptions,
-   deps: CliDeps,
-): Promise<CommandResult> {
-   const dbDir = deps.findDb(options.dbPath);
-   if (!dbDir) {
-      const basePath = options.dbPath ?? process.cwd();
-      return {
-         error: `error: no .kbdb database found at ${basePath}`,
-         exitCode: 1,
-      };
-   }
-
-   let client: DisconnectableClient;
-   try {
-      client = await deps.createWorkerClient({
-         contextPath: dbDir,
-      });
-   } catch (err) {
-      return {
-         error: `error: ${errorToMessage(err)}`,
-         exitCode: 1,
-      };
-   }
-
-   try {
-      const versionStatus = await client.checkVersion(dbDir);
-
-      if (versionStatus.status === 'too_new') {
-         return {
-            error:
-               `error: database version` +
-               ` ${versionStatus.currentVersion.toString()}` +
-               ` is newer than kbdb version` +
-               ` ${versionStatus.requiredVersion.toString()}` +
-               ` -- upgrade kbdb`,
-            exitCode: 1,
-         };
-      }
-
-      if (versionStatus.status === 'needs_migration') {
-         const migrateResult = await client.migrateDatabase(dbDir);
-         return {
-            output: JSON.stringify(migrateResult, null, 2),
-            exitCode: 0,
-         };
-      }
-
-      return { output: 'already up to date', exitCode: 0 };
-   } catch (err) {
-      return {
-         error: `error: migrate failed: ${errorToMessage(err)}`,
-         exitCode: 1,
-      };
-   } finally {
-      client.disconnect();
-   }
-}
-
-async function handleDataCommand(
-   options: CliOptions,
-   deps: CliDeps,
-): Promise<CommandResult> {
-   let dbDir = deps.findDb(options.dbPath);
-
-   if (!dbDir) {
-      const basePath = options.dbPath ?? process.cwd();
-
-      if (!deps.isStdinTty()) {
-         return {
-            error:
-               `error: no .kbdb database found at ${basePath}` +
-               ' -- run `kbdb --init` to create one',
-            exitCode: 1,
-         };
-      }
-
-      const answer = await deps.promptUser(
-         `No .kbdb database found. Create one in ${basePath}? [y/N] `,
-      );
-
-      if (answer.toLowerCase() !== 'y') {
-         return {
-            error: 'aborted: no database created',
-            exitCode: 1,
-         };
-      }
-
-      const initResult = deps.runInit(options);
-      if (!initResult.ok) {
-         return {
-            error: `error: ${initResult.errorMessage ?? 'init failed'}`,
-            exitCode: 1,
-         };
-      }
-      dbDir = initResult.targetPath;
-   }
-
-   let client: DisconnectableClient;
-   try {
-      client = await deps.createWorkerClient({
-         contextPath: dbDir,
-      });
-   } catch (err) {
-      return {
-         error: `error: ${errorToMessage(err)}`,
-         exitCode: 1,
-      };
-   }
-
-   try {
-      const gateResult = await versionGate(client, dbDir);
-      if (gateResult) return gateResult;
-
-      return await dispatchCommand(client, options);
-   } finally {
-      client.disconnect();
-   }
-}
-
-async function versionGate(
-   client: DisconnectableClient,
-   dbDir: string,
-): Promise<CommandResult | null> {
-   const versionStatus = await client.checkVersion(dbDir);
-
-   if (versionStatus.status === 'needs_migration') {
-      return {
-         error:
-            'error: database needs migration' +
-            ' -- run `kbdb --migrate`',
-         exitCode: 1,
-      };
-   }
-
-   if (versionStatus.status === 'too_new') {
-      return {
-         error:
-            `error: database version` +
-            ` ${versionStatus.currentVersion.toString()}` +
-            ` is newer than kbdb version` +
-            ` ${versionStatus.requiredVersion.toString()}` +
-            ` -- upgrade kbdb`,
-         exitCode: 1,
-      };
-   }
-
-   return null;
-}

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

@@ -1,47 +0,0 @@
-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 async function runContent(
-   client: ContentClient,
-   options: CliOptions,
-): Promise<ContentResult> {
-   return client.content(options.args);
-}

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

@@ -1,44 +0,0 @@
-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 function runDbInit(
-   options: CliOptions,
-   runInitFn: RunInitFn,
-): CommandResult {
-   const result = runInitFn(options);
-   if (result.ok) {
-      return {
-         output: JSON.stringify(
-            { path: result.targetPath, created: true },
-            null,
-            2,
-         ),
-         exitCode: 0,
-      };
-   }
-   return {
-      error: result.errorMessage ?? 'init failed',
-      exitCode: 1,
-   };
-}

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

@@ -1,40 +0,0 @@
-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 async function runDbMigrate(
-   client: DbMigrateClient,
-   options: CliOptions,
-): Promise<MigrateResult> {
-   const dbPath = options.dbPath ?? process.cwd();
-   return client.migrateDatabase(dbPath);
-}

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

@@ -1,40 +0,0 @@
-import type { CliOptions } from '../typings/cli-options.interface.ts';
-import type { ExportResult } from '../../worker-client/typings/export-result.model.ts';
-
-/**
- * Minimal client interface required by `runExport`.
- *
- * Decouples the CLI function from the concrete `WorkerClient`
- * implementation, making it straightforward to test with mocks.
- */
-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`
-    * @returns export report with the resolved path and file counts
-    */
-   export(params: { path?: string }): Promise<ExportResult>;
-}
-
-/**
- * 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/`).
- *
- * @param client - export client to delegate to
- * @param options - parsed CLI options whose first positional
- *   argument, if present, is the target directory path
- * @returns the export result containing the resolved path and file
- *   counts
- */
-export async function runExport(
-   client: ExportClient,
-   options: CliOptions,
-): Promise<ExportResult> {
-   const path = options.args[0];
-   return client.export({ path });
-}

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

@@ -1,51 +0,0 @@
-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;
-   /**
-    * Number of sections whose `source_path` file no longer
-    * contains their heading text (advisory; not auto-removed).
-    * Absent on older daemon versions.
-    */
-   readonly stale_sources?: 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 async function runGc(
-   client: GcClient,
-   _options: CliOptions,
-): Promise<GcResult> {
-   return client.gc();
-}

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

@@ -1,93 +0,0 @@
-import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
-import { join, resolve } from 'node:path';
-import type { CliOptions } from '../typings/cli-options.interface.ts';
-import { installDefaultSkills } from './install-default-skills.function.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;
-}
-
-const DB_FORMAT_VERSION = 1;
-
-const CATALOG_TOML = `version = ${DB_FORMAT_VERSION.toString()}
-section_count = 0
-document_count = 0
-created_at = 0
-updated_at = 0
-checksum = ""
-`;
-
-const WORKER_TOML = '# kbdb worker configuration\n';
-
-const GITIGNORE = [
-   '# kbdb binary indexes (auto-generated)',
-   'corpus.bin',
-   'inverted.idx',
-   'positional.idx',
-   '',
-].join('\n');
-
-/**
- * Creates the `.kbdb` directory scaffold directly on disk.
- *
- * This mirrors the Rust `init_directory` in
- * `engine/crates/fs-database/src/scaffold.rs` and does not
- * require a running worker daemon.
- */
-function createScaffold(dbDir: string): void {
-   mkdirSync(dbDir, { recursive: true });
-   mkdirSync(join(dbDir, 'sections'));
-   mkdirSync(join(dbDir, 'documents'));
-   writeFileSync(join(dbDir, 'catalog.toml'), CATALOG_TOML);
-   writeFileSync(join(dbDir, 'corpus.bin'), '');
-   writeFileSync(join(dbDir, 'inverted.idx'), '');
-   writeFileSync(join(dbDir, 'positional.idx'), '');
-   writeFileSync(join(dbDir, 'worker.toml'), WORKER_TOML);
-   writeFileSync(join(dbDir, '.gitignore'), GITIGNORE);
-}
-
-/**
- * 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 function runInit(options: CliOptions): InitResult {
-   const basePath = options.dbPath
-      ? resolve(options.dbPath)
-      : process.cwd();
-   const dbDir = join(basePath, '.kbdb');
-
-   try {
-      if (existsSync(dbDir)) {
-         return {
-            ok: false,
-            targetPath: dbDir,
-            errorMessage: `database directory already exists: ${dbDir}`,
-         };
-      }
-      createScaffold(dbDir);
-      installDefaultSkills(dbDir);
-      return { ok: true, targetPath: dbDir };
-   } catch (err: unknown) {
-      const errorMessage =
-         err instanceof Error ? err.message : String(err);
-      return { ok: false, targetPath: dbDir, errorMessage };
-   }
-}