@dikolab/kbdb 0.1.0

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

@@ -0,0 +1,133 @@
+import type { CliOptions } from '../typings/cli-options.interface.ts';
+import {
+   DEFAULT_FORMAT,
+   DEFAULT_LIMIT,
+   DEFAULT_MODE,
+} from '../constants/defaults.constant.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 function parseArgs(argv: string[]): CliOptions {
+   const options: CliOptions = {
+      command: '',
+      format: DEFAULT_FORMAT,
+      mode: DEFAULT_MODE,
+      limit: DEFAULT_LIMIT,
+      args: [],
+   };
+
+   let i = 0;
+   while (i < argv.length) {
+      const arg = argv[i];
+      switch (arg) {
+         case '--help':
+         case '-h':
+            if (options.command) {
+               options.args.unshift(options.command);
+               options.command = 'help';
+            } else {
+               options.command = 'help';
+            }
+            return options;
+         case '--version':
+         case '-v':
+            options.command = 'version';
+            return options;
+         case '--init':
+            // eslint-disable-next-line no-console
+            console.error(
+               'warning: --init is deprecated,' + ' use "kbdb db init"',
+            );
+            options.command = 'init';
+            break;
+         case '--migrate':
+            // eslint-disable-next-line no-console
+            console.error(
+               'warning: --migrate is deprecated,' +
+                  ' use "kbdb db migrate"',
+            );
+            options.command = 'migrate';
+            break;
+         case '--db':
+            options.dbPath = argv[++i];
+            break;
+         case '--format':
+         case '-f':
+            options.format = (argv[++i] ??
+               DEFAULT_FORMAT) as CliOptions['format'];
+            break;
+         case '--mode':
+         case '-m':
+            options.mode = (argv[++i] ??
+               DEFAULT_MODE) as CliOptions['mode'];
+            break;
+         case '--limit':
+         case '-l':
+            options.limit =
+               parseInt(argv[++i] ?? '', 10) || DEFAULT_LIMIT;
+            break;
+         case '--title':
+            options.title = argv[++i];
+            break;
+         case '--description':
+            options.description = argv[++i];
+            break;
+         case '--docid':
+            options.docid = argv[++i];
+            break;
+         case '--name':
+            options.name = argv[++i];
+            break;
+         case '--persona':
+            options.persona = argv[++i];
+            break;
+         case '--body':
+            options.body = argv[++i];
+            break;
+         case '--skills':
+            options.skills = (argv[++i] ?? '').split(',');
+            break;
+         case '--content':
+         case '-c':
+            options.content = true;
+            break;
+         default:
+            if (!options.command) {
+               options.command = arg;
+            } else if (
+               !options.args.length &&
+               (options.command === 'db' ||
+                  options.command === 'skill' ||
+                  options.command === 'agent')
+            ) {
+               options.command = `${options.command}-${arg}`;
+            } else {
+               options.args.push(arg);
+            }
+      }
+      i++;
+   }
+
+   return options;
+}

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

