@dikolab/kbdb 0.3.1 → 0.4.0

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

@@ -1,36 +0,0 @@
-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/resolve-skill-names.function.ts

@@ -1,43 +0,0 @@
-import type {
-   AgentGetClient,
-   AgentDocumentSection,
-   AgentSectionRecord,
-} from '../typings/agent-get-client.interface.ts';
-
-/**
- * Resolves skill names by reading each skill section's JSON content.
- *
- * Returns `null` for any reference whose section no longer exists
- * (dangling reference) or whose content cannot be parsed.
- *
- * @param client - client used to fetch section records
- * @param skillRefs - ordered section references to resolve
- * @returns list of resolved skill entries with name and position
- */
-export async function resolveSkillNames(
-   client: AgentGetClient,
-   skillRefs: AgentDocumentSection[],
-): Promise<{ kbid: string; name: string | null; position: number }[]> {
-   if (skillRefs.length === 0) return [];
-   const kbids = skillRefs.map((r) => r.kbid);
-   const sections: AgentSectionRecord[] =
-      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 name =
-            typeof parsed['name'] === 'string' ? parsed['name'] : null;
-         return { kbid: ref.kbid, name, position: ref.position };
-      } catch {
-         return { kbid: ref.kbid, name: null, position: ref.position };
-      }
-   });
-}

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

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

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

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

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

@@ -1,159 +0,0 @@
-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;
-}
-
-/**
- * A single entry in the divergent-content map.
- * Groups kbids under a common source key.
- */
-interface DivergentContentEntry {
-   /** Source key that has multiple divergent content versions. */
-   readonly sourceKey: string;
-   /** Kbids of sections sharing this source key but with different content. */
-   readonly kbids: 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;
-   /**
-    * Sections that share a source key but have divergent content.
-    * Each entry groups the kbids under a common source key.
-    * Empty when no divergent content is found.
-    */
-   readonly divergent_content: DivergentContentEntry[];
-}
-
-/** Raw daemon response from `integrityCheck`. */
-interface RawIntegrityCheckResult {
-   /** `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;
-   /**
-    * Encoded divergent-content map.
-    *
-    * Format: `sk1:kbid1,kbid2;sk2:kbid3,kbid4`
-    *
-    * Each semicolon-separated segment is a source key followed by
-    * a colon and a comma-separated list of kbids. Absent when no
-    * divergent content exists.
-    */
-   readonly divergent_content?: string;
-}
-
-/**
- * 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<RawIntegrityCheckResult>;
-}
-
-/**
- * Parses the encoded `divergent_content` string from the daemon
- * into a structured array.
- *
- * Input format: `sk1:kbid1,kbid2;sk2:kbid3,kbid4`
- *
- * @param encoded - raw encoded string, or empty / absent
- * @returns structured entries grouped by source key
- */
-function parseDivergentContent(
-   encoded: string | undefined,
-): DivergentContentEntry[] {
-   if (!encoded) return [];
-   return encoded
-      .split(';')
-      .filter((segment) => segment.includes(':'))
-      .map((segment) => {
-         const colonIdx = segment.indexOf(':');
-         const sourceKey = segment.slice(0, colonIdx);
-         const kbids = segment
-            .slice(colonIdx + 1)
-            .split(',')
-            .filter((k) => k.length > 0);
-         return { sourceKey, kbids };
-      })
-      .filter((entry) => entry.kbids.length > 0);
-}
-
-/**
- * Runs an integrity check on the database and returns the report.
- *
- * Delegates to `client.integrityCheck()`, then parses the encoded
- * `divergent_content` field into structured form. 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 with parsed `divergent_content`
- */
-export async function runCheck(
-   client: CheckClient,
-   _options: CliOptions,
-): Promise<IntegrityCheckResult> {
-   const raw = await client.integrityCheck();
-   return {
-      ok: raw.ok,
-      errors: raw.errors,
-      sections_checked: raw.sections_checked,
-      documents_checked: raw.documents_checked,
-      references_checked: raw.references_checked,
-      elapsed_ms: raw.elapsed_ms,
-      divergent_content: parseDivergentContent(raw.divergent_content),
-   };
-}