agentic-knowledge-mcp 0.0.1

package/packages/cli/dist/commands/status.js

@@ -0,0 +1,268 @@
+/**
+ * Status command - show status of web sources
+ */
+import { Command } from "commander";
+import chalk from "chalk";
+import { promises as fs } from "node:fs";
+import * as path from "node:path";
+import {
+  findConfigPathSync,
+  loadConfigSync,
+  calculateLocalPath,
+} from "@codemcp/knowledge-core";
+export const statusCommand = new Command("status")
+  .description("Show status of web sources for docsets")
+  .option("-c, --config <path>", "Path to configuration file")
+  .option("-v, --verbose", "Show detailed status information", false)
+  .action(async (options) => {
+    try {
+      console.log(chalk.blue("📊 Agentic Knowledge Status\n"));
+      // Find and load configuration
+      const configPath = options.config || findConfigPathSync(process.cwd());
+      if (!configPath) {
+        throw new Error(
+          "No configuration file found. Run this command from a directory with .knowledge/config.yaml",
+        );
+      }
+      console.log(chalk.gray(`📄 Config: ${configPath}`));
+      const config = loadConfigSync(configPath);
+      // Find docsets with web sources
+      const webDocsets = config.docsets.filter(
+        (d) => d.web_sources && d.web_sources.length > 0,
+      );
+      if (webDocsets.length === 0) {
+        console.log(chalk.yellow("\n⚠️  No docsets with web sources found."));
+        // Show all docsets for reference
+        if (config.docsets.length > 0) {
+          console.log(chalk.gray("\nAvailable docsets (local only):"));
+          for (const docset of config.docsets) {
+            console.log(chalk.gray(`  • ${docset.id} - ${docset.name}`));
+          }
+        }
+        return;
+      }
+      console.log(
+        chalk.green(
+          `\n✅ Found ${webDocsets.length} docset(s) with web sources\n`,
+        ),
+      );
+      // Get status for each docset
+      const statuses = [];
+      for (const docset of webDocsets) {
+        const status = await getDocsetStatus(docset, configPath);
+        statuses.push(status);
+      }
+      // Display summary
+      displaySummary(statuses);
+      // Display detailed status if verbose
+      if (options.verbose) {
+        console.log(chalk.blue("\n📋 Detailed Status\n"));
+        for (const status of statuses) {
+          displayDetailedStatus(status);
+        }
+      }
+    } catch (error) {
+      console.error(chalk.red("❌ Failed to get status"));
+      console.error(
+        chalk.red(error instanceof Error ? error.message : String(error)),
+      );
+      process.exit(1);
+    }
+  });
+async function getDocsetStatus(docset, configPath) {
+  try {
+    const localPath = calculateLocalPath(docset, configPath);
+    const metadataPath = path.join(localPath, ".agentic-metadata.json");
+    // Check if docset is initialized
+    let metadata = null;
+    try {
+      const metadataContent = await fs.readFile(metadataPath, "utf8");
+      metadata = JSON.parse(metadataContent);
+    } catch {
+      return {
+        docset,
+        initialized: false,
+        metadata: null,
+        sources: [],
+      };
+    }
+    // Load source metadata
+    const sources = [];
+    for (let i = 0; i < (docset.web_sources?.length || 0); i++) {
+      try {
+        const sourceMetadataPath = path.join(
+          localPath,
+          `.agentic-source-${i}.json`,
+        );
+        const sourceContent = await fs.readFile(sourceMetadataPath, "utf8");
+        const sourceMetadata = JSON.parse(sourceContent);
+        sources.push(sourceMetadata);
+      } catch {
+        // Source metadata missing - this might indicate an issue
+      }
+    }
+    return {
+      docset,
+      initialized: true,
+      metadata,
+      sources,
+    };
+  } catch (error) {
+    return {
+      docset,
+      initialized: false,
+      metadata: null,
+      sources: [],
+      error: error instanceof Error ? error.message : String(error),
+    };
+  }
+}
+function displaySummary(statuses) {
+  console.log(chalk.blue("📈 Summary"));
+  console.log("─".repeat(50));
+  for (const status of statuses) {
+    const { docset, initialized, metadata, sources, error } = status;
+    if (error) {
+      console.log(
+        `${chalk.red("❌")} ${chalk.bold(docset.id)} - ${chalk.red("Error: " + error)}`,
+      );
+      continue;
+    }
+    if (!initialized) {
+      console.log(
+        `${chalk.yellow("⚠️")} ${chalk.bold(docset.id)} - ${chalk.yellow("Not initialized")}`,
+      );
+      console.log(
+        chalk.gray(
+          `   ${docset.web_sources?.length || 0} web source(s) configured`,
+        ),
+      );
+      continue;
+    }
+    if (!metadata) {
+      console.log(
+        `${chalk.red("❌")} ${chalk.bold(docset.id)} - ${chalk.red("Metadata corrupted")}`,
+      );
+      continue;
+    }
+    // Calculate status
+    const lastActivity = metadata.last_refreshed || metadata.initialized_at;
+    const lastActivityTime = new Date(lastActivity);
+    const timeSince = Date.now() - lastActivityTime.getTime();
+    const hoursSince = timeSince / (1000 * 60 * 60);
+    const daysSince = timeSince / (1000 * 60 * 60 * 24);
+    let timeDisplay;
+    let statusIcon;
+    if (hoursSince < 1) {
+      timeDisplay = `${Math.round(hoursSince * 60)} minutes ago`;
+      statusIcon = chalk.green("✅");
+    } else if (hoursSince < 24) {
+      timeDisplay = `${Math.round(hoursSince)} hours ago`;
+      statusIcon = chalk.green("✅");
+    } else if (daysSince < 7) {
+      timeDisplay = `${Math.round(daysSince)} days ago`;
+      statusIcon = chalk.yellow("⚠️");
+    } else {
+      timeDisplay = `${Math.round(daysSince)} days ago`;
+      statusIcon = chalk.red("🔄");
+    }
+    console.log(
+      `${statusIcon} ${chalk.bold(docset.id)} - ${chalk.gray(metadata.total_files)} files`,
+    );
+    console.log(
+      chalk.gray(
+        `   Last updated: ${timeDisplay} | ${sources.length}/${metadata.web_sources_count} sources loaded`,
+      ),
+    );
+  }
+}
+function displayDetailedStatus(status) {
+  const { docset, initialized, metadata, sources, error } = status;
+  console.log(chalk.bold(`🔸 ${docset.id} (${docset.name})`));
+  console.log("─".repeat(40));
+  if (error) {
+    console.log(chalk.red(`❌ Error: ${error}`));
+    console.log();
+    return;
+  }
+  if (!initialized) {
+    console.log(chalk.yellow("⚠️  Status: Not initialized"));
+    console.log(
+      chalk.gray(`📝 Description: ${docset.description || "No description"}`),
+    );
+    console.log(
+      chalk.gray(
+        `🔗 Web sources configured: ${docset.web_sources?.length || 0}`,
+      ),
+    );
+    if (docset.web_sources && docset.web_sources.length > 0) {
+      console.log(chalk.gray("   Sources:"));
+      for (const [i, source] of docset.web_sources.entries()) {
+        console.log(
+          chalk.gray(`     ${i + 1}. ${source.url} (${source.type})`),
+        );
+      }
+      console.log(
+        chalk.blue(
+          "\n   💡 Run 'agentic-knowledge init " +
+            docset.id +
+            "' to initialize",
+        ),
+      );
+    }
+    console.log();
+    return;
+  }
+  if (!metadata) {
+    console.log(chalk.red("❌ Status: Metadata corrupted"));
+    console.log();
+    return;
+  }
+  // Display basic info
+  console.log(chalk.green("✅ Status: Initialized"));
+  console.log(
+    chalk.gray(`📝 Description: ${docset.description || "No description"}`),
+  );
+  console.log(chalk.gray(`📄 Total files: ${metadata.total_files}`));
+  console.log(chalk.gray(`🔗 Web sources: ${metadata.web_sources_count}`));
+  // Display timing info
+  const initTime = new Date(metadata.initialized_at);
+  const lastRefresh = metadata.last_refreshed
+    ? new Date(metadata.last_refreshed)
+    : null;
+  console.log(chalk.gray(`📅 Initialized: ${initTime.toLocaleString()}`));
+  if (lastRefresh) {
+    console.log(
+      chalk.gray(`🔄 Last refreshed: ${lastRefresh.toLocaleString()}`),
+    );
+  }
+  // Display source details
+  if (sources.length > 0) {
+    console.log(chalk.gray("\n🔗 Sources:"));
+    for (const [i, source] of sources.entries()) {
+      const downloadTime = new Date(source.downloaded_at);
+      console.log(
+        chalk.gray(
+          `   ${i + 1}. ${source.source_url} (${source.files_count} files, ${downloadTime.toLocaleString()})`,
+        ),
+      );
+      if (source.last_commit) {
+        console.log(
+          chalk.gray(
+            `      Last commit: ${source.last_commit.substring(0, 8)}`,
+          ),
+        );
+      }
+    }
+  }
+  // Display missing sources
+  const missingSources = (docset.web_sources?.length || 0) - sources.length;
+  if (missingSources > 0) {
+    console.log(
+      chalk.yellow(
+        `⚠️  ${missingSources} source(s) missing metadata - run refresh`,
+      ),
+    );
+  }
+  console.log();
+}

