@dikolab/kbdb 0.1.0

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

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

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

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

@@ -0,0 +1,40 @@
+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-gc.function.ts

@@ -0,0 +1,45 @@
+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 async function runGc(
+   client: GcClient,
+   _options: CliOptions,
+): Promise<GcResult> {
+   return client.gc();
+}

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

@@ -0,0 +1,91 @@
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+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;
+}
+
+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);
+      return { ok: true, targetPath: dbDir };
+   } catch (err: unknown) {
+      const errorMessage =
+         err instanceof Error ? err.message : String(err);
+      return { ok: false, targetPath: dbDir, errorMessage };
+   }
+}