agentic-knowledge-mcp 0.0.1

package/packages/core/dist/config/loader.js

@@ -0,0 +1,236 @@
+/**
+ * Configuration loading and validation
+ */
+import { promises as fs } from "node:fs";
+import * as fsSync from "node:fs";
+import { load } from "js-yaml";
+import { KnowledgeError, ErrorType } from "../types.js";
+import { validateTemplate } from "../templates/processor.js";
+/**
+ * Load configuration from a YAML file with strict template validation
+ * @param configPath - Path to the configuration file
+ * @returns Parsed configuration object
+ */
+export async function loadConfig(configPath) {
+  try {
+    const content = await fs.readFile(configPath, "utf-8");
+    const parsed = load(content);
+    if (!validateConfig(parsed)) {
+      throw new KnowledgeError(
+        ErrorType.CONFIG_INVALID,
+        "Configuration file contains invalid structure",
+        { configPath, parsed },
+      );
+    }
+    // Validate templates strictly at load time
+    validateAllTemplates(parsed, configPath);
+    return parsed;
+  } catch (error) {
+    if (error instanceof KnowledgeError) {
+      throw error;
+    }
+    if (error.code === "ENOENT") {
+      throw new KnowledgeError(
+        ErrorType.CONFIG_NOT_FOUND,
+        `Configuration file not found: ${configPath}`,
+        { configPath },
+      );
+    }
+    throw new KnowledgeError(
+      ErrorType.YAML_PARSE_ERROR,
+      `Failed to parse YAML configuration: ${error.message}`,
+      { configPath, error },
+    );
+  }
+}
+/**
+ * Synchronous version of loadConfig with strict template validation
+ * @param configPath - Path to the configuration file
+ * @returns Parsed configuration object
+ */
+export function loadConfigSync(configPath) {
+  try {
+    const content = fsSync.readFileSync(configPath, "utf-8");
+    const parsed = load(content);
+    if (!validateConfig(parsed)) {
+      throw new KnowledgeError(
+        ErrorType.CONFIG_INVALID,
+        "Configuration file contains invalid structure",
+        { configPath, parsed },
+      );
+    }
+    // Validate templates strictly at load time
+    validateAllTemplates(parsed, configPath);
+    return parsed;
+  } catch (error) {
+    if (error instanceof KnowledgeError) {
+      throw error;
+    }
+    if (error.code === "ENOENT") {
+      throw new KnowledgeError(
+        ErrorType.CONFIG_NOT_FOUND,
+        `Configuration file not found: ${configPath}`,
+        { configPath },
+      );
+    }
+    throw new KnowledgeError(
+      ErrorType.YAML_PARSE_ERROR,
+      `Failed to parse YAML configuration: ${error.message}`,
+      { configPath, error },
+    );
+  }
+}
+/**
+ * Validate all templates in configuration at load time
+ * @param config - Configuration object to validate
+ * @param configPath - Path to config file for error context
+ */
+function validateAllTemplates(config, configPath) {
+  // Validate global template if present
+  if (config.template) {
+    try {
+      validateTemplate(config.template);
+    } catch (error) {
+      throw new KnowledgeError(
+        ErrorType.TEMPLATE_ERROR,
+        `Invalid global template in configuration: ${error.message}`,
+        { configPath, template: config.template, originalError: error },
+      );
+    }
+  }
+  // Validate each docset template if present
+  for (const docset of config.docsets) {
+    if (docset.template) {
+      try {
+        validateTemplate(docset.template);
+      } catch (error) {
+        throw new KnowledgeError(
+          ErrorType.TEMPLATE_ERROR,
+          `Invalid template for docset '${docset.id}': ${error.message}`,
+          {
+            configPath,
+            docsetId: docset.id,
+            template: docset.template,
+            originalError: error,
+          },
+        );
+      }
+    }
+  }
+}
+/**
+ * Validate a configuration object
+ * @param config - Configuration to validate
+ * @returns True if valid, false if invalid
+ */
+export function validateConfig(config) {
+  if (!config || typeof config !== "object") {
+    return false;
+  }
+  const obj = config;
+  // Check required fields
+  if (typeof obj["version"] !== "string") {
+    return false;
+  }
+  if (!Array.isArray(obj["docsets"])) {
+    return false;
+  }
+  // Validate each docset
+  for (const docset of obj["docsets"]) {
+    if (!validateDocset(docset)) {
+      return false;
+    }
+  }
+  // Optional template field
+  if (obj["template"] !== undefined && typeof obj["template"] !== "string") {
+    return false;
+  }
+  return true;
+}
+/**
+ * Validate a docset configuration object
+ * @param docset - Docset to validate
+ * @returns True if valid, false if invalid
+ */
+function validateDocset(docset) {
+  if (!docset || typeof docset !== "object") {
+    return false;
+  }
+  const obj = docset;
+  // Check required fields
+  if (typeof obj["id"] !== "string" || obj["id"].toString().trim() === "") {
+    return false;
+  }
+  if (typeof obj["name"] !== "string" || obj["name"].toString().trim() === "") {
+    return false;
+  }
+  // local_path is optional if web_sources are provided
+  const hasWebSources =
+    Array.isArray(obj["web_sources"]) && obj["web_sources"].length > 0;
+  const hasLocalPath =
+    typeof obj["local_path"] === "string" &&
+    obj["local_path"].toString().trim() !== "";
+  if (!hasWebSources && !hasLocalPath) {
+    return false; // Must have either web_sources or local_path
+  }
+  if (
+    obj["local_path"] !== undefined &&
+    typeof obj["local_path"] !== "string"
+  ) {
+    return false; // If local_path is provided, it must be a valid string
+  }
+  // Check optional fields
+  if (
+    obj["description"] !== undefined &&
+    typeof obj["description"] !== "string"
+  ) {
+    return false;
+  }
+  if (obj["template"] !== undefined && typeof obj["template"] !== "string") {
+    return false;
+  }
+  // Check optional web_sources field
+  if (obj["web_sources"] !== undefined) {
+    if (!Array.isArray(obj["web_sources"])) {
+      return false;
+    }
+    // Validate each web source
+    for (const webSource of obj["web_sources"]) {
+      if (!validateWebSource(webSource)) {
+        return false;
+      }
+    }
+  }
+  return true;
+}
+/**
+ * Validate a web source configuration object
+ * @param webSource - Web source to validate
+ * @returns True if valid, false if invalid
+ */
+function validateWebSource(webSource) {
+  if (!webSource || typeof webSource !== "object") {
+    return false;
+  }
+  const obj = webSource;
+  // Check required fields
+  if (typeof obj["url"] !== "string" || obj["url"].toString().trim() === "") {
+    return false;
+  }
+  if (typeof obj["type"] !== "string") {
+    return false;
+  }
+  // Validate type is one of the supported values
+  const validTypes = ["git_repo", "documentation_site", "api_documentation"];
+  if (!validTypes.includes(obj["type"])) {
+    return false;
+  }
+  // Check optional options field
+  if (
+    obj["options"] !== undefined &&
+    (typeof obj["options"] !== "object" || obj["options"] === null)
+  ) {
+    return false;
+  }
+  return true;
+}

