@fractary/codex-mcp 0.8.0 → 0.9.0

package/dist/cli.cjs

@@ -5586,6 +5586,7 @@ var {
 // ../../sdk/js/dist/index.js
 init_cjs_shims();
 var import_micromatch = __toESM(require_micromatch(), 1);
+var path3 = __toESM(require("path"), 1);
 var import_path = __toESM(require("path"), 1);
 var import_child_process = require("child_process");
 
@@ -12237,6 +12238,7 @@ var safeLoadAll = renamed("safeLoadAll", "loadAll");
 var safeDump = renamed("safeDump", "dump");
 
 // ../../sdk/js/dist/index.js
+var fs3 = __toESM(require("fs/promises"), 1);
 var import_promises = __toESM(require("fs/promises"), 1);
 var import_util4 = require("util");
 var __defProp2 = Object.defineProperty;
@@ -12488,9 +12490,45 @@ function resolveReference(uri, options = {}) {
   };
   if (isCurrentProject && parsed.path) {
     resolved.localPath = parsed.path;
+    if (options.config) {
+      const fileSource = detectFilePluginSource(parsed.path, options.config);
+      if (fileSource) {
+        resolved.sourceType = "file-plugin";
+        resolved.filePluginSource = fileSource.name;
+        resolved.localPath = fileSource.fullPath;
+      }
+    }
   }
   return resolved;
 }
