@fractary/codex 0.1.3 → 0.2.0

package/README.md

@@ -224,7 +224,15 @@ Follow [Semantic Versioning](https://semver.org/):
 
 MIT - see [LICENSE](LICENSE)
 
+## Documentation
+
+- [CLI Integration Guide](../../docs/guides/cli-integration.md) - How to integrate into CLI applications
+- [API Reference](../../docs/guides/api-reference.md) - Complete API documentation
+- [Configuration Guide](../../docs/guides/configuration.md) - Configuration reference
+- [Troubleshooting](../../docs/guides/troubleshooting.md) - Common issues and solutions
+- [Examples](../../docs/examples/) - Real-world usage patterns
+
 ## See Also
 
 - [Python SDK](../python/) - `fractary-codex` on PyPI
-- [Documentation](../../docs/)
+- [Technical Specifications](../../docs/specs/) - Detailed specs

package/dist/index.cjs

@@ -2419,387 +2419,6 @@ function setDefaultCacheManager(manager) {
   defaultCacheManager = manager;
 }
 
-// src/mcp/tools.ts
-var CODEX_TOOLS = [
-  {
-    name: "codex_fetch",
-    description: "Fetch a document from the Codex knowledge base by URI. Returns the document content.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        uri: {
-          type: "string",
-          description: "Codex URI in format: codex://org/project/path/to/file.md"
-        },
-        branch: {
-          type: "string",
-          description: "Git branch to fetch from (default: main)"
-        },
-        noCache: {
-          type: "boolean",
-          description: "Bypass cache and fetch fresh content"
-        }
-      },
-      required: ["uri"]
-    }
-  },
-  {
-    name: "codex_search",
-    description: "Search for documents in the Codex knowledge base.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        query: {
-          type: "string",
-          description: "Search query string"
-        },
-        org: {
-          type: "string",
-          description: "Filter by organization"
-        },
-        project: {
-          type: "string",
-          description: "Filter by project"
-        },
-        limit: {
-          type: "number",
-          description: "Maximum number of results (default: 10)"
-        },
-        type: {
-          type: "string",
-          description: "Filter by artifact type (e.g., docs, specs, logs)"
-        }
-      },
-      required: ["query"]
-    }
-  },
-  {
-    name: "codex_list",
-    description: "List documents in the Codex cache.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        org: {
-          type: "string",
-          description: "Filter by organization"
-        },
-        project: {
-          type: "string",
-          description: "Filter by project"
-        },
-        includeExpired: {
-          type: "boolean",
-          description: "Include expired cache entries"
-        }
-      }
-    }
-  },
-  {
-    name: "codex_invalidate",
-    description: "Invalidate cached documents matching a pattern.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        pattern: {
-          type: "string",
-          description: "URI pattern to invalidate (supports regex)"
-        }
-      },
-      required: ["pattern"]
-    }
-  }
-];
-function textResult(text, isError = false) {
-  return {
-    content: [{ type: "text", text }],
-    isError
-  };
-}
-function resourceResult(uri, content, mimeType) {
-  return {
-    content: [
-      {
-        type: "resource",
-        resource: {
-          uri,
-          mimeType,
-          text: content
-        }
-      }
-    ]
-  };
-}
-async function handleFetch(args, ctx) {
-  const { uri, branch, noCache } = args;
-  const ref = resolveReference(uri);
-  if (!ref) {
-    return textResult(`Invalid codex URI: ${uri}`, true);
-  }
-  try {
-    let result;
-    if (noCache) {
-      result = await ctx.storage.fetch(ref, { branch });
-      await ctx.cache.set(uri, result);
-    } else {
-      result = await ctx.cache.get(ref, { branch });
-    }
-    const content = result.content.toString("utf-8");
-    return resourceResult(uri, content, result.contentType);
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    return textResult(`Failed to fetch ${uri}: ${message}`, true);
-  }
-}
-async function handleSearch(args, ctx) {
-  const { query, org, project, limit = 10 } = args;
-  const stats = await ctx.cache.getStats();
-  if (stats.entryCount === 0) {
-    return textResult("No documents in cache. Use codex_fetch to load documents first.");
-  }
-  const message = `Search functionality requires a search index.
-Query: "${query}"
-Filters: org=${org || "any"}, project=${project || "any"}
-Limit: ${limit}
-
-To fetch documents, use codex_fetch with a specific URI like:
-codex://org/project/docs/file.md`;
-  return textResult(message);
-}
-async function handleList(args, ctx) {
-  const { org, project, includeExpired } = args;
-  const stats = await ctx.cache.getStats();
-  let message = `Cache Statistics:
-- Total entries: ${stats.entryCount}
-- Memory entries: ${stats.memoryEntries}
-- Memory size: ${formatBytes(stats.memorySize)}
-- Total size: ${formatBytes(stats.totalSize)}
-- Fresh: ${stats.freshCount}
-- Stale: ${stats.staleCount}
-- Expired: ${stats.expiredCount}`;
-  if (org) {
-    message += `
-
-Filtered by org: ${org}`;
-  }
-  if (project) {
-    message += `
-Filtered by project: ${project}`;
-  }
-  if (includeExpired) {
-    message += `
-Including expired entries`;
-  }
-  return textResult(message);
-}
-async function handleInvalidate(args, ctx) {
-  const { pattern } = args;
-  try {
-    const regex = new RegExp(pattern);
-    const count = await ctx.cache.invalidatePattern(regex);
-    return textResult(`Invalidated ${count} cache entries matching pattern: ${pattern}`);
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    return textResult(`Invalid pattern: ${message}`, true);
-  }
-}
-async function handleToolCall(name, args, ctx) {
-  switch (name) {
-    case "codex_fetch":
-      return handleFetch(args, ctx);
-    case "codex_search":
-      return handleSearch(args, ctx);
-    case "codex_list":
-      return handleList(args, ctx);
-    case "codex_invalidate":
-      return handleInvalidate(args, ctx);
-    default:
-      return textResult(`Unknown tool: ${name}`, true);
-  }
-}
-function formatBytes(bytes) {
-  if (bytes === 0) return "0 B";
-  const k = 1024;
-  const sizes = ["B", "KB", "MB", "GB"];
-  const i = Math.floor(Math.log(bytes) / Math.log(k));
-  return `${parseFloat((bytes / Math.pow(k, i)).toFixed(2))} ${sizes[i]}`;
-}
-
-// src/mcp/server.ts
-var McpServer = class {
-  config;
-  toolContext;
-  constructor(config) {
-    this.config = {
-      name: config.name ?? "codex",
-      version: config.version ?? "1.0.0",
-      cache: config.cache,
-      storage: config.storage
-    };
-    this.toolContext = {
-      cache: config.cache,
-      storage: config.storage
-    };
-  }
-  /**
-   * Get server info
-   */
-  getServerInfo() {
-    return {
-      name: this.config.name,
-      version: this.config.version,
-      capabilities: this.getCapabilities()
-    };
-  }
-  /**
-   * Get server capabilities
-   */
-  getCapabilities() {
-    return {
-      tools: {
-        listChanged: false
-      },
-      resources: {
-        subscribe: false,
-        listChanged: false
-      }
-    };
-  }
-  /**
-   * List available tools
-   */
-  listTools() {
-    return CODEX_TOOLS;
-  }
-  /**
-   * Call a tool
-   */
-  async callTool(name, args) {
-    return handleToolCall(name, args, this.toolContext);
-  }
-  /**
-   * List available resources
-   */
-  async listResources() {
-    const resources = [];
-    const stats = await this.config.cache.getStats();
-    resources.push({
-      uri: "codex://cache/summary",
-      name: "Cache Summary",
-      description: `${stats.entryCount} cached documents`,
-      mimeType: "text/plain"
-    });
-    return resources;
-  }
-  /**
-   * List resource templates
-   */
-  listResourceTemplates() {
-    return [
-      {
-        uriTemplate: "codex://{org}/{project}/{path}",
-        name: "Codex Document",
-        description: "Fetch a document from the Codex knowledge base",
-        mimeType: "text/markdown"
-      }
-    ];
-  }
-  /**
-   * Read a resource
-   */
-  async readResource(uri) {
-    if (uri === "codex://cache/summary") {
-      const stats = await this.config.cache.getStats();
-      return [
-        {
-          uri,
-          mimeType: "text/plain",
-          text: `Cache Statistics:
-- Total entries: ${stats.entryCount}
-- Memory entries: ${stats.memoryEntries}
-- Fresh: ${stats.freshCount}
-- Stale: ${stats.staleCount}
-- Expired: ${stats.expiredCount}`
-        }
-      ];
-    }
-    const ref = resolveReference(uri);
-    if (!ref) {
-      throw new Error(`Invalid codex URI: ${uri}`);
-    }
-    const result = await this.config.cache.get(ref);
-    return [
-      {
-        uri,
-        mimeType: result.contentType,
-        text: result.content.toString("utf-8")
-      }
-    ];
-  }
-  /**
-   * Handle JSON-RPC request
-   *
-   * This method handles the low-level MCP protocol messages.
-   */
-  async handleRequest(method, params) {
-    switch (method) {
-      case "initialize":
-        return {
-          protocolVersion: "2024-11-05",
-          serverInfo: this.getServerInfo(),
-          capabilities: this.getCapabilities()
-        };
-      case "tools/list":
-        return { tools: this.listTools() };
-      case "tools/call": {
-        const { name, arguments: args } = params;
-        return await this.callTool(name, args);
-      }
-      case "resources/list":
-        return { resources: await this.listResources() };
-      case "resources/templates/list":
-        return { resourceTemplates: this.listResourceTemplates() };
-      case "resources/read": {
-        const { uri } = params;
-        return { contents: await this.readResource(uri) };
-      }
-      case "prompts/list":
-        return { prompts: [] };
-      default:
-        throw new Error(`Unknown method: ${method}`);
-    }
-  }
-  /**
-   * Process a JSON-RPC message
-   */
-  async processMessage(message) {
-    let id = null;
-    try {
-      const request = JSON.parse(message);
-      id = request.id;
-      const { method, params } = request;
-      const result = await this.handleRequest(method, params);
-      return JSON.stringify({
-        jsonrpc: "2.0",
-        id,
-        result
-      });
-    } catch (error) {
-      const errorMessage = error instanceof Error ? error.message : String(error);
-      return JSON.stringify({
-        jsonrpc: "2.0",
-        id,
-        error: {
-          code: -32603,
-          message: errorMessage
-        }
-      });
-    }
-  }
-};
-function createMcpServer(config) {
-  return new McpServer(config);
-}
-
 // src/sync/types.ts
 var DEFAULT_SYNC_CONFIG = {
   defaultDirection: "to-codex",
@@ -3084,10 +2703,10 @@ function formatPlanSummary(plan) {
     lines.push(`\u26A0\uFE0F Conflicts: ${stats.conflicts} files`);
     lines.push("");
   }
-  lines.push(`Total: ${plan.totalFiles} files (${formatBytes2(stats.totalBytes)})`);
+  lines.push(`Total: ${plan.totalFiles} files (${formatBytes(stats.totalBytes)})`);
   return lines.join("\n");
 }