package/packages/core/dist/config/manager.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Configuration management with read and write capabilities
+ */
+import type { KnowledgeConfig } from "../types.js";
+/**
+ * Central configuration manager for all config file operations
+ */
+export declare class ConfigManager {
+    private configCache;
+    private readonly CONFIG_CACHE_TTL;
+    /**
+     * Load configuration with caching
+     * @param startDir - Directory to start searching from (defaults to cwd)
+     * @returns Configuration and path
+     */
+    loadConfig(startDir?: string): Promise<{
+        config: KnowledgeConfig;
+        configPath: string;
+    }>;
+    /**
+     * Load configuration from specific file path
+     * @param configPath - Path to configuration file
+     * @returns Parsed configuration
+     */
+    loadConfigFromPath(configPath: string): Promise<KnowledgeConfig>;
+    /**
+     * Save configuration to file
+     * @param config - Configuration to save
+     * @param configPath - Path to save to (optional, uses cached path if available)
+     */
+    saveConfig(config: KnowledgeConfig, configPath?: string): Promise<void>;
+    /**
+     * Update paths for a specific docset with discovered files
+     * @param docsetId - ID of docset to update
+     * @param discoveredPaths - Array of file paths that were discovered
+     * @returns Updated configuration
+     */
+    updateDocsetPaths(docsetId: string, discoveredPaths: string[]): Promise<KnowledgeConfig>;
+    /**
+     * Find configuration file path
+     * @param startDir - Directory to start searching from
+     * @returns Path to config file or null if not found
+     */
+    findConfigPath(startDir?: string): Promise<string | null>;
+    /**
+     * Clear configuration cache (useful for testing)
+     */
+    clearCache(): void;
+    /**
+     * Check if configuration exists
+     * @param startDir - Directory to start searching from
+     * @returns True if config file exists
+     */
+    configExists(startDir?: string): Promise<boolean>;
+}