package/packages/cli/dist/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * CLI exports for agentic-knowledge
+ */
+export * from "./commands/init.js";
+export * from "./commands/refresh.js";
+export * from "./commands/status.js";

package/packages/cli/dist/index.js

@@ -0,0 +1,6 @@
+/**
+ * CLI exports for agentic-knowledge
+ */
+export * from "./commands/init.js";
+export * from "./commands/refresh.js";
+export * from "./commands/status.js";

package/packages/cli/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@codemcp/knowledge-cli",
+  "version": "0.0.1",
+  "description": "Command-line interface for agentic knowledge web content management",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "agentic-knowledge": "./dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "build:watch": "tsc -p tsconfig.build.json --watch",
+    "clean": "rimraf dist",
+    "dev": "tsc -p tsconfig.build.json --watch",
+    "lint": "oxlint && eslint .",
+    "lint:fix": "oxlint --fix && eslint . --fix",
+    "format:check": "prettier --check .",
+    "format:fix": "prettier --write .",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@codemcp/knowledge-core": "workspace:*",
+    "@codemcp/knowledge-content-loader": "workspace:*",
+    "commander": "^12.0.0",
+    "chalk": "^5.3.0",
+    "ora": "^8.0.1"
+  },
+  "devDependencies": {
+    "@types/node": "^24.3.0",
+    "rimraf": "^6.0.1",
+    "typescript": "^5.9.2",
+    "vitest": "^3.2.4"
+  },
+  "keywords": [
+    "agentic",
+    "knowledge",
+    "cli",
+    "web-content",
+    "documentation",
+    "git"
+  ],
+  "author": "Oliver Jägle <github@beimir.net>",
+  "license": "MIT"
+}

