@fractary/codex 0.8.0 → 0.9.1

package/dist/index.cjs

@@ -5,15 +5,33 @@ var path3 = require('path');
 var child_process = require('child_process');
 var zod = require('zod');
 var yaml = require('js-yaml');
-var fs2 = require('fs/promises');
+var fs3 = require('fs/promises');
 var util = require('util');
 
 function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
 
+function _interopNamespace(e) {
+  if (e && e.__esModule) return e;
+  var n = Object.create(null);
+  if (e) {
+    Object.keys(e).forEach(function (k) {
+      if (k !== 'default') {
+        var d = Object.getOwnPropertyDescriptor(e, k);
+        Object.defineProperty(n, k, d.get ? d : {
+          enumerable: true,
+          get: function () { return e[k]; }
+        });
+      }
+    });
+  }
+  n.default = e;
+  return Object.freeze(n);
+}
+
 var micromatch3__default = /*#__PURE__*/_interopDefault(micromatch3);
-var path3__default = /*#__PURE__*/_interopDefault(path3);
+var path3__namespace = /*#__PURE__*/_interopNamespace(path3);
 var yaml__default = /*#__PURE__*/_interopDefault(yaml);
-var fs2__default = /*#__PURE__*/_interopDefault(fs2);
+var fs3__namespace = /*#__PURE__*/_interopNamespace(fs3);
 
 var __defProp = Object.defineProperty;
 var __getOwnPropNames = Object.getOwnPropertyNames;
@@ -170,7 +188,7 @@ function validatePath(filePath) {
       return false;
     }
   }
-  const normalized = path3__default.default.normalize(filePath);
+  const normalized = path3__namespace.default.normalize(filePath);
   if (normalized.startsWith("..") || normalized.includes("/../") || normalized.includes("\\..\\")) {
     return false;
   }
@@ -188,7 +206,7 @@ function sanitizePath(filePath) {
   }
   sanitized = sanitized.replace(/^\/+/, "");
   sanitized = sanitized.replace(/^~\//, "");
-  sanitized = path3__default.default.normalize(sanitized);
+  sanitized = path3__namespace.default.normalize(sanitized);
   sanitized = sanitized.replace(/\.\.\//g, "").replace(/\.\./g, "");
   sanitized = sanitized.replace(/^\.\//, "");
   sanitized = sanitized.replace(/\0/g, "");
@@ -289,10 +307,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;
@@ -363,7 +381,7 @@ function getCurrentContext(options = {}) {
   return detectCurrentProject(options.cwd);
 }
 function calculateCachePath(org, project, filePath, cacheDir) {
-  return path3__default.default.join(cacheDir, org, project, filePath);
+  return path3__namespace.default.join(cacheDir, org, project, filePath);
 }
 function resolveReference(uri, options = {}) {
   const parsed = parseReference(uri);
@@ -372,7 +390,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__default.default.join(cacheDir, parsed.org, parsed.project);
+  const cachePath = parsed.path ? calculateCachePath(parsed.org, parsed.project, parsed.path, cacheDir) : path3__namespace.default.join(cacheDir, parsed.org, parsed.project);
   const isCurrentProject = currentContext.org === parsed.org && currentContext.project === parsed.project;
   const resolved = {
     ...parsed,
@@ -381,9 +399,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__namespace.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__namespace.default.join(basePath, pathWithoutSource)
+      };
+    }
+  }
+  return null;
+}
 function resolveReferences(uris, options = {}) {
   return uris.map((uri) => resolveReference(uri, options)).filter((r) => r !== null);
 }
@@ -397,9 +451,9 @@ function getRelativeCachePath(uri) {
     return null;
   }
   if (parsed.path) {
-    return path3__default.default.join(parsed.org, parsed.project, parsed.path);
+    return path3__namespace.default.join(parsed.org, parsed.project, parsed.path);
   }
-  return path3__default.default.join(parsed.org, parsed.project);
+  return path3__namespace.default.join(parsed.org, parsed.project);
 }
 
 // src/types/built-in.ts