package/packages/core/dist/config/manager.js

@@ -0,0 +1,180 @@
+/**
+ * Configuration management with read and write capabilities
+ */
+import { promises as fs } from "node:fs";
+import { load, dump } from "js-yaml";
+import { KnowledgeError, ErrorType } from "../types.js";
+import { validateConfig } from "./loader.js";
+import { findConfigPath } from "./discovery.js";
+/**
+ * Central configuration manager for all config file operations
+ */
+export class ConfigManager {
+  configCache = null;
+  CONFIG_CACHE_TTL = 60000; // 1 minute cache
+  /**
+   * Load configuration with caching
+   * @param startDir - Directory to start searching from (defaults to cwd)
+   * @returns Configuration and path
+   */
+  async loadConfig(startDir) {
+    const now = Date.now();
+    // Return cached config if still valid
+    if (
+      this.configCache &&
+      now - this.configCache.loadTime < this.CONFIG_CACHE_TTL
+    ) {
+      return {
+        config: this.configCache.config,
+        configPath: this.configCache.configPath,
+      };
+    }
+    // Find and load fresh config
+    const configPath = await findConfigPath(startDir);
+    if (!configPath) {
+      throw new KnowledgeError(
+        ErrorType.CONFIG_NOT_FOUND,
+        "No configuration file found. Please ensure .knowledge/config.yaml exists in your project.",
+        { searchPath: startDir || process.cwd() },
+      );
+    }
+    const config = await this.loadConfigFromPath(configPath);
+    // Cache the result
+    this.configCache = {
+      config,
+      configPath,
+      loadTime: now,
+    };
+    return { config, configPath };
+  }
+  /**
+   * Load configuration from specific file path
+   * @param configPath - Path to configuration file
+   * @returns Parsed configuration
+   */
+  async loadConfigFromPath(configPath) {
+    try {
+      const content = await fs.readFile(configPath, "utf-8");
+      const parsed = load(content);
+      if (!validateConfig(parsed)) {
+        throw new KnowledgeError(
+          ErrorType.CONFIG_INVALID,
+          "Configuration file contains invalid structure",
+          { configPath, parsed },
+        );
+      }
+      return parsed;
+    } catch (error) {
+      if (error instanceof KnowledgeError) {
+        throw error;
+      }
+      if (error.code === "ENOENT") {
+        throw new KnowledgeError(
+          ErrorType.CONFIG_NOT_FOUND,
+          `Configuration file not found: ${configPath}`,
+          { configPath },
+        );
+      }
+      throw new KnowledgeError(
+        ErrorType.CONFIG_INVALID,
+        `Failed to parse configuration file: ${error instanceof Error ? error.message : String(error)}`,
+        { configPath, originalError: error },
+      );
+    }
+  }
+  /**
+   * Save configuration to file
+   * @param config - Configuration to save
+   * @param configPath - Path to save to (optional, uses cached path if available)
+   */
+  async saveConfig(config, configPath) {
+    const targetPath = configPath || this.configCache?.configPath;
+    if (!targetPath) {
+      throw new KnowledgeError(
+        ErrorType.CONFIG_INVALID,
+        "No configuration path available. Load config first or provide explicit path.",
+        { configPath },
+      );
+    }
+    // Validate config before saving
+    if (!validateConfig(config)) {
+      throw new KnowledgeError(
+        ErrorType.CONFIG_INVALID,
+        "Cannot save invalid configuration",
+        { config },
+      );
+    }
+    try {
+      const yamlContent = dump(config, {
+        indent: 2,
+        lineWidth: 120,
+        noRefs: true,
+      });
+      await fs.writeFile(targetPath, yamlContent, "utf-8");
+      // Invalidate cache since config changed
+      this.configCache = null;
+    } catch (error) {
+      throw new KnowledgeError(
+        ErrorType.CONFIG_INVALID,
+        `Failed to save configuration: ${error instanceof Error ? error.message : String(error)}`,
+        { configPath: targetPath, originalError: error },
+      );
+    }
+  }
+  /**
+   * Update paths for a specific docset with discovered files
+   * @param docsetId - ID of docset to update
+   * @param discoveredPaths - Array of file paths that were discovered
+   * @returns Updated configuration
+   */
+  async updateDocsetPaths(docsetId, discoveredPaths) {
+    const { config } = await this.loadConfig();
+    // Find the docset to update
+    const docset = config.docsets.find((d) => d.id === docsetId);
+    if (!docset) {
+      throw new KnowledgeError(
+        ErrorType.CONFIG_INVALID,
+        `Docset '${docsetId}' not found in configuration`,
+        { docsetId, availableDocsets: config.docsets.map((d) => d.id) },
+      );
+    }
+    // Update web sources with discovered paths
+    if (docset.web_sources) {
+      for (const webSource of docset.web_sources) {
+        if (webSource.type === "git_repo") {
+          // Add or update the paths in options
+          if (!webSource.options) {
+            webSource.options = {};
+          }
+          webSource.options.paths = discoveredPaths;
+        }
+      }
+    }
+    // Save updated configuration
+    await this.saveConfig(config);
+    return config;
+  }
+  /**
+   * Find configuration file path
+   * @param startDir - Directory to start searching from
+   * @returns Path to config file or null if not found
+   */
+  async findConfigPath(startDir) {
+    return await findConfigPath(startDir);
+  }
+  /**
+   * Clear configuration cache (useful for testing)
+   */
+  clearCache() {
+    this.configCache = null;
+  }
+  /**
+   * Check if configuration exists
+   * @param startDir - Directory to start searching from
+   * @returns True if config file exists
+   */
+  async configExists(startDir) {
+    const path = await this.findConfigPath(startDir);
+    return path !== null;
+  }
+}