-function formatBytes2(bytes) {
+function formatBytes(bytes) {
   if (bytes === 0) return "0 B";
   const k = 1024;
   const sizes = ["B", "KB", "MB", "GB"];
@@ -4213,7 +3832,6 @@ function generateReferenceMigrationSummary(results) {
 
 exports.AutoSyncPatternSchema = AutoSyncPatternSchema;
 exports.BUILT_IN_TYPES = BUILT_IN_TYPES;
-exports.CODEX_TOOLS = CODEX_TOOLS;
 exports.CODEX_URI_PREFIX = CODEX_URI_PREFIX;
 exports.CacheManager = CacheManager;
 exports.CachePersistence = CachePersistence;
@@ -4233,7 +3851,6 @@ exports.HttpStorage = HttpStorage;
 exports.LEGACY_PATTERNS = LEGACY_PATTERNS;
 exports.LEGACY_REF_PREFIX = LEGACY_REF_PREFIX;
 exports.LocalStorage = LocalStorage;
-exports.McpServer = McpServer;
 exports.MetadataSchema = MetadataSchema;
 exports.PERMISSION_LEVEL_ORDER = PERMISSION_LEVEL_ORDER;
 exports.PermissionDeniedError = PermissionDeniedError;
@@ -4260,7 +3877,6 @@ exports.createEmptySyncPlan = createEmptySyncPlan;
 exports.createGitHubStorage = createGitHubStorage;
 exports.createHttpStorage = createHttpStorage;
 exports.createLocalStorage = createLocalStorage;
-exports.createMcpServer = createMcpServer;
 exports.createPermissionManager = createPermissionManager;
 exports.createRule = createRule;
 exports.createRulesFromPatterns = createRulesFromPatterns;
@@ -4308,11 +3924,6 @@ exports.getPlanStats = getPlanStats;
 exports.getRelativeCachePath = getRelativeCachePath;
 exports.getRemainingTtl = getRemainingTtl;
 exports.getTargetRepos = getTargetRepos;
-exports.handleFetch = handleFetch;
-exports.handleInvalidate = handleInvalidate;
-exports.handleList = handleList;
-exports.handleSearch = handleSearch;
-exports.handleToolCall = handleToolCall;
 exports.hasContentChanged = hasContentChanged;
 exports.hasFrontmatter = hasFrontmatter;
 exports.hasLegacyReferences = hasLegacyReferences;