@@ -0,0 +1,36 @@
+import { createInterface } from 'node:readline';
+
+/** 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 async function promptUser(
+   question: string,
+   io?: PromptIO,
+): Promise<string> {
+   const ask = io?.ask ?? askReadline;
+   const answer = await ask(question);
+   return answer.trim();
+}
+
+function askReadline(question: string): Promise<string> {
+   return new Promise<string>((resolve) => {
+      const rl = createInterface({
+         input: process.stdin,
+         output: process.stdout,
+      });
+      rl.question(question, (answer) => {
+         rl.close();
+         resolve(answer);
+      });
+   });
+}

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

@@ -0,0 +1,114 @@
+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 async function runAgentCreate(
+   client: AgentCreateClient,
+   options: CliOptions,
+): Promise<CommandResult> {
+   const name = options.name;
+   if (!name) {
+      return { error: '--name is required', exitCode: 1 };
+   }
+   const persona = options.persona;
+   if (!persona) {
+      return { error: '--persona is required', exitCode: 1 };
+   }
+   const skills = options.skills ?? [];
+
+   if (skills.length > 0) {
+      const sections = await client.readSections(skills);
+      const found = new Set(sections.map((s) => s.kbid));
+      const missing = skills.filter((k) => !found.has(k));
+      if (missing.length > 0) {
+         return {
+            error: `skill not found: ${missing.join(', ')}`,
+            exitCode: 1,
+         };
+      }
+   }
+
+   const metadata = JSON.stringify({
+      name,
+      description: options.description ?? '',
+      persona,
+   });
+
+   const metaResult = await client.addSection({
+      sectionType: 'text',
+      content: metadata,
+      title: name,
+      description: options.description,
+   });
+
+   const allKbids = [metaResult.kbid, ...skills];
+   const docid = await client.groupSections(name, allKbids, 'agent');
+
+   return {
+      output: JSON.stringify(
+         { docid, name, skillCount: skills.length },
+         null,
+         2,
+      ),
+      exitCode: 0,
+   };
+}

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

@@ -0,0 +1,47 @@
+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 async function runAgentDelete(
+   client: AgentDeleteClient,
+   options: CliOptions,
+): Promise<CommandResult> {
+   const docid = options.args[0];
+   if (!docid) {
+      return { error: 'docid is required', exitCode: 1 };
+   }
+   await client.removeGrouping(docid);
+   return {
+      output: JSON.stringify({ docid, removed: true }, null, 2),
+      exitCode: 0,
+   };
+}

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

@@ -0,0 +1,166 @@
+import type { CliOptions } from '../typings/cli-options.interface.ts';
+import type { CommandResult } from '../typings/command-result.model.ts';
+
+/** A document section reference as returned by `retrieveDocument`. */
+interface DocumentSection {
+   /** Knowledge-base identifier of the section. */
+   readonly kbid: string;
+   /** Zero-based position of the section within the document. */
+   readonly position: number;
+}
+
+/** A document record as returned by `retrieveDocument`. */
+interface AgentDocument {
+   /** Unique document identifier. */
+   readonly docid: string;
+   /** Human-readable document title used as agent name fallback. */
+   readonly title: string;
+   /** Ordered list of section references. */
+   readonly sections: DocumentSection[];
+}
+
+/** 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[]>;
+}
+
+/**
+ * Reads agent metadata from the first section's JSON content.
+ * Falls back to `fallbackName` when the section is absent or the
+ * content cannot be parsed.
+ */
+async function readAgentMeta(
+   client: AgentGetClient,
+   metaKbid: string,
+   fallbackName: string,
+): Promise<{ name: string; description: string; persona: string }> {
+   const sections = await client.readSections([metaKbid]);
+   const first = sections.at(0);
+   if (!first) {
+      return { name: fallbackName, description: '', persona: '' };
+   }
+   try {
+      const meta = JSON.parse(first.content) as Record<string, unknown>;
+      return {
+         name:
+            typeof meta['name'] === 'string'
+               ? meta['name']
+               : fallbackName,
+         description:
+            typeof meta['description'] === 'string'
+               ? meta['description']
+               : '',
+         persona:
+            typeof meta['persona'] === 'string' ? meta['persona'] : '',
+      };
+   } catch {
+      return { name: fallbackName, description: '', persona: '' };
+   }
+}
+
+/**
+ * Resolves skill names by reading each skill section's JSON content.
+ * Returns `null` for any reference whose section no longer exists
+ * (dangling reference).
+ */
+async function resolveSkills(
+   client: AgentGetClient,
+   skillRefs: DocumentSection[],
+): Promise<{ kbid: string; name: string | null; position: number }[]> {
+   if (skillRefs.length === 0) {
+      return [];
+   }
+   const kbids = skillRefs.map((r) => r.kbid);
+   const sections = await client.readSections(kbids);
+   const sectionMap = new Map(sections.map((s) => [s.kbid, s]));
+   return skillRefs.map((ref) => {
+      const sec = sectionMap.get(ref.kbid);
+      if (!sec) {
+         return { kbid: ref.kbid, name: null, position: ref.position };
+      }
+      try {
+         const parsed = JSON.parse(sec.content) as Record<
+            string,
+            unknown
+         >;
+         const skillName =
+            typeof parsed['name'] === 'string' ? parsed['name'] : null;
+         return {
+            kbid: ref.kbid,
+            name: skillName,
+            position: ref.position,
+         };
+      } catch {
+         return { kbid: ref.kbid, name: null, position: ref.position };
+      }
+   });
+}
+
+/**
+ * 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 async function runAgentGet(
+   client: AgentGetClient,
+   options: CliOptions,
+): Promise<CommandResult> {
+   const docid = options.args[0];
+   if (!docid) {
+      return { error: 'docid is required', exitCode: 1 };
+   }
+
+   const doc = (await client.retrieveDocument(docid)) as AgentDocument;
+   const metaKbid = doc.sections[0]?.kbid;
+   const skillRefs = doc.sections.slice(1);
+
+   const { name, description, persona } = metaKbid
+      ? await readAgentMeta(client, metaKbid, doc.title)
+      : { name: doc.title, description: '', persona: '' };
+
+   const skills = await resolveSkills(client, skillRefs);
+
+   return {
+      output: JSON.stringify(
+         { docid, name, description, persona, skills },
+         null,
+         2,
+      ),
+      exitCode: 0,
+   };
+}

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

@@ -0,0 +1,58 @@
+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 async function runAgentList(
+   client: AgentListClient,
+   _options: CliOptions,
+): Promise<CommandResult> {
+   const docs = await client.listDocumentsByType('agent');
+   const items = docs.map((d) => ({
+      docid: d.docid,
+      name: d.title,
+      skillCount: Math.max(0, d.sections.length - 1),
+   }));
+   return {
+      output: JSON.stringify(items, null, 2),
+      exitCode: 0,
+   };
+}

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

@@ -0,0 +1,78 @@
+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 async function runCheck(
+   client: CheckClient,
+   _options: CliOptions,
+): Promise<IntegrityCheckResult> {
+   return client.integrityCheck();
+}