package/packages/core/dist/content/api-documentation-loader.d.ts

@@ -0,0 +1,26 @@
+/**
+ * API documentation content loader (STUB - not implemented yet)
+ */
+import { ContentLoader, type LoadResult } from "./loader.js";
+import { WebSourceConfig } from "../types.js";
+/**
+ * Content loader for API documentation (STUB IMPLEMENTATION)
+ */
+export declare class ApiDocumentationLoader extends ContentLoader {
+  /**
+   * Check if this loader can handle the given web source type
+   */
+  canHandle(webSource: WebSourceConfig): boolean;
+  /**
+   * Validate the web source configuration
+   */
+  validateConfig(webSource: WebSourceConfig): true | string;
+  /**
+   * Load content from API documentation (NOT IMPLEMENTED)
+   */
+  load(webSource: WebSourceConfig, targetPath: string): Promise<LoadResult>;
+  /**
+   * Get content identifier (NOT IMPLEMENTED)
+   */
+  getContentId(webSource: WebSourceConfig): Promise<string>;
+}

package/packages/core/dist/content/api-documentation-loader.js

@@ -0,0 +1,45 @@
+/**
+ * API documentation content loader (STUB - not implemented yet)
+ */
+import { ContentLoader } from "./loader.js";
+import { WebSourceType, KnowledgeError, ErrorType } from "../types.js";
+/**
+ * Content loader for API documentation (STUB IMPLEMENTATION)
+ */
+export class ApiDocumentationLoader extends ContentLoader {
+  /**
+   * Check if this loader can handle the given web source type
+   */
+  canHandle(webSource) {
+    return webSource.type === WebSourceType.API_DOCUMENTATION;
+  }
+  /**
+   * Validate the web source configuration
+   */
+  validateConfig(webSource) {
+    if (!webSource.url) {
+      return "API documentation URL is required";
+    }
+    return true;
+  }
+  /**
+   * Load content from API documentation (NOT IMPLEMENTED)
+   */
+  async load(webSource, targetPath) {
+    throw new KnowledgeError(
+      ErrorType.NOT_IMPLEMENTED,
+      "API documentation loading is not yet implemented. Use git_repo type for repositories with API documentation.",
+      { webSource: webSource.url, targetPath },
+    );
+  }
+  /**
+   * Get content identifier (NOT IMPLEMENTED)
+   */
+  async getContentId(webSource) {
+    throw new KnowledgeError(
+      ErrorType.NOT_IMPLEMENTED,
+      "API documentation content ID generation is not yet implemented.",
+      { webSource: webSource.url },
+    );
+  }
+}

package/packages/core/dist/content/content-processor.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Content processor for converting and preparing content
+ */
+/**
+ * Options for content processing
+ */
+export interface ProcessingOptions {
+  /** Add frontmatter with source metadata */
+  addFrontmatter?: boolean;
+  /** Source URL to include in frontmatter */
+  sourceUrl?: string;
+  /** Additional metadata to include */
+  metadata?: Record<string, unknown>;
+}
+/**
+ * Content processor for converting and preparing documentation content
+ */
+export declare class ContentProcessor {
+  /**
+   * Process a file, optionally adding frontmatter metadata
+   * @param filePath - Path to the file to process
+   * @param options - Processing options
+   */
+  processFile(filePath: string, options?: ProcessingOptions): Promise<void>;
+  /**
+   * Add frontmatter to markdown content
+   * @param content - Original markdown content
+   * @param options - Processing options with metadata
+   * @returns Content with frontmatter added
+   */
+  private addFrontmatter;
+  /**
+   * Simple object to YAML conversion for frontmatter
+   * @param obj - Object to convert
+   * @returns YAML string
+   */
+  private objectToYaml;
+  /**
+   * Check if a file should be processed based on its extension
+   * @param filePath - Path to check
+   * @returns True if file should be processed
+   */
+  shouldProcess(filePath: string): boolean;
+}