@@ -854,8 +908,40 @@ var ArchiveProjectConfigSchema = zod.z.object({
 var ArchiveConfigSchema = zod.z.object({
   projects: zod.z.record(ArchiveProjectConfigSchema)
 });
+var GitHubAuthConfigSchema = zod.z.object({
+  /** Default token environment variable name (default: GITHUB_TOKEN) */
+  default_token_env: zod.z.string().optional(),
+  /** Fallback to public access if authentication fails */
+  fallback_to_public: zod.z.boolean().optional()
+});
+var AuthConfigSchema = zod.z.object({
+  /** GitHub authentication configuration */
+  github: GitHubAuthConfigSchema.optional()
+});
+var SourceConfigSchema = zod.z.object({
+  /** Source type */
+  type: zod.z.enum(["github", "s3", "http", "local"]),
+  /** Environment variable containing the authentication token */
+  token_env: zod.z.string().optional(),
+  /** Direct token value (not recommended, use token_env instead) */
+  token: zod.z.string().optional(),
+  /** Branch to fetch from (for GitHub sources) */
+  branch: zod.z.string().optional(),
+  /** Base URL (for HTTP sources) */
+  base_url: zod.z.string().optional(),
+  /** Bucket name (for S3 sources) */
+  bucket: zod.z.string().optional(),
+  /** Prefix/path within bucket (for S3 sources) */
+  prefix: zod.z.string().optional()
+});
+var DependencyConfigSchema = zod.z.object({
+  /** Sources within this dependency */
+  sources: zod.z.record(SourceConfigSchema)
+});
 var CodexConfigSchema = zod.z.object({
   organizationSlug: zod.z.string(),
+  /** Project name (optional) */
+  project: zod.z.string().optional(),
   directories: zod.z.object({
     source: zod.z.string().optional(),
     target: zod.z.string().optional(),
@@ -865,8 +951,47 @@ var CodexConfigSchema = zod.z.object({
   // Directional sync configuration
   sync: DirectionalSyncSchema.optional(),
   // Archive configuration
-  archive: ArchiveConfigSchema.optional()
+  archive: ArchiveConfigSchema.optional(),
+  // Authentication configuration
+  auth: AuthConfigSchema.optional(),
+  // Dependencies configuration (external projects)
+  dependencies: zod.z.record(DependencyConfigSchema).optional()
 }).strict();
+var FileSourceSchema = zod.z.object({
+  type: zod.z.enum(["s3", "r2", "gcs", "local"]),
+  bucket: zod.z.string().optional(),
+  prefix: zod.z.string().optional(),
+  region: zod.z.string().optional(),
+  local: zod.z.object({
+    base_path: zod.z.string()
+  }),
+  push: zod.z.object({
+    compress: zod.z.boolean().optional(),
+    keep_local: zod.z.boolean().optional()
+  }).optional(),
+  auth: zod.z.object({
+    profile: zod.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 = zod.z.object({
+  schema_version: zod.z.string(),
+  sources: zod.z.record(FileSourceSchema)
+});
+zod.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;
@@ -1196,18 +1321,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;
@@ -1243,8 +1368,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",
@@ -1304,19 +1429,19 @@ var LocalStorage = class {
     if (!reference.localPath) {
       throw new Error(`No local path for reference: ${reference.uri}`);
     }
-    const fullPath = path3__default.default.isAbsolute(reference.localPath) ? reference.localPath : path3__default.default.join(this.baseDir, reference.localPath);
+    const fullPath = path3__namespace.default.isAbsolute(reference.localPath) ? reference.localPath : path3__namespace.default.join(this.baseDir, reference.localPath);
     try {
-      await fs2__default.default.access(fullPath);
+      await fs3__namespace.default.access(fullPath);
     } catch {
       throw new Error(`File not found: ${fullPath}`);
     }
-    const stats = await fs2__default.default.stat(fullPath);
+    const stats = await fs3__namespace.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__default.default.readFile(fullPath);
+    const content = await fs3__namespace.default.readFile(fullPath);
     return {
       content,
       contentType: detectContentType(reference.localPath),
@@ -1335,9 +1460,9 @@ var LocalStorage = class {
     if (!reference.localPath) {
       return false;
     }
-    const fullPath = path3__default.default.isAbsolute(reference.localPath) ? reference.localPath : path3__default.default.join(this.baseDir, reference.localPath);
+    const fullPath = path3__namespace.default.isAbsolute(reference.localPath) ? reference.localPath : path3__namespace.default.join(this.baseDir, reference.localPath);
     try {
-      await fs2__default.default.access(fullPath);
+      await fs3__namespace.default.access(fullPath);
       return true;
     } catch {
       return false;
@@ -1347,24 +1472,24 @@ var LocalStorage = class {
    * Read file content as string
    */
   async readText(filePath) {
-    const fullPath = path3__default.default.isAbsolute(filePath) ? filePath : path3__default.default.join(this.baseDir, filePath);
-    return fs2__default.default.readFile(fullPath, "utf-8");
+    const fullPath = path3__namespace.default.isAbsolute(filePath) ? filePath : path3__namespace.default.join(this.baseDir, filePath);
+    return fs3__namespace.default.readFile(fullPath, "utf-8");
   }
   /**
    * Write content to file
    */
   async write(filePath, content) {
-    const fullPath = path3__default.default.isAbsolute(filePath) ? filePath : path3__default.default.join(this.baseDir, filePath);
-    await fs2__default.default.mkdir(path3__default.default.dirname(fullPath), { recursive: true });
-    await fs2__default.default.writeFile(fullPath, content);
+    const fullPath = path3__namespace.default.isAbsolute(filePath) ? filePath : path3__namespace.default.join(this.baseDir, filePath);
+    await fs3__namespace.default.mkdir(path3__namespace.default.dirname(fullPath), { recursive: true });
+    await fs3__namespace.default.writeFile(fullPath, content);
   }
   /**
    * Delete a file
    */
   async delete(filePath) {
-    const fullPath = path3__default.default.isAbsolute(filePath) ? filePath : path3__default.default.join(this.baseDir, filePath);
+    const fullPath = path3__namespace.default.isAbsolute(filePath) ? filePath : path3__namespace.default.join(this.baseDir, filePath);
     try {
-      await fs2__default.default.unlink(fullPath);
+      await fs3__namespace.default.unlink(fullPath);
       return true;
     } catch {
       return false;
@@ -1374,10 +1499,10 @@ var LocalStorage = class {
    * List files in a directory
    */
   async list(dirPath) {
-    const fullPath = path3__default.default.isAbsolute(dirPath) ? dirPath : path3__default.default.join(this.baseDir, dirPath);
+    const fullPath = path3__namespace.default.isAbsolute(dirPath) ? dirPath : path3__namespace.default.join(this.baseDir, dirPath);
     try {
-      const entries = await fs2__default.default.readdir(fullPath, { withFileTypes: true });
-      return entries.filter((e) => e.isFile()).map((e) => path3__default.default.join(dirPath, e.name));
+      const entries = await fs3__namespace.default.readdir(fullPath, { withFileTypes: true });
+      return entries.filter((e) => e.isFile()).map((e) => path3__namespace.default.join(dirPath, e.name));
     } catch {
       return [];
     }
@@ -1722,6 +1847,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__namespace.isAbsolute(reference.localPath) ? path3__namespace.resolve(reference.localPath) : path3__namespace.resolve(this.baseDir, reference.localPath);
+    const source = this.sourceResolver.resolveSource(reference.filePluginSource);
+    if (source) {
+      const allowedDir = path3__namespace.resolve(this.baseDir, source.localPath);
+      if (!absolutePath.startsWith(allowedDir + path3__namespace.sep) && absolutePath !== allowedDir) {
+        throw new Error(
+          `Path traversal detected: ${reference.localPath} resolves outside allowed directory ${source.localPath}`
+        );
+      }
+    }
+    try {
+      const content = await fs3__namespace.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__namespace.isAbsolute(reference.localPath) ? path3__namespace.resolve(reference.localPath) : path3__namespace.resolve(this.baseDir, reference.localPath);
+    if (reference.filePluginSource) {
+      const source = this.sourceResolver.resolveSource(reference.filePluginSource);
+      if (source) {
+        const allowedDir = path3__namespace.resolve(this.baseDir, source.localPath);
+        if (!absolutePath.startsWith(allowedDir + path3__namespace.sep) && absolutePath !== allowedDir) {
+          return false;
+        }
+      }
+    }
+    try {
+      await fs3__namespace.access(absolutePath);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  /**
+   * Detect content type from file extension
+   */
+  detectContentType(filePath) {
+    const ext = path3__namespace.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 = util.promisify(child_process.execFile);
 async function execFileNoThrow(command, args = [], options) {
   try {
@@ -1871,10 +2290,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";
   }
   /**
@@ -1885,9 +2304,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;
       }
     }
@@ -1896,14 +2315,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);
   }
 };
 
@@ -1911,14 +2330,61 @@ var S3ArchiveStorage = class {
 var StorageManager = class {
   providers = /* @__PURE__ */ new Map();
   priority;
+  codexConfig;
   constructor(config = {}) {
+    this.codexConfig = config.codexConfig;
     this.providers.set("local", new LocalStorage(config.local));
     this.providers.set("github", new GitHubStorage(config.github));
     this.providers.set("http", new HttpStorage(config.http));
     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"]);
+  }
+  /**
+   * Resolve authentication token for a reference
+   *
+   * Looks up dependency-specific authentication or falls back to default
+   */
+  resolveToken(reference) {
+    if (!this.codexConfig) {
+      return void 0;
+    }
+    const dependencyKey = `${reference.org}/${reference.project}`;
+    if (this.codexConfig.dependencies?.[dependencyKey]) {
+      const dependency = this.codexConfig.dependencies[dependencyKey];
+      for (const [, sourceConfig] of Object.entries(dependency.sources)) {
+        if (sourceConfig.type === "github") {
+          if (sourceConfig.token_env) {
+            const token = process.env[sourceConfig.token_env];
+            if (token) {
+              return token;
+            }
+          }
+          if (sourceConfig.token) {
+            return sourceConfig.token;
+          }
+        }
+      }
+    }
+    const defaultTokenEnv = this.codexConfig.auth?.github?.default_token_env || "GITHUB_TOKEN";
+    return process.env[defaultTokenEnv];
+  }
+  /**
+   * Resolve fetch options with authentication
+   *
+   * Merges reference-specific authentication with provided options
+   */
+  resolveFetchOptions(reference, options) {
+    const token = this.resolveToken(reference);
+    return {
+      ...options,
+      token: options?.token || token
+      // Explicit option overrides resolved token
+    };
   }
   /**
    * Register a custom storage provider
@@ -1960,8 +2426,10 @@ var StorageManager = class {
    * Fetch content for a reference
    *
    * Tries providers in priority order until one succeeds.
+   * Automatically resolves authentication based on dependency configuration.
    */
   async fetch(reference, options) {
+    const resolvedOptions = this.resolveFetchOptions(reference, options);
     const errors = [];
     for (const type of this.priority) {
       const provider = this.providers.get(type);
@@ -1969,7 +2437,7 @@ var StorageManager = class {
         continue;
       }
       try {
-        return await provider.fetch(reference, options);
+        return await provider.fetch(reference, resolvedOptions);
       } catch (error) {
         errors.push(error instanceof Error ? error : new Error(String(error)));
       }
@@ -1990,15 +2458,17 @@ var StorageManager = class {
    * Check if content exists for a reference
    *
    * Returns true if any provider reports the content exists.
+   * Automatically resolves authentication based on dependency configuration.
    */
   async exists(reference, options) {
+    const resolvedOptions = this.resolveFetchOptions(reference, options);
     for (const type of this.priority) {
       const provider = this.providers.get(type);
       if (!provider || !provider.canHandle(reference)) {
         continue;
       }
       try {
-        if (await provider.exists(reference, options)) {
+        if (await provider.exists(reference, resolvedOptions)) {
           return true;
         }
       } catch {
@@ -2018,6 +2488,8 @@ var StorageManager = class {
   }
   /**
    * Fetch multiple references in parallel
+   *
+   * Automatically resolves authentication for each reference based on dependency configuration.
    */
   async fetchMany(references, options) {
     const results = /* @__PURE__ */ new Map();
@@ -2158,7 +2630,7 @@ var CachePersistence = class {
     }
     const [, org, project, filePath] = match;
     const relativePath = filePath || "index";
-    return path3__default.default.join(this.cacheDir, org, project, relativePath + this.extension);
+    return path3__namespace.default.join(this.cacheDir, org, project, relativePath + this.extension);
   }
   /**
    * Get the metadata file path for a URI
@@ -2174,8 +2646,8 @@ var CachePersistence = class {
     const metadataPath = this.getMetadataPath(uri);
     try {
       const [metadataJson, content] = await Promise.all([
-        fs2__default.default.readFile(metadataPath, "utf-8"),
-        fs2__default.default.readFile(cachePath)
+        fs3__namespace.default.readFile(metadataPath, "utf-8"),
+        fs3__namespace.default.readFile(cachePath)
       ]);
       const metadata = JSON.parse(metadataJson);
       return {
@@ -2195,32 +2667,32 @@ var CachePersistence = class {
   async write(entry) {
     const cachePath = this.getCachePath(entry.metadata.uri);
     const metadataPath = this.getMetadataPath(entry.metadata.uri);
-    await fs2__default.default.mkdir(path3__default.default.dirname(cachePath), { recursive: true });
+    await fs3__namespace.default.mkdir(path3__namespace.default.dirname(cachePath), { recursive: true });
     if (this.atomicWrites) {
       const tempCachePath = cachePath + ".tmp";
       const tempMetadataPath = metadataPath + ".tmp";
       try {
         await Promise.all([
-          fs2__default.default.writeFile(tempCachePath, entry.content),
-          fs2__default.default.writeFile(tempMetadataPath, JSON.stringify(entry.metadata, null, 2))
+          fs3__namespace.default.writeFile(tempCachePath, entry.content),
+          fs3__namespace.default.writeFile(tempMetadataPath, JSON.stringify(entry.metadata, null, 2))
         ]);
         await Promise.all([
-          fs2__default.default.rename(tempCachePath, cachePath),
-          fs2__default.default.rename(tempMetadataPath, metadataPath)
+          fs3__namespace.default.rename(tempCachePath, cachePath),
+          fs3__namespace.default.rename(tempMetadataPath, metadataPath)
         ]);
       } catch (error) {
         await Promise.all([
-          fs2__default.default.unlink(tempCachePath).catch(() => {
+          fs3__namespace.default.unlink(tempCachePath).catch(() => {
           }),
-          fs2__default.default.unlink(tempMetadataPath).catch(() => {
+          fs3__namespace.default.unlink(tempMetadataPath).catch(() => {
           })
         ]);
         throw error;
       }
     } else {
       await Promise.all([
-        fs2__default.default.writeFile(cachePath, entry.content),
-        fs2__default.default.writeFile(metadataPath, JSON.stringify(entry.metadata, null, 2))
+        fs3__namespace.default.writeFile(cachePath, entry.content),
+        fs3__namespace.default.writeFile(metadataPath, JSON.stringify(entry.metadata, null, 2))
       ]);
     }
   }
@@ -2231,7 +2703,7 @@ var CachePersistence = class {
     const cachePath = this.getCachePath(uri);
     const metadataPath = this.getMetadataPath(uri);
     try {
-      await Promise.all([fs2__default.default.unlink(cachePath), fs2__default.default.unlink(metadataPath)]);
+      await Promise.all([fs3__namespace.default.unlink(cachePath), fs3__namespace.default.unlink(metadataPath)]);
       return true;
     } catch (error) {
       if (error.code === "ENOENT") {
@@ -2246,7 +2718,7 @@ var CachePersistence = class {
   async exists(uri) {
     const cachePath = this.getCachePath(uri);
     try {
-      await fs2__default.default.access(cachePath);
+      await fs3__namespace.default.access(cachePath);
       return true;
     } catch {
       return false;
@@ -2258,20 +2730,20 @@ var CachePersistence = class {
   async list() {
     const uris = [];
     try {
-      const orgs = await fs2__default.default.readdir(this.cacheDir);
+      const orgs = await fs3__namespace.default.readdir(this.cacheDir);
       for (const org of orgs) {
-        const orgPath = path3__default.default.join(this.cacheDir, org);
-        const orgStat = await fs2__default.default.stat(orgPath);
+        const orgPath = path3__namespace.default.join(this.cacheDir, org);
+        const orgStat = await fs3__namespace.default.stat(orgPath);
         if (!orgStat.isDirectory()) continue;
-        const projects = await fs2__default.default.readdir(orgPath);
+        const projects = await fs3__namespace.default.readdir(orgPath);
         for (const project of projects) {
-          const projectPath = path3__default.default.join(orgPath, project);
-          const projectStat = await fs2__default.default.stat(projectPath);
+          const projectPath = path3__namespace.default.join(orgPath, project);
+          const projectStat = await fs3__namespace.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__default.default.relative(projectPath, file);
+              const relativePath = path3__namespace.default.relative(projectPath, file);
               const filePath = relativePath.slice(0, -this.extension.length);
               uris.push(`codex://${org}/${project}/${filePath}`);
             }
@@ -2291,9 +2763,9 @@ var CachePersistence = class {
    */
   async listFilesRecursive(dir) {
     const files = [];
-    const entries = await fs2__default.default.readdir(dir, { withFileTypes: true });
+    const entries = await fs3__namespace.default.readdir(dir, { withFileTypes: true });
     for (const entry of entries) {
-      const fullPath = path3__default.default.join(dir, entry.name);
+      const fullPath = path3__namespace.default.join(dir, entry.name);
       if (entry.isDirectory()) {
         files.push(...await this.listFilesRecursive(fullPath));
       } else if (entry.isFile()) {
@@ -2308,12 +2780,12 @@ var CachePersistence = class {
   async clear() {
     let count = 0;
     try {
-      const orgs = await fs2__default.default.readdir(this.cacheDir);
+      const orgs = await fs3__namespace.default.readdir(this.cacheDir);
       for (const org of orgs) {
-        const orgPath = path3__default.default.join(this.cacheDir, org);
-        const stat = await fs2__default.default.stat(orgPath);
+        const orgPath = path3__namespace.default.join(this.cacheDir, org);
+        const stat = await fs3__namespace.default.stat(orgPath);
         if (stat.isDirectory()) {
-          await fs2__default.default.rm(orgPath, { recursive: true });
+          await fs3__namespace.default.rm(orgPath, { recursive: true });
           count++;
         }
       }
@@ -2374,7 +2846,7 @@ var CachePersistence = class {
    * Ensure cache directory exists
    */
   async ensureDir() {
-    await fs2__default.default.mkdir(this.cacheDir, { recursive: true });
+    await fs3__namespace.default.mkdir(this.cacheDir, { recursive: true });
   }
   /**
    * Get cache directory path
@@ -2422,8 +2894,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) {
@@ -2629,13 +3110,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;
   }
   /**
@@ -2754,11 +3240,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__default.default.isMatch(path6, pattern)) {
+    if (micromatch3__default.default.isMatch(path7, pattern)) {
       return {
-        path: path6,
+        path: path7,
         shouldSync: false,
         reason: `Excluded by default pattern: ${pattern}`
       };
@@ -2769,9 +3255,9 @@ function evaluatePath(path6, rules, direction, defaultExcludes = []) {
     if (rule.direction && rule.direction !== direction) {
       continue;
     }
-    if (micromatch3__default.default.isMatch(path6, rule.pattern)) {
+    if (micromatch3__default.default.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}`
@@ -2779,21 +3265,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 = []) {
@@ -3059,8 +3545,8 @@ async function scanCodexWithRouting(options) {
   for (const filePath of allFiles) {
     totalScanned++;
     try {
-      const fullPath = path3__default.default.join(codexDir, filePath);
-      const stats = await fs2__default.default.stat(fullPath);
+      const fullPath = path3__namespace.default.join(codexDir, filePath);
+      const stats = await fs3__namespace.default.stat(fullPath);
       if (stats.size > maxFileSize) {
         totalSkipped++;
         errors.push({
@@ -3156,10 +3642,10 @@ async function listAllFilesRecursive(dirPath) {
   const files = [];
   async function scanDirectory(currentPath, relativePath = "") {
     try {
-      const entries = await fs2__default.default.readdir(currentPath, { withFileTypes: true });
+      const entries = await fs3__namespace.default.readdir(currentPath, { withFileTypes: true });
       for (const entry of entries) {
-        const entryPath = path3__default.default.join(currentPath, entry.name);
-        const entryRelativePath = relativePath ? path3__default.default.join(relativePath, entry.name) : entry.name;
+        const entryPath = path3__namespace.default.join(currentPath, entry.name);
+        const entryRelativePath = relativePath ? path3__namespace.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;
@@ -3398,17 +3884,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") {
@@ -3463,15 +3949,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;
   }
   /**
@@ -3555,19 +4041,19 @@ function ruleMatchesContext(rule, context) {
   }
   return true;
 }
-function ruleMatchesPath(rule, path6) {
-  return micromatch3__default.default.isMatch(path6, rule.pattern);
+function ruleMatchesPath(rule, path7) {
+  return micromatch3__default.default.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)) {
@@ -3586,24 +4072,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);
   });
 }
@@ -3694,21 +4180,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 {
@@ -3717,7 +4203,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
@@ -3820,12 +4306,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
       );
@@ -3833,9 +4319,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";
@@ -4332,8 +4818,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();
@@ -4429,6 +4915,8 @@ exports.DEFAULT_MIGRATION_OPTIONS = DEFAULT_MIGRATION_OPTIONS;
 exports.DEFAULT_PERMISSION_CONFIG = DEFAULT_PERMISSION_CONFIG;
 exports.DEFAULT_SYNC_CONFIG = DEFAULT_SYNC_CONFIG;
 exports.DEFAULT_TYPE = DEFAULT_TYPE;
+exports.FilePluginFileNotFoundError = FilePluginFileNotFoundError;
+exports.FilePluginStorage = FilePluginStorage;
 exports.GitHubStorage = GitHubStorage;
 exports.HttpStorage = HttpStorage;
 exports.LEGACY_PATTERNS = LEGACY_PATTERNS;