+function detectFilePluginSource(filePath, config) {
+  if (!config?.file?.sources) {
+    return null;
+  }
+  for (const [sourceName, source] of Object.entries(config.file.sources)) {
+    const basePath = source.local?.base_path;
+    if (!basePath) {
+      continue;
+    }
+    const normalizedPath = filePath.replace(/^\.\//, "").replace(/^\//, "");
+    const normalizedBasePath = basePath.replace(/^\.\//, "").replace(/^\//, "").replace(/\/$/, "");
+    if (normalizedPath.startsWith(normalizedBasePath)) {
+      return {
+        name: sourceName,
+        fullPath: import_path.default.join(basePath, normalizedPath.substring(normalizedBasePath.length).replace(/^\//, ""))
+      };
+    }
+    const sourceNameInPath = normalizedBasePath.split("/").pop();
+    if (sourceNameInPath && normalizedPath.startsWith(sourceNameInPath + "/")) {
+      const pathWithoutSource = normalizedPath.substring(sourceNameInPath.length + 1);
+      return {
+        name: sourceName,
+        fullPath: import_path.default.join(basePath, pathWithoutSource)
+      };
+    }
+  }
+  return null;
+}
 var TTL = {
   ONE_HOUR: 3600,
   ONE_DAY: 86400,
@@ -12662,6 +12700,41 @@ var CodexConfigSchema = external_exports.object({
   // Archive configuration
   archive: ArchiveConfigSchema.optional()
 }).strict();
+var FileSourceSchema = external_exports.object({
+  type: external_exports.enum(["s3", "r2", "gcs", "local"]),
+  bucket: external_exports.string().optional(),
+  prefix: external_exports.string().optional(),
+  region: external_exports.string().optional(),
+  local: external_exports.object({
+    base_path: external_exports.string()
+  }),
+  push: external_exports.object({
+    compress: external_exports.boolean().optional(),
+    keep_local: external_exports.boolean().optional()
+  }).optional(),
+  auth: external_exports.object({
+    profile: external_exports.string().optional()
+  }).optional()
+}).refine(
+  (data) => {
+    if (data.type !== "local" && !data.bucket) {
+      return false;
+    }
+    return true;
+  },
+  {
+    message: "Bucket is required for s3, r2, and gcs storage types",
+    path: ["bucket"]
+  }
+);
+var FileConfigSchema = external_exports.object({
+  schema_version: external_exports.string(),
+  sources: external_exports.record(FileSourceSchema)
+});
+external_exports.object({
+  file: FileConfigSchema.optional(),
+  codex: CodexConfigSchema.optional()
+});
 init_matcher();
 init_matcher();
 var DEFAULT_FETCH_OPTIONS = {
@@ -12680,8 +12753,8 @@ function mergeFetchOptions(options) {
     ...options
   };
 }
-function detectContentType(path6) {
-  const ext = path6.split(".").pop()?.toLowerCase();
+function detectContentType(path7) {
+  const ext = path7.split(".").pop()?.toLowerCase();
   const mimeTypes = {
     md: "text/markdown",
     markdown: "text/markdown",
@@ -13146,6 +13219,294 @@ var HttpStorage = class {
     }
   }
 };
+var FileSourceResolver = class {
+  constructor(config) {
+    this.config = config;
+    this.initializeSources();
+  }
+  sources = /* @__PURE__ */ new Map();
+  /**
+   * Initialize sources from config
+   */
+  initializeSources() {
+    if (!this.config.file?.sources) {
+      return;
+    }
+    for (const [name, sourceConfig] of Object.entries(this.config.file.sources)) {
+      const resolved = {
+        name,
+        type: "file-plugin",
+        localPath: sourceConfig.local.base_path,
+        isCurrentProject: true,
+        config: sourceConfig
+      };
+      if (sourceConfig.bucket && sourceConfig.type !== "local") {
+        resolved.bucket = sourceConfig.bucket;
+        resolved.prefix = sourceConfig.prefix;
+        resolved.remotePath = this.buildRemotePath(sourceConfig);
+      }
+      this.sources.set(name, resolved);
+    }
+  }
+  /**
+   * Build remote path from source config
+   */
+  buildRemotePath(source) {
+    const protocol = source.type === "s3" ? "s3://" : source.type === "r2" ? "r2://" : "gcs://";
+    const bucket = source.bucket;
+    const prefix = source.prefix ? `/${source.prefix}` : "";
+    return `${protocol}${bucket}${prefix}`;
+  }
+  /**
+   * Get all available file plugin sources
+   *
+   * @returns Array of resolved file sources
+   */
+  getAvailableSources() {
+    return Array.from(this.sources.values());
+  }
+  /**
+   * Resolve a source by name
+   *
+   * @param name - Source name (e.g., "specs", "logs")
+   * @returns Resolved source or null if not found
+   */
+  resolveSource(name) {
+    return this.sources.get(name) || null;
+  }
+  /**
+   * Check if a path belongs to any file plugin source
+   *
+   * @param path - File path to check
+   * @returns True if path matches any source's base_path
+   */
+  isFilePluginPath(path7) {
+    return this.getSourceForPath(path7) !== null;
+  }
+  /**
+   * Get the source for a given path
+   *
+   * Matches path against all source base_paths and returns the matching source.
+   * Uses longest-match strategy if multiple sources match.
+   *
+   * @param path - File path to match
+   * @returns Matching source or null
+   */
+  getSourceForPath(path7) {
+    let bestMatch = null;
+    let bestMatchLength = 0;
+    for (const source of this.sources.values()) {
+      const normalizedPath = this.normalizePath(path7);
+      const normalizedBasePath = this.normalizePath(source.localPath);
+      if (normalizedPath.startsWith(normalizedBasePath)) {
+        const matchLength = normalizedBasePath.length;
+        if (matchLength > bestMatchLength) {
+          bestMatch = source;
+          bestMatchLength = matchLength;
+        }
+      }
+    }
+    return bestMatch;
+  }
+  /**
+   * Normalize path for comparison
+   * - Remove leading "./" or "/"
+   * - Remove trailing "/"
+   * - Convert to lowercase for case-insensitive comparison
+   */
+  normalizePath(path7) {
+    return path7.replace(/^\.\//, "").replace(/^\//, "").replace(/\/$/, "").toLowerCase();
+  }
+  /**
+   * Get source names
+   *
+   * @returns Array of source names
+   */
+  getSourceNames() {
+    return Array.from(this.sources.keys());
+  }
+  /**
+   * Check if sources are configured
+   *
+   * @returns True if any file plugin sources are configured
+   */
+  hasSources() {
+    return this.sources.size > 0;
+  }
+};
+var FilePluginFileNotFoundError = class _FilePluginFileNotFoundError extends Error {
+  constructor(filePath, sourceName, options) {
+    const includeCloudSuggestions = options?.includeCloudSuggestions !== false;
+    const storageType = options?.storageType;
+    let message = `File not found: ${filePath}
+
+`;
+    if (includeCloudSuggestions) {
+      if (storageType) {
+        message += `This file may be in cloud storage (${storageType}).
+
+`;
+      } else {
+        message += `This file may not have been synced from remote storage yet.
+`;
+      }
+      message += `To fetch from cloud storage, run:
+`;
+      message += `  file pull ${sourceName}
+
+`;
+      message += `Or sync all sources:
+`;
+      message += `  file sync`;
+    } else {
+      message += `Please ensure the file exists locally or pull it from cloud storage.`;
+    }
+    super(message);
+    this.filePath = filePath;
+    this.sourceName = sourceName;
+    this.name = "FilePluginFileNotFoundError";
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, _FilePluginFileNotFoundError);
+    }
+  }
+};
+var FilePluginStorage = class {
+  constructor(options) {
+    this.options = options;
+    this.sourceResolver = new FileSourceResolver(options.config);
+    this.baseDir = options.baseDir || process.cwd();
+  }
+  name = "file-plugin";
+  type = "local";
+  // Reuse local type for compatibility
+  sourceResolver;
+  baseDir;
+  /**
+   * Check if this provider can handle the reference
+   *
+   * Only handles:
+   * - Current project references
+   * - With sourceType === 'file-plugin'
+   *
+   * @param reference - Resolved reference
+   * @returns True if this provider can handle the reference
+   */
+  canHandle(reference) {
+    return reference.isCurrentProject && reference.sourceType === "file-plugin";
+  }
+  /**
+   * Fetch content for a reference
+   *
+   * Reads from local filesystem based on the resolved local path.
+   * If file not found and S3 fallback is enabled, throws helpful error.
+   *
+   * @param reference - Resolved reference
+   * @param options - Fetch options (unused for local reads)
+   * @returns Fetch result with content
+   */
+  async fetch(reference, _options) {
+    if (!reference.localPath) {
+      throw new Error(`File plugin reference missing localPath: ${reference.uri}`);
+    }
+    if (!reference.filePluginSource) {
+      throw new Error(`File plugin reference missing source name: ${reference.uri}`);
+    }
+    const absolutePath = path3.isAbsolute(reference.localPath) ? path3.resolve(reference.localPath) : path3.resolve(this.baseDir, reference.localPath);
+    const source = this.sourceResolver.resolveSource(reference.filePluginSource);
+    if (source) {
+      const allowedDir = path3.resolve(this.baseDir, source.localPath);
+      if (!absolutePath.startsWith(allowedDir + path3.sep) && absolutePath !== allowedDir) {
+        throw new Error(
+          `Path traversal detected: ${reference.localPath} resolves outside allowed directory ${source.localPath}`
+        );
+      }
+    }
+    try {
+      const content = await fs3.readFile(absolutePath);
+      const contentType = this.detectContentType(absolutePath);
+      return {
+        content,
+        contentType,
+        size: content.length,
+        source: "file-plugin",
+        metadata: {
+          filePluginSource: reference.filePluginSource,
+          localPath: absolutePath
+        }
+      };
+    } catch (error) {
+      if (error.code === "ENOENT") {
+        const source2 = this.sourceResolver.resolveSource(reference.filePluginSource);
+        throw this.createFileNotFoundError(reference, source2);
+      }
+      throw error;
+    }
+  }
+  /**
+   * Check if a reference exists
+   *
+   * @param reference - Resolved reference
+   * @param options - Fetch options (unused)
+   * @returns True if file exists
+   */
+  async exists(reference, _options) {
+    if (!reference.localPath) {
+      return false;
+    }
+    const absolutePath = path3.isAbsolute(reference.localPath) ? path3.resolve(reference.localPath) : path3.resolve(this.baseDir, reference.localPath);
+    if (reference.filePluginSource) {
+      const source = this.sourceResolver.resolveSource(reference.filePluginSource);
+      if (source) {
+        const allowedDir = path3.resolve(this.baseDir, source.localPath);
+        if (!absolutePath.startsWith(allowedDir + path3.sep) && absolutePath !== allowedDir) {
+          return false;
+        }
+      }
+    }
+    try {
+      await fs3.access(absolutePath);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  /**
+   * Detect content type from file extension
+   */
+  detectContentType(filePath) {
+    const ext = path3.extname(filePath).toLowerCase();
+    const mimeTypes = {
+      ".md": "text/markdown",
+      ".txt": "text/plain",
+      ".json": "application/json",
+      ".yaml": "text/yaml",
+      ".yml": "text/yaml",
+      ".html": "text/html",
+      ".xml": "application/xml",
+      ".log": "text/plain",
+      ".js": "application/javascript",
+      ".ts": "application/typescript",
+      ".py": "text/x-python",
+      ".sh": "application/x-sh"
+    };
+    return mimeTypes[ext] || "application/octet-stream";
+  }
+  /**
+   * Create a helpful error message when file is not found
+   */
+  createFileNotFoundError(reference, source) {
+    const includeCloudSuggestions = this.options.enableS3Fallback !== false;
+    const storageType = source?.config.type;
+    return new FilePluginFileNotFoundError(
+      reference.localPath || reference.path || "",
+      reference.filePluginSource || "",
+      {
+        includeCloudSuggestions,
+        storageType
+      }
+    );
+  }
+};
 var execFileAsync = (0, import_util4.promisify)(import_child_process.execFile);
 async function execFileNoThrow(command, args = [], options) {
   try {
@@ -13293,10 +13654,10 @@ var S3ArchiveStorage = class {
    *
    * Used to organize archives by type
    */
-  detectType(path6) {
-    if (path6.startsWith("specs/")) return "specs";
-    if (path6.startsWith("docs/")) return "docs";
-    if (path6.includes("/logs/")) return "logs";
+  detectType(path7) {
+    if (path7.startsWith("specs/")) return "specs";
+    if (path7.startsWith("docs/")) return "docs";
+    if (path7.includes("/logs/")) return "logs";
     return "misc";
   }
   /**
@@ -13307,9 +13668,9 @@ var S3ArchiveStorage = class {
    * - *.md (all markdown files)
    * - docs/*.md (markdown files in docs/)
    */
-  matchesPatterns(path6, patterns) {
+  matchesPatterns(path7, patterns) {
     for (const pattern of patterns) {
-      if (this.matchesPattern(path6, pattern)) {
+      if (this.matchesPattern(path7, pattern)) {
         return true;
       }
     }
@@ -13318,14 +13679,14 @@ var S3ArchiveStorage = class {
   /**
    * Check if path matches a single pattern
    */
-  matchesPattern(path6, pattern) {
+  matchesPattern(path7, pattern) {
     const DOUBLE_STAR = "\0DOUBLE_STAR\0";
     let regexPattern = pattern.replace(/\*\*/g, DOUBLE_STAR);
     regexPattern = regexPattern.replace(/[.[\](){}+^$|\\]/g, "\\$&");
     regexPattern = regexPattern.replace(/\*/g, "[^/]*").replace(/\?/g, "[^/]");
     regexPattern = regexPattern.replace(new RegExp(DOUBLE_STAR, "g"), ".*");
     const regex = new RegExp(`^${regexPattern}$`);
-    return regex.test(path6);
+    return regex.test(path7);
   }
 };
 var StorageManager = class {
@@ -13338,7 +13699,10 @@ var StorageManager = class {
     if (config.s3Archive) {
       this.providers.set("s3-archive", new S3ArchiveStorage(config.s3Archive));
     }
-    this.priority = config.priority || (config.s3Archive ? ["local", "s3-archive", "github", "http"] : ["local", "github", "http"]);
+    if (config.filePlugin) {
+      this.providers.set("file-plugin", new FilePluginStorage(config.filePlugin));
+    }
+    this.priority = config.priority || (config.filePlugin && config.s3Archive ? ["file-plugin", "local", "s3-archive", "github", "http"] : config.filePlugin ? ["file-plugin", "local", "github", "http"] : config.s3Archive ? ["local", "s3-archive", "github", "http"] : ["local", "github", "http"]);
   }
   /**
    * Register a custom storage provider
@@ -13806,8 +14170,17 @@ var CacheManager = class {
    * Get content for a reference
    *
    * Implements cache-first strategy with stale-while-revalidate.
+   *
+   * EXCEPTION: File plugin sources (current project files) bypass cache entirely.
+   * They are always read fresh from disk for optimal development experience.
    */
   async get(reference, options) {
+    if (reference.isCurrentProject && reference.sourceType === "file-plugin") {
+      if (!this.storage) {
+        throw new Error("Storage manager not set");
+      }
+      return await this.storage.fetch(reference, options);
+    }
     const ttl = options?.ttl ?? this.config.defaultTtl;
     let entry = this.memoryCache.get(reference.uri);
     if (!entry && this.persistence) {
@@ -14013,13 +14386,18 @@ var CacheManager = class {
   }
   /**
    * Fetch content and store in cache
+   *
+   * EXCEPTION: File plugin sources are not cached (should not reach here,
+   * but added as safety check).
    */
   async fetchAndCache(reference, ttl, options) {
     if (!this.storage) {
       throw new Error("Storage manager not set");
     }
     const result = await this.storage.fetch(reference, options);
-    await this.set(reference.uri, result, ttl);
+    if (!(reference.isCurrentProject && reference.sourceType === "file-plugin")) {
+      await this.set(reference.uri, result, ttl);
+    }
     return result;
   }
   /**
@@ -14203,6 +14581,14 @@ var CODEX_TOOLS = [
       },
       required: ["pattern"]
     }
+  },
+  {
+    name: "codex_file_sources_list",
+    description: "List file plugin sources available in the current project.",
+    inputSchema: {
+      type: "object",
+      properties: {}
+    }
   }
 ];
 function textResult(text, isError = false) {
@@ -14239,9 +14625,12 @@ async function handleFetch(args, ctx) {
   }
   try {
     let result;
+    const isFilePlugin = ref.isCurrentProject && ref.sourceType === "file-plugin";
     if (noCache) {
       result = await ctx.storage.fetch(ref, { branch });
-      await ctx.cache.set(uri, result);
+      if (!isFilePlugin) {
+        await ctx.cache.set(uri, result);
+      }
     } else {
       result = await ctx.cache.get(ref, { branch });
     }
@@ -14249,6 +14638,10 @@ async function handleFetch(args, ctx) {
     return resourceResult(uri, content, result.contentType);
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
+    const errorName = error instanceof Error ? error.name : "Error";
+    if (errorName === "FilePluginFileNotFoundError") {
+      return textResult(message, true);
+    }
     return textResult(`Failed to fetch ${uri}: ${message}`, true);
   }
 }
@@ -14347,6 +14740,33 @@ async function handleCacheClear(args, ctx) {
     return textResult(`Failed to clear cache: ${message}`, true);
   }
 }
+async function handleFileSourcesList(ctx) {
+  try {
+    const filePluginProvider = ctx.storage.getProvider("file-plugin");
+    if (!filePluginProvider) {
+      return textResult(`No file plugin sources configured.
+
+To enable file plugin integration, the storage manager must be initialized with filePlugin configuration.
+
+File plugin sources allow codex to access current project artifacts (specs, logs, etc.) directly from the local filesystem without caching.`);
+    }
+    return textResult(`File plugin provider is configured.
+
+File plugin sources are available for current project artifact access.
+Sources are read directly from local filesystem without caching.
+
+To see available sources, check the unified configuration at:
+.fractary/config.yaml
+
+Look for the 'file.sources' section which defines:
+- specs: .fractary/specs
+- logs: .fractary/logs
+- etc.`);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return textResult(`Failed to list file sources: ${message}`, true);
+  }
+}
 async function handleToolCall(name, args, ctx) {
   switch (name) {
     case "codex_document_fetch":
@@ -14357,6 +14777,8 @@ async function handleToolCall(name, args, ctx) {
       return handleList(args, ctx);
     case "codex_cache_clear":
       return handleCacheClear(args, ctx);
+    case "codex_file_sources_list":
+      return handleFileSourcesList(ctx);
     default:
       return textResult(`Unknown tool: ${name}`, true);
   }