package/packages/core/dist/content/content-processor.js

@@ -0,0 +1,81 @@
+/**
+ * Content processor for converting and preparing content
+ */
+import { promises as fs } from "node:fs";
+import * as path from "node:path";
+/**
+ * Content processor for converting and preparing documentation content
+ */
+export class ContentProcessor {
+  /**
+   * Process a file, optionally adding frontmatter metadata
+   * @param filePath - Path to the file to process
+   * @param options - Processing options
+   */
+  async processFile(filePath, options = {}) {
+    const content = await fs.readFile(filePath, "utf-8");
+    const extension = path.extname(filePath).toLowerCase();
+    // For markdown files, optionally add frontmatter
+    if (extension === ".md" || extension === ".mdx") {
+      if (options.addFrontmatter) {
+        const processedContent = this.addFrontmatter(content, options);
+        await fs.writeFile(filePath, processedContent, "utf-8");
+      }
+    }
+    // For other file types, we keep them as-is for now
+    // Future: HTML to Markdown conversion would go here
+  }
+  /**
+   * Add frontmatter to markdown content
+   * @param content - Original markdown content
+   * @param options - Processing options with metadata
+   * @returns Content with frontmatter added
+   */
+  addFrontmatter(content, options) {
+    // Check if frontmatter already exists
+    if (content.startsWith("---\n")) {
+      return content; // Don't modify existing frontmatter
+    }
+    const frontmatter = {};
+    if (options.sourceUrl) {
+      frontmatter["source_url"] = options.sourceUrl;
+    }
+    if (options.metadata) {
+      Object.assign(frontmatter, options.metadata);
+    }
+    // Add processed timestamp
+    frontmatter["processed_at"] = new Date().toISOString();
+    // Convert to YAML frontmatter
+    const yamlFrontmatter = this.objectToYaml(frontmatter);
+    return `---\n${yamlFrontmatter}---\n\n${content}`;
+  }
+  /**
+   * Simple object to YAML conversion for frontmatter
+   * @param obj - Object to convert
+   * @returns YAML string
+   */
+  objectToYaml(obj) {
+    return (
+      Object.entries(obj)
+        .map(([key, value]) => {
+          if (typeof value === "string") {
+            // Quote strings that contain special characters
+            const needsQuotes = /[:\n\r\t"']/.test(value);
+            return `${key}: ${needsQuotes ? `"${value.replace(/"/g, '\\"')}"` : value}`;
+          }
+          return `${key}: ${value}`;
+        })
+        .join("\n") + "\n"
+    );
+  }
+  /**
+   * Check if a file should be processed based on its extension
+   * @param filePath - Path to check
+   * @returns True if file should be processed
+   */
+  shouldProcess(filePath) {
+    const extension = path.extname(filePath).toLowerCase();
+    const processableExtensions = [".md", ".mdx", ".txt", ".rst"];
+    return processableExtensions.includes(extension);
+  }
+}

package/packages/core/dist/content/documentation-site-loader.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Documentation site content loader (STUB - not implemented yet)
+ */
+import { ContentLoader, type LoadResult } from "./loader.js";
+import { WebSourceConfig } from "../types.js";
+/**
+ * Content loader for documentation websites (STUB IMPLEMENTATION)
+ */
+export declare class DocumentationSiteLoader extends ContentLoader {
+  /**
+   * Check if this loader can handle the given web source type
+   */
+  canHandle(webSource: WebSourceConfig): boolean;
+  /**
+   * Validate the web source configuration
+   */
+  validateConfig(webSource: WebSourceConfig): true | string;
+  /**
+   * Load content from a documentation site (NOT IMPLEMENTED)
+   */
+  load(webSource: WebSourceConfig, targetPath: string): Promise<LoadResult>;
+  /**
+   * Get content identifier (NOT IMPLEMENTED)
+   */
+  getContentId(webSource: WebSourceConfig): Promise<string>;
+}