@fractary/codex 0.8.0 → 0.9.0

package/dist/index.js

@@ -1,9 +1,11 @@
 import micromatch3 from 'micromatch';
-import path3 from 'path';
+import * as path3 from 'path';
+import path3__default from 'path';
 import { execFile, execSync } from 'child_process';
 import { z } from 'zod';
 import yaml from 'js-yaml';
-import fs2 from 'fs/promises';
+import * as fs3 from 'fs/promises';
+import fs3__default from 'fs/promises';
 import { promisify } from 'util';
 
 var __defProp = Object.defineProperty;
@@ -161,7 +163,7 @@ function validatePath(filePath) {
       return false;
     }
   }
-  const normalized = path3.normalize(filePath);
+  const normalized = path3__default.normalize(filePath);
   if (normalized.startsWith("..") || normalized.includes("/../") || normalized.includes("\\..\\")) {
     return false;
   }
@@ -179,7 +181,7 @@ function sanitizePath(filePath) {
   }
   sanitized = sanitized.replace(/^\/+/, "");
   sanitized = sanitized.replace(/^~\//, "");
-  sanitized = path3.normalize(sanitized);
+  sanitized = path3__default.normalize(sanitized);
   sanitized = sanitized.replace(/\.\.\//g, "").replace(/\.\./g, "");
   sanitized = sanitized.replace(/^\.\//, "");
   sanitized = sanitized.replace(/\0/g, "");
@@ -280,10 +282,10 @@ function parseReference(uri, options = {}) {
     path: filePath
   };
 }
-function buildUri(org, project, path6) {
+function buildUri(org, project, path7) {
   const base = `${CODEX_URI_PREFIX}${org}/${project}`;
-  if (path6) {
-    const cleanPath = path6.startsWith("/") ? path6.slice(1) : path6;
+  if (path7) {
+    const cleanPath = path7.startsWith("/") ? path7.slice(1) : path7;
     return `${base}/${cleanPath}`;
   }
   return base;
@@ -354,7 +356,7 @@ function getCurrentContext(options = {}) {
   return detectCurrentProject(options.cwd);
 }
 function calculateCachePath(org, project, filePath, cacheDir) {
-  return path3.join(cacheDir, org, project, filePath);
+  return path3__default.join(cacheDir, org, project, filePath);
 }
 function resolveReference(uri, options = {}) {
   const parsed = parseReference(uri);
@@ -363,7 +365,7 @@ function resolveReference(uri, options = {}) {
   }
   const cacheDir = options.cacheDir || DEFAULT_CACHE_DIR;
   const currentContext = getCurrentContext(options);
-  const cachePath = parsed.path ? calculateCachePath(parsed.org, parsed.project, parsed.path, cacheDir) : path3.join(cacheDir, parsed.org, parsed.project);
+  const cachePath = parsed.path ? calculateCachePath(parsed.org, parsed.project, parsed.path, cacheDir) : path3__default.join(cacheDir, parsed.org, parsed.project);
   const isCurrentProject = currentContext.org === parsed.org && currentContext.project === parsed.project;
   const resolved = {
     ...parsed,
@@ -372,9 +374,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: path3__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: path3__default.join(basePath, pathWithoutSource)
+      };
+    }
+  }
+  return null;
+}
 function resolveReferences(uris, options = {}) {
   return uris.map((uri) => resolveReference(uri, options)).filter((r) => r !== null);
 }
@@ -388,9 +426,9 @@ function getRelativeCachePath(uri) {
     return null;
   }
   if (parsed.path) {
-    return path3.join(parsed.org, parsed.project, parsed.path);
+    return path3__default.join(parsed.org, parsed.project, parsed.path);
   }
-  return path3.join(parsed.org, parsed.project);
+  return path3__default.join(parsed.org, parsed.project);
 }
 
 // src/types/built-in.ts
@@ -858,6 +896,41 @@ var CodexConfigSchema = z.object({
   // Archive configuration
   archive: ArchiveConfigSchema.optional()
 }).strict();
+var FileSourceSchema = z.object({
+  type: z.enum(["s3", "r2", "gcs", "local"]),
+  bucket: z.string().optional(),
+  prefix: z.string().optional(),
+  region: z.string().optional(),
+  local: z.object({
+    base_path: z.string()
+  }),
+  push: z.object({
+    compress: z.boolean().optional(),
+    keep_local: z.boolean().optional()
+  }).optional(),
+  auth: z.object({
+    profile: z.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 = z.object({
+  schema_version: z.string(),
+  sources: z.record(FileSourceSchema)
+});
+z.object({
+  file: FileConfigSchema.optional(),
+  codex: CodexConfigSchema.optional()
+});
 function parseMetadata(content, options = {}) {
   const { strict = true, normalize = true } = options;
   const normalizedContent = normalize ? content.replace(/\r\n/g, "\n") : content;
@@ -1187,18 +1260,18 @@ function parseCustomDestination(value) {
     );
   }
   const repo = value.substring(0, colonIndex).trim();
-  const path6 = value.substring(colonIndex + 1).trim();
+  const path7 = value.substring(colonIndex + 1).trim();
   if (!repo) {
     throw new ValidationError(
       `Invalid custom destination: repository name cannot be empty in "${value}"`
     );
   }
-  if (!path6) {
+  if (!path7) {
     throw new ValidationError(
       `Invalid custom destination: path cannot be empty in "${value}"`
     );
   }
-  return { repo, path: path6 };
+  return { repo, path: path7 };
 }
 function getCustomSyncDestinations(metadata) {
   const customDestinations = metadata.codex_sync_custom;
@@ -1234,8 +1307,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",
@@ -1295,19 +1368,19 @@ var LocalStorage = class {
     if (!reference.localPath) {
       throw new Error(`No local path for reference: ${reference.uri}`);
     }
-    const fullPath = path3.isAbsolute(reference.localPath) ? reference.localPath : path3.join(this.baseDir, reference.localPath);
+    const fullPath = path3__default.isAbsolute(reference.localPath) ? reference.localPath : path3__default.join(this.baseDir, reference.localPath);
     try {
-      await fs2.access(fullPath);
+      await fs3__default.access(fullPath);
     } catch {
       throw new Error(`File not found: ${fullPath}`);
     }
-    const stats = await fs2.stat(fullPath);
+    const stats = await fs3__default.stat(fullPath);
     if (stats.size > opts.maxSize) {
       throw new Error(
         `File too large: ${stats.size} bytes (max: ${opts.maxSize} bytes)`
       );
     }
-    const content = await fs2.readFile(fullPath);
+    const content = await fs3__default.readFile(fullPath);
     return {
       content,
       contentType: detectContentType(reference.localPath),
@@ -1326,9 +1399,9 @@ var LocalStorage = class {
     if (!reference.localPath) {
       return false;
     }
-    const fullPath = path3.isAbsolute(reference.localPath) ? reference.localPath : path3.join(this.baseDir, reference.localPath);
+    const fullPath = path3__default.isAbsolute(reference.localPath) ? reference.localPath : path3__default.join(this.baseDir, reference.localPath);
     try {
-      await fs2.access(fullPath);
+      await fs3__default.access(fullPath);
       return true;
     } catch {
       return false;
@@ -1338,24 +1411,24 @@ var LocalStorage = class {
    * Read file content as string
    */
   async readText(filePath) {
-    const fullPath = path3.isAbsolute(filePath) ? filePath : path3.join(this.baseDir, filePath);
-    return fs2.readFile(fullPath, "utf-8");
+    const fullPath = path3__default.isAbsolute(filePath) ? filePath : path3__default.join(this.baseDir, filePath);
+    return fs3__default.readFile(fullPath, "utf-8");
   }
   /**
    * Write content to file
    */
   async write(filePath, content) {
-    const fullPath = path3.isAbsolute(filePath) ? filePath : path3.join(this.baseDir, filePath);
-    await fs2.mkdir(path3.dirname(fullPath), { recursive: true });
-    await fs2.writeFile(fullPath, content);
+    const fullPath = path3__default.isAbsolute(filePath) ? filePath : path3__default.join(this.baseDir, filePath);
+    await fs3__default.mkdir(path3__default.dirname(fullPath), { recursive: true });
+    await fs3__default.writeFile(fullPath, content);
   }
   /**
    * Delete a file
    */
   async delete(filePath) {
-    const fullPath = path3.isAbsolute(filePath) ? filePath : path3.join(this.baseDir, filePath);
+    const fullPath = path3__default.isAbsolute(filePath) ? filePath : path3__default.join(this.baseDir, filePath);
     try {
-      await fs2.unlink(fullPath);
+      await fs3__default.unlink(fullPath);
       return true;
     } catch {
       return false;
@@ -1365,10 +1438,10 @@ var LocalStorage = class {
    * List files in a directory
    */
   async list(dirPath) {
-    const fullPath = path3.isAbsolute(dirPath) ? dirPath : path3.join(this.baseDir, dirPath);
+    const fullPath = path3__default.isAbsolute(dirPath) ? dirPath : path3__default.join(this.baseDir, dirPath);
     try {
-      const entries = await fs2.readdir(fullPath, { withFileTypes: true });
-      return entries.filter((e) => e.isFile()).map((e) => path3.join(dirPath, e.name));
+      const entries = await fs3__default.readdir(fullPath, { withFileTypes: true });
+      return entries.filter((e) => e.isFile()).map((e) => path3__default.join(dirPath, e.name));
     } catch {
       return [];
     }
@@ -1713,6 +1786,300 @@ var HttpStorage = class {
 function createHttpStorage(options) {
   return new HttpStorage(options);
 }
+
+// src/file-integration/source-resolver.ts
+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;
+  }
+};
+
+// src/storage/errors.ts
+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);
+    }
+  }
+};
+
+// src/storage/file-plugin.ts
+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 = promisify(execFile);
 async function execFileNoThrow(command, args = [], options) {
   try {
@@ -1862,10 +2229,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";
   }
   /**
@@ -1876,9 +2243,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;
       }
     }
@@ -1887,14 +2254,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);
   }
 };
 
@@ -1909,7 +2276,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
@@ -2149,7 +2519,7 @@ var CachePersistence = class {
     }
     const [, org, project, filePath] = match;
     const relativePath = filePath || "index";
-    return path3.join(this.cacheDir, org, project, relativePath + this.extension);
+    return path3__default.join(this.cacheDir, org, project, relativePath + this.extension);
   }
   /**
    * Get the metadata file path for a URI
@@ -2165,8 +2535,8 @@ var CachePersistence = class {
     const metadataPath = this.getMetadataPath(uri);
     try {
       const [metadataJson, content] = await Promise.all([
-        fs2.readFile(metadataPath, "utf-8"),
-        fs2.readFile(cachePath)
+        fs3__default.readFile(metadataPath, "utf-8"),
+        fs3__default.readFile(cachePath)
       ]);
       const metadata = JSON.parse(metadataJson);
       return {
@@ -2186,32 +2556,32 @@ var CachePersistence = class {
   async write(entry) {
     const cachePath = this.getCachePath(entry.metadata.uri);
     const metadataPath = this.getMetadataPath(entry.metadata.uri);
-    await fs2.mkdir(path3.dirname(cachePath), { recursive: true });
+    await fs3__default.mkdir(path3__default.dirname(cachePath), { recursive: true });
     if (this.atomicWrites) {
       const tempCachePath = cachePath + ".tmp";
       const tempMetadataPath = metadataPath + ".tmp";
       try {
         await Promise.all([
-          fs2.writeFile(tempCachePath, entry.content),
-          fs2.writeFile(tempMetadataPath, JSON.stringify(entry.metadata, null, 2))
+          fs3__default.writeFile(tempCachePath, entry.content),
+          fs3__default.writeFile(tempMetadataPath, JSON.stringify(entry.metadata, null, 2))
         ]);
         await Promise.all([
-          fs2.rename(tempCachePath, cachePath),
-          fs2.rename(tempMetadataPath, metadataPath)
+          fs3__default.rename(tempCachePath, cachePath),
+          fs3__default.rename(tempMetadataPath, metadataPath)
         ]);
       } catch (error) {
         await Promise.all([
-          fs2.unlink(tempCachePath).catch(() => {
+          fs3__default.unlink(tempCachePath).catch(() => {
           }),
-          fs2.unlink(tempMetadataPath).catch(() => {
+          fs3__default.unlink(tempMetadataPath).catch(() => {
           })
         ]);
         throw error;
       }
     } else {
       await Promise.all([
-        fs2.writeFile(cachePath, entry.content),
-        fs2.writeFile(metadataPath, JSON.stringify(entry.metadata, null, 2))
+        fs3__default.writeFile(cachePath, entry.content),
+        fs3__default.writeFile(metadataPath, JSON.stringify(entry.metadata, null, 2))
       ]);
     }
   }
@@ -2222,7 +2592,7 @@ var CachePersistence = class {
     const cachePath = this.getCachePath(uri);
     const metadataPath = this.getMetadataPath(uri);
     try {
-      await Promise.all([fs2.unlink(cachePath), fs2.unlink(metadataPath)]);
+      await Promise.all([fs3__default.unlink(cachePath), fs3__default.unlink(metadataPath)]);
       return true;
     } catch (error) {
       if (error.code === "ENOENT") {
@@ -2237,7 +2607,7 @@ var CachePersistence = class {
   async exists(uri) {
     const cachePath = this.getCachePath(uri);
     try {
-      await fs2.access(cachePath);
+      await fs3__default.access(cachePath);
       return true;
     } catch {
       return false;
@@ -2249,20 +2619,20 @@ var CachePersistence = class {
   async list() {
     const uris = [];
     try {
-      const orgs = await fs2.readdir(this.cacheDir);
+      const orgs = await fs3__default.readdir(this.cacheDir);
       for (const org of orgs) {
-        const orgPath = path3.join(this.cacheDir, org);
-        const orgStat = await fs2.stat(orgPath);
+        const orgPath = path3__default.join(this.cacheDir, org);
+        const orgStat = await fs3__default.stat(orgPath);
         if (!orgStat.isDirectory()) continue;
-        const projects = await fs2.readdir(orgPath);
+        const projects = await fs3__default.readdir(orgPath);
         for (const project of projects) {
-          const projectPath = path3.join(orgPath, project);
-          const projectStat = await fs2.stat(projectPath);
+          const projectPath = path3__default.join(orgPath, project);
+          const projectStat = await fs3__default.stat(projectPath);
           if (!projectStat.isDirectory()) continue;
           const files = await this.listFilesRecursive(projectPath);
           for (const file of files) {
             if (file.endsWith(this.extension)) {
-              const relativePath = path3.relative(projectPath, file);
+              const relativePath = path3__default.relative(projectPath, file);
               const filePath = relativePath.slice(0, -this.extension.length);
               uris.push(`codex://${org}/${project}/${filePath}`);
             }
@@ -2282,9 +2652,9 @@ var CachePersistence = class {
    */
   async listFilesRecursive(dir) {
     const files = [];
-    const entries = await fs2.readdir(dir, { withFileTypes: true });
+    const entries = await fs3__default.readdir(dir, { withFileTypes: true });
     for (const entry of entries) {
-      const fullPath = path3.join(dir, entry.name);
+      const fullPath = path3__default.join(dir, entry.name);
       if (entry.isDirectory()) {
         files.push(...await this.listFilesRecursive(fullPath));
       } else if (entry.isFile()) {
@@ -2299,12 +2669,12 @@ var CachePersistence = class {
   async clear() {
     let count = 0;
     try {
-      const orgs = await fs2.readdir(this.cacheDir);
+      const orgs = await fs3__default.readdir(this.cacheDir);
       for (const org of orgs) {
-        const orgPath = path3.join(this.cacheDir, org);
-        const stat = await fs2.stat(orgPath);
+        const orgPath = path3__default.join(this.cacheDir, org);
+        const stat = await fs3__default.stat(orgPath);
         if (stat.isDirectory()) {
-          await fs2.rm(orgPath, { recursive: true });
+          await fs3__default.rm(orgPath, { recursive: true });
           count++;
         }
       }
@@ -2365,7 +2735,7 @@ var CachePersistence = class {
    * Ensure cache directory exists
    */
   async ensureDir() {
-    await fs2.mkdir(this.cacheDir, { recursive: true });
+    await fs3__default.mkdir(this.cacheDir, { recursive: true });
   }
   /**
    * Get cache directory path
@@ -2413,8 +2783,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) {
@@ -2620,13 +2999,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;
   }
   /**
@@ -2745,11 +3129,11 @@ var DEFAULT_SYNC_CONFIG = {
   deleteOrphans: false,
   conflictStrategy: "newest"
 };
-function evaluatePath(path6, rules, direction, defaultExcludes = []) {
+function evaluatePath(path7, rules, direction, defaultExcludes = []) {
   for (const pattern of defaultExcludes) {
-    if (micromatch3.isMatch(path6, pattern)) {
+    if (micromatch3.isMatch(path7, pattern)) {
       return {
-        path: path6,
+        path: path7,
         shouldSync: false,
         reason: `Excluded by default pattern: ${pattern}`
       };
@@ -2760,9 +3144,9 @@ function evaluatePath(path6, rules, direction, defaultExcludes = []) {
     if (rule.direction && rule.direction !== direction) {
       continue;
     }
-    if (micromatch3.isMatch(path6, rule.pattern)) {
+    if (micromatch3.isMatch(path7, rule.pattern)) {
       return {
-        path: path6,
+        path: path7,
         shouldSync: rule.include,
         matchedRule: rule,
         reason: rule.include ? `Included by rule: ${rule.pattern}` : `Excluded by rule: ${rule.pattern}`
@@ -2770,21 +3154,21 @@ function evaluatePath(path6, rules, direction, defaultExcludes = []) {
     }
   }
   return {
-    path: path6,
+    path: path7,
     shouldSync: true,
     reason: "No matching rule, included by default"
   };
 }
 function evaluatePaths(paths, rules, direction, defaultExcludes = []) {
   const results = /* @__PURE__ */ new Map();
-  for (const path6 of paths) {
-    results.set(path6, evaluatePath(path6, rules, direction, defaultExcludes));
+  for (const path7 of paths) {
+    results.set(path7, evaluatePath(path7, rules, direction, defaultExcludes));
   }
   return results;
 }
 function filterSyncablePaths(paths, rules, direction, defaultExcludes = []) {
   return paths.filter(
-    (path6) => evaluatePath(path6, rules, direction, defaultExcludes).shouldSync
+    (path7) => evaluatePath(path7, rules, direction, defaultExcludes).shouldSync
   );
 }
 function createRulesFromPatterns(include = [], exclude = []) {
@@ -3050,8 +3434,8 @@ async function scanCodexWithRouting(options) {
   for (const filePath of allFiles) {
     totalScanned++;
     try {
-      const fullPath = path3.join(codexDir, filePath);
-      const stats = await fs2.stat(fullPath);
+      const fullPath = path3__default.join(codexDir, filePath);
+      const stats = await fs3__default.stat(fullPath);
       if (stats.size > maxFileSize) {
         totalSkipped++;
         errors.push({
@@ -3147,10 +3531,10 @@ async function listAllFilesRecursive(dirPath) {
   const files = [];
   async function scanDirectory(currentPath, relativePath = "") {
     try {
-      const entries = await fs2.readdir(currentPath, { withFileTypes: true });
+      const entries = await fs3__default.readdir(currentPath, { withFileTypes: true });
       for (const entry of entries) {
-        const entryPath = path3.join(currentPath, entry.name);
-        const entryRelativePath = relativePath ? path3.join(relativePath, entry.name) : entry.name;
+        const entryPath = path3__default.join(currentPath, entry.name);
+        const entryRelativePath = relativePath ? path3__default.join(relativePath, entry.name) : entry.name;
         if (entry.isDirectory()) {
           if (entry.name.startsWith(".") || entry.name === "node_modules" || entry.name === "dist" || entry.name === "build") {
             continue;
@@ -3389,17 +3773,17 @@ var SyncManager = class {
         if (file.operation === "create" || file.operation === "update") {
           const sourcePath = `${plan.source}/${file.path}`;
           const targetPath = `${plan.target}/${file.path}`;
-          const fs4 = await import('fs/promises');
-          const path6 = await import('path');
-          const targetDir = path6.dirname(targetPath);
-          await fs4.mkdir(targetDir, { recursive: true });
-          await fs4.copyFile(sourcePath, targetPath);
+          const fs5 = await import('fs/promises');
+          const path7 = await import('path');
+          const targetDir = path7.dirname(targetPath);
+          await fs5.mkdir(targetDir, { recursive: true });
+          await fs5.copyFile(sourcePath, targetPath);
           synced++;
         } else if (file.operation === "delete") {
           const targetPath = `${plan.target}/${file.path}`;
-          const fs4 = await import('fs/promises');
+          const fs5 = await import('fs/promises');
           try {
-            await fs4.unlink(targetPath);
+            await fs5.unlink(targetPath);
             synced++;
           } catch (error) {
             if (error.code !== "ENOENT") {
@@ -3454,15 +3838,15 @@ var SyncManager = class {
   /**
    * Get sync status for a file
    */
-  async getFileStatus(path6) {
+  async getFileStatus(path7) {
     const manifest = await this.loadManifest();
-    return manifest?.entries[path6] ?? null;
+    return manifest?.entries[path7] ?? null;
   }
   /**
    * Check if a file is synced
    */
-  async isFileSynced(path6) {
-    const status = await this.getFileStatus(path6);
+  async isFileSynced(path7) {
+    const status = await this.getFileStatus(path7);
     return status !== null;
   }
   /**
@@ -3546,19 +3930,19 @@ function ruleMatchesContext(rule, context) {
   }
   return true;
 }
-function ruleMatchesPath(rule, path6) {
-  return micromatch3.isMatch(path6, rule.pattern);
+function ruleMatchesPath(rule, path7) {
+  return micromatch3.isMatch(path7, rule.pattern);
 }
 function ruleMatchesAction(rule, action) {
   return rule.actions.includes(action);
 }
-function evaluatePermission(path6, action, context, config) {
+function evaluatePermission(path7, action, context, config) {
   const sortedRules = [...config.rules].sort((a, b) => (b.priority ?? 0) - (a.priority ?? 0));
   for (const rule of sortedRules) {
     if (!ruleMatchesContext(rule, context)) {
       continue;
     }
-    if (!ruleMatchesPath(rule, path6)) {
+    if (!ruleMatchesPath(rule, path7)) {
       continue;
     }
     if (!ruleMatchesAction(rule, action)) {
@@ -3577,24 +3961,24 @@ function evaluatePermission(path6, action, context, config) {
     reason: config.defaultAllow ? "Allowed by default" : "Denied by default"
   };
 }
-function isAllowed(path6, action, context, config) {
-  const result = evaluatePermission(path6, action, context, config);
+function isAllowed(path7, action, context, config) {
+  const result = evaluatePermission(path7, action, context, config);
   return result.allowed;
 }
-function hasPermission(path6, action, requiredLevel, context, config) {
-  const result = evaluatePermission(path6, action, context, config);
+function hasPermission(path7, action, requiredLevel, context, config) {
+  const result = evaluatePermission(path7, action, context, config);
   return levelGrants(result.level, requiredLevel);
 }
 function evaluatePermissions(paths, action, context, config) {
   const results = /* @__PURE__ */ new Map();
-  for (const path6 of paths) {
-    results.set(path6, evaluatePermission(path6, action, context, config));
+  for (const path7 of paths) {
+    results.set(path7, evaluatePermission(path7, action, context, config));
   }
   return results;
 }
 function filterByPermission(paths, action, context, config, requiredLevel = "read") {
-  return paths.filter((path6) => {
-    const result = evaluatePermission(path6, action, context, config);
+  return paths.filter((path7) => {
+    const result = evaluatePermission(path7, action, context, config);
     return levelGrants(result.level, requiredLevel);
   });
 }
@@ -3685,21 +4069,21 @@ var PermissionManager = class {
   /**
    * Check if an action is allowed for a path
    */
-  isAllowed(path6, action, context) {
-    const result = this.evaluate(path6, action, context);
+  isAllowed(path7, action, context) {
+    const result = this.evaluate(path7, action, context);
     return result.allowed;
   }
   /**
    * Check if a permission level is granted
    */
-  hasPermission(path6, action, requiredLevel, context) {
-    const result = this.evaluate(path6, action, context);
+  hasPermission(path7, action, requiredLevel, context) {
+    const result = this.evaluate(path7, action, context);
     return levelGrants(result.level, requiredLevel);
   }
   /**
    * Evaluate permission for a path and action
    */
-  evaluate(path6, action, context) {
+  evaluate(path7, action, context) {
     const mergedContext = { ...this.defaultContext, ...context };
     if (!this.config.enforced) {
       return {
@@ -3708,7 +4092,7 @@ var PermissionManager = class {
         reason: "Permissions not enforced"
       };
     }
-    return evaluatePermission(path6, action, mergedContext, this.config);
+    return evaluatePermission(path7, action, mergedContext, this.config);
   }
   /**
    * Filter paths by permission
@@ -3811,12 +4195,12 @@ var PermissionManager = class {
   /**
    * Assert permission (throws if denied)
    */
-  assertPermission(path6, action, requiredLevel = "read", context) {
-    const result = this.evaluate(path6, action, context);
+  assertPermission(path7, action, requiredLevel = "read", context) {
+    const result = this.evaluate(path7, action, context);
     if (!levelGrants(result.level, requiredLevel)) {
       throw new PermissionDeniedError(
-        `Permission denied for ${action} on ${path6}: ${result.reason}`,
-        path6,
+        `Permission denied for ${action} on ${path7}: ${result.reason}`,
+        path7,
         action,
         result
       );
@@ -3824,9 +4208,9 @@ var PermissionManager = class {
   }
 };
 var PermissionDeniedError = class extends Error {
-  constructor(message, path6, action, result) {
+  constructor(message, path7, action, result) {
     super(message);
-    this.path = path6;
+    this.path = path7;
     this.action = action;
     this.result = result;
     this.name = "PermissionDeniedError";
@@ -4323,8 +4707,8 @@ function convertToUri(reference, options = {}) {
   const parts = parseReference2(trimmed);
   const org = parts.org || options.defaultOrg || "_";
   const project = parts.project || options.defaultProject || "_";
-  const path6 = parts.path;
-  return `codex://${org}/${project}/${path6}`;
+  const path7 = parts.path;
+  return `codex://${org}/${project}/${path7}`;
 }
 function parseReference2(reference) {
   const trimmed = reference.trim();
@@ -4404,6 +4788,6 @@ function generateReferenceMigrationSummary(results) {
   return lines.join("\n");
 }
 
-export { AutoSyncPatternSchema, BUILT_IN_TYPES, CODEX_URI_PREFIX, CacheManager, CachePersistence, CodexConfigSchema, CodexError, CommonRules, ConfigurationError, CustomTypeSchema, DEFAULT_CACHE_DIR, DEFAULT_FETCH_OPTIONS, DEFAULT_MIGRATION_OPTIONS, DEFAULT_PERMISSION_CONFIG, DEFAULT_SYNC_CONFIG, DEFAULT_TYPE, GitHubStorage, HttpStorage, LEGACY_PATTERNS, LEGACY_REF_PREFIX, LocalStorage, MetadataSchema, PERMISSION_LEVEL_ORDER, PermissionDeniedError, PermissionManager, StorageManager, SyncManager, SyncRulesSchema, TTL, TypeRegistry, TypesConfigSchema, ValidationError, buildUri, calculateCachePath, calculateContentHash, convertLegacyReference, convertLegacyReferences, convertToUri, createCacheEntry, createCacheManager, createCachePersistence, createDefaultRegistry, createEmptyModernConfig, createEmptySyncPlan, createGitHubStorage, createHttpStorage, createLocalStorage, createPermissionManager, createRule, createRulesFromPatterns, createStorageManager, createSyncManager, createSyncPlan, deserializeCacheEntry, detectContentType, detectCurrentProject, detectVersion, estimateSyncTime, evaluatePath, evaluatePaths, evaluatePatterns, evaluatePermission, evaluatePermissions, extendType, extractOrgFromRepoName, extractRawFrontmatter, filterByPatterns, filterByPermission, filterPlanOperations, filterSyncablePaths, findLegacyReferences, formatPlanSummary, generateMigrationReport, generateReferenceMigrationSummary, getBuiltInType, getBuiltInTypeNames, getCacheEntryAge, getCacheEntryStatus, getCurrentContext, getCustomSyncDestinations, getDefaultCacheManager, getDefaultConfig, getDefaultDirectories, getDefaultPermissionManager, getDefaultRules, getDefaultStorageManager, getDirectory, getExtension, getFilename, getMigrationRequirements, getPlanStats, getRelativeCachePath, getRemainingTtl, getTargetRepos, hasContentChanged, hasFrontmatter, hasLegacyReferences, hasPermission as hasPermissionLevel, isBuiltInType, isCacheEntryFresh, isCacheEntryValid, isCurrentProjectUri, isLegacyConfig, isLegacyReference, isModernConfig, isAllowed as isPermissionAllowed, isValidUri, levelGrants, loadConfig, loadCustomTypes, matchAnyPattern, matchPattern, maxLevel, mergeFetchOptions, mergeRules, mergeTypes, migrateConfig, migrateFileReferences, minLevel, needsMigration, parseCustomDestination, parseMetadata, parseReference, parseTtl, resolveOrganization, resolveReference, resolveReferences, ruleMatchesAction, ruleMatchesContext, ruleMatchesPath, sanitizePath, serializeCacheEntry, setDefaultCacheManager, setDefaultPermissionManager, setDefaultStorageManager, shouldSyncToRepo, summarizeEvaluations, touchCacheEntry, validateCustomTypes, validateMetadata, validateMigratedConfig, validateOrg, validatePath, validateRules2 as validatePermissionRules, validateProject, validateRules, validateUri };
+export { AutoSyncPatternSchema, BUILT_IN_TYPES, CODEX_URI_PREFIX, CacheManager, CachePersistence, CodexConfigSchema, CodexError, CommonRules, ConfigurationError, CustomTypeSchema, DEFAULT_CACHE_DIR, DEFAULT_FETCH_OPTIONS, DEFAULT_MIGRATION_OPTIONS, DEFAULT_PERMISSION_CONFIG, DEFAULT_SYNC_CONFIG, DEFAULT_TYPE, FilePluginFileNotFoundError, FilePluginStorage, GitHubStorage, HttpStorage, LEGACY_PATTERNS, LEGACY_REF_PREFIX, LocalStorage, MetadataSchema, PERMISSION_LEVEL_ORDER, PermissionDeniedError, PermissionManager, StorageManager, SyncManager, SyncRulesSchema, TTL, TypeRegistry, TypesConfigSchema, ValidationError, buildUri, calculateCachePath, calculateContentHash, convertLegacyReference, convertLegacyReferences, convertToUri, createCacheEntry, createCacheManager, createCachePersistence, createDefaultRegistry, createEmptyModernConfig, createEmptySyncPlan, createGitHubStorage, createHttpStorage, createLocalStorage, createPermissionManager, createRule, createRulesFromPatterns, createStorageManager, createSyncManager, createSyncPlan, deserializeCacheEntry, detectContentType, detectCurrentProject, detectVersion, estimateSyncTime, evaluatePath, evaluatePaths, evaluatePatterns, evaluatePermission, evaluatePermissions, extendType, extractOrgFromRepoName, extractRawFrontmatter, filterByPatterns, filterByPermission, filterPlanOperations, filterSyncablePaths, findLegacyReferences, formatPlanSummary, generateMigrationReport, generateReferenceMigrationSummary, getBuiltInType, getBuiltInTypeNames, getCacheEntryAge, getCacheEntryStatus, getCurrentContext, getCustomSyncDestinations, getDefaultCacheManager, getDefaultConfig, getDefaultDirectories, getDefaultPermissionManager, getDefaultRules, getDefaultStorageManager, getDirectory, getExtension, getFilename, getMigrationRequirements, getPlanStats, getRelativeCachePath, getRemainingTtl, getTargetRepos, hasContentChanged, hasFrontmatter, hasLegacyReferences, hasPermission as hasPermissionLevel, isBuiltInType, isCacheEntryFresh, isCacheEntryValid, isCurrentProjectUri, isLegacyConfig, isLegacyReference, isModernConfig, isAllowed as isPermissionAllowed, isValidUri, levelGrants, loadConfig, loadCustomTypes, matchAnyPattern, matchPattern, maxLevel, mergeFetchOptions, mergeRules, mergeTypes, migrateConfig, migrateFileReferences, minLevel, needsMigration, parseCustomDestination, parseMetadata, parseReference, parseTtl, resolveOrganization, resolveReference, resolveReferences, ruleMatchesAction, ruleMatchesContext, ruleMatchesPath, sanitizePath, serializeCacheEntry, setDefaultCacheManager, setDefaultPermissionManager, setDefaultStorageManager, shouldSyncToRepo, summarizeEvaluations, touchCacheEntry, validateCustomTypes, validateMetadata, validateMigratedConfig, validateOrg, validatePath, validateRules2 as validatePermissionRules, validateProject, validateRules, validateUri };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map