package/packages/content-loader/dist/__tests__/debug-filtering.d.ts

@@ -0,0 +1 @@
+export {};

package/packages/content-loader/dist/__tests__/debug-filtering.js

@@ -0,0 +1,17 @@
+import { GitRepoLoader } from "../content/git-repo-loader.js";
+import * as path from "node:path";
+const loader = new GitRepoLoader();
+const testFiles = [
+  ".github/commit-convention.md",
+  "docs/getting-started.md",
+  "src/index.js",
+];
+console.log("Testing directory exclusion logic:");
+for (const file of testFiles) {
+  const directory = path.dirname(file);
+  console.log(`File: ${file}`);
+  console.log(`Directory: "${directory}"`);
+  console.log(`Includes .github: ${directory.includes(".github")}`);
+  console.log(`Result: ${loader.isDocumentationFile(file)}`);
+  console.log("---");
+}

package/packages/content-loader/dist/__tests__/test-filtering.d.ts

@@ -0,0 +1 @@
+export {};

package/packages/content-loader/dist/__tests__/test-filtering.js

@@ -0,0 +1,19 @@
+// Quick test of filtering logic
+import { GitRepoLoader } from "../content/git-repo-loader.js";
+const loader = new GitRepoLoader();
+const testFiles = [
+  "README.md", // Should include: README anywhere
+  "docs/getting-started.md", // Should include: .md extension
+  "docs/.postcssrc.json", // Should exclude: hidden file
+  "docs/.vitepress/config.ts", // Should exclude: .ts extension (not in examples)
+  "docs/.vitepress/theme/index.ts", // Should exclude: .ts extension + hidden directory
+  "docs/.vitepress/theme/styles.css", // Should exclude: .css extension
+  "examples/config.json", // Should include: in examples directory
+  "examples/demo.js", // Should include: in examples directory
+  "src/main.ts", // Should exclude: in src directory
+];
+console.log("Testing filtering logic:");
+for (const file of testFiles) {
+  const result = loader.isDocumentationFile(file);
+  console.log(`${result ? "✅" : "❌"} ${file}`);
+}

package/packages/content-loader/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/content-loader/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, WebSourceError, WebSourceErrorType } 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 WebSourceError(
+      WebSourceErrorType.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 WebSourceError(
+      WebSourceErrorType.NOT_IMPLEMENTED,
+      "API documentation content ID generation is not yet implemented.",
+      { webSource: webSource.url },
+    );
+  }
+}

package/packages/content-loader/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/content-loader/dist/content/content-processor.js

@@ -0,0 +1,86 @@
+/**
+ * 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",
+            ".adoc",
+            ".asciidoc",
+        ];
+        return processableExtensions.includes(extension);
+    }
+}

package/packages/content-loader/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>;
+}

package/packages/content-loader/dist/content/documentation-site-loader.js

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