@fractary/codex 0.2.1 → 0.3.0

package/README.md

@@ -40,7 +40,7 @@ console.log(ref.path)     // 'docs/api-guide.md'
 
 // Create storage and cache managers
 const storage = StorageManager.create()
-const cache = CacheManager.create({ cacheDir: '.codex-cache' })
+const cache = CacheManager.create({ cacheDir: '.fractary/codex/cache' })
 
 // Fetch content with caching
 const content = await cache.get('codex://myorg/docs/api-guide.md')
@@ -80,7 +80,7 @@ const result = await storage.fetch('codex://org/project/file.md')
 import { createCacheManager } from '@fractary/codex'
 
 const cache = createCacheManager({
-  cacheDir: '.codex-cache',
+  cacheDir: '.fractary/codex/cache',
   maxMemorySize: 50 * 1024 * 1024,
   defaultTtl: 3600
 })
@@ -96,7 +96,7 @@ import { createMcpServer } from '@fractary/codex'
 const server = createMcpServer({
   name: 'codex',
   version: '1.0.0',
-  cacheDir: '.codex-cache'
+  cacheDir: '.fractary/codex/cache'
 })
 
 await server.start()
@@ -226,12 +226,9 @@ MIT - see [LICENSE](LICENSE)
 
 ## Documentation
 
-- [Command Reference](../../docs/guides/command-reference.md) - Complete command reference for all interfaces
-- [API Reference](../../docs/guides/api-reference.md) - Complete API documentation
 - [CLI Integration Guide](../../docs/guides/cli-integration.md) - How to integrate into CLI applications
+- [API Reference](../../docs/guides/api-reference.md) - Complete API documentation
 - [Configuration Guide](../../docs/guides/configuration.md) - Configuration reference
-- [Naming Conventions](../../docs/guides/naming-conventions.md) - Naming standards across all interfaces
-- [MCP Migration Guide](../../docs/guides/mcp-migration-guide.md) - Migrating to new MCP tool names
 - [Troubleshooting](../../docs/guides/troubleshooting.md) - Common issues and solutions
 - [Examples](../../docs/examples/) - Real-world usage patterns
 

package/dist/index.cjs

@@ -185,10 +185,10 @@ function parseReference(uri, options = {}) {
     path: filePath
   };
 }
-function buildUri(org, project, path5) {
+function buildUri(org, project, path6) {
   const base = `${CODEX_URI_PREFIX}${org}/${project}`;
-  if (path5) {
-    const cleanPath = path5.startsWith("/") ? path5.slice(1) : path5;
+  if (path6) {
+    const cleanPath = path6.startsWith("/") ? path6.slice(1) : path6;
     return `${base}/${cleanPath}`;
   }
   return base;
@@ -226,7 +226,7 @@ function getDirectory(uri) {
   }
   return parsed.path.slice(0, lastSlash);
 }
-var DEFAULT_CACHE_DIR = ".fractary/plugins/codex/cache";
+var DEFAULT_CACHE_DIR = ".fractary/codex/cache";
 function detectCurrentProject(cwd) {
   try {
     const options = cwd ? { cwd, encoding: "utf-8" } : { encoding: "utf-8" };
@@ -1066,18 +1066,18 @@ function parseCustomDestination(value) {
     );
   }
   const repo = value.substring(0, colonIndex).trim();
-  const path5 = value.substring(colonIndex + 1).trim();
+  const path6 = value.substring(colonIndex + 1).trim();
   if (!repo) {
     throw new ValidationError(
       `Invalid custom destination: repository name cannot be empty in "${value}"`
     );
   }
-  if (!path5) {
+  if (!path6) {
     throw new ValidationError(
       `Invalid custom destination: path cannot be empty in "${value}"`
     );
   }
-  return { repo, path: path5 };
+  return { repo, path: path6 };
 }
 function getCustomSyncDestinations(metadata) {
   const customDestinations = metadata.codex_sync_custom;
@@ -1113,8 +1113,8 @@ function mergeFetchOptions(options) {
     ...options
   };
 }
-function detectContentType(path5) {
-  const ext = path5.split(".").pop()?.toLowerCase();
+function detectContentType(path6) {
+  const ext = path6.split(".").pop()?.toLowerCase();
   const mimeTypes = {
     md: "text/markdown",
     markdown: "text/markdown",
@@ -2437,11 +2437,11 @@ var DEFAULT_SYNC_CONFIG = {
   deleteOrphans: false,
   conflictStrategy: "newest"
 };
-function evaluatePath(path5, rules, direction, defaultExcludes = []) {
+function evaluatePath(path6, rules, direction, defaultExcludes = []) {
   for (const pattern of defaultExcludes) {
-    if (micromatch2__default.default.isMatch(path5, pattern)) {
+    if (micromatch2__default.default.isMatch(path6, pattern)) {
       return {
-        path: path5,
+        path: path6,
         shouldSync: false,
         reason: `Excluded by default pattern: ${pattern}`
       };
@@ -2452,9 +2452,9 @@ function evaluatePath(path5, rules, direction, defaultExcludes = []) {
     if (rule.direction && rule.direction !== direction) {
       continue;
     }
-    if (micromatch2__default.default.isMatch(path5, rule.pattern)) {
+    if (micromatch2__default.default.isMatch(path6, rule.pattern)) {
       return {
-        path: path5,
+        path: path6,
         shouldSync: rule.include,
         matchedRule: rule,
         reason: rule.include ? `Included by rule: ${rule.pattern}` : `Excluded by rule: ${rule.pattern}`
@@ -2462,21 +2462,21 @@ function evaluatePath(path5, rules, direction, defaultExcludes = []) {
     }
   }
   return {
-    path: path5,
+    path: path6,
     shouldSync: true,
     reason: "No matching rule, included by default"
   };
 }
 function evaluatePaths(paths, rules, direction, defaultExcludes = []) {
   const results = /* @__PURE__ */ new Map();
-  for (const path5 of paths) {
-    results.set(path5, evaluatePath(path5, rules, direction, defaultExcludes));
+  for (const path6 of paths) {
+    results.set(path6, evaluatePath(path6, rules, direction, defaultExcludes));
   }
   return results;
 }
 function filterSyncablePaths(paths, rules, direction, defaultExcludes = []) {
   return paths.filter(
-    (path5) => evaluatePath(path5, rules, direction, defaultExcludes).shouldSync
+    (path6) => evaluatePath(path6, rules, direction, defaultExcludes).shouldSync
   );
 }
 function createRulesFromPatterns(include = [], exclude = []) {
@@ -2713,6 +2713,123 @@ function formatBytes(bytes) {
   const i = Math.floor(Math.log(bytes) / Math.log(k));
   return `${parseFloat((bytes / Math.pow(k, i)).toFixed(2))} ${sizes[i]}`;
 }
+async function scanCodexWithRouting(options) {
+  const {
+    codexDir,
+    targetProject,
+    org,
+    rules,
+    storage,
+    skipNoFrontmatter = true,
+    maxFileSize = 10 * 1024 * 1024
+    // 10MB default
+  } = options;
+  const startTime = Date.now();
+  const routedFiles = [];
+  const sourceProjectsSet = /* @__PURE__ */ new Set();
+  const errors = [];
+  let totalScanned = 0;
+  let totalSkipped = 0;
+  const allFiles = await listAllFilesRecursive(codexDir);
+  for (const filePath of allFiles) {
+    totalScanned++;
+    try {
+      if (!filePath.endsWith(".md")) {
+        totalSkipped++;
+        continue;
+      }
+      const fullPath = path3__default.default.join(codexDir, filePath);
+      const stats = await fs2__default.default.stat(fullPath);
+      if (stats.size > maxFileSize) {
+        totalSkipped++;
+        errors.push({
+          path: filePath,
+          error: `File too large (${stats.size} bytes, max: ${maxFileSize})`
+        });
+        continue;
+      }
+      const content = await storage.readText(fullPath);
+      const parseResult = parseMetadata(content, { strict: false });
+      if (skipNoFrontmatter && Object.keys(parseResult.metadata).length === 0) {
+        totalSkipped++;
+        continue;
+      }
+      const sourceProject = extractProjectFromPath(filePath, org);
+      const shouldSync = shouldSyncToRepo({
+        filePath,
+        fileMetadata: parseResult.metadata,
+        targetRepo: targetProject,
+        sourceRepo: sourceProject,
+        rules
+      });
+      if (shouldSync) {
+        const buffer = Buffer.from(content);
+        const hash = calculateContentHash(buffer);
+        routedFiles.push({
+          path: filePath,
+          size: buffer.length,
+          mtime: stats.mtimeMs,
+          hash,
+          metadata: parseResult.metadata,
+          sourceProject
+        });
+        sourceProjectsSet.add(sourceProject);
+      } else {
+        totalSkipped++;
+      }
+    } catch (error) {
+      totalSkipped++;
+      errors.push({
+        path: filePath,
+        error: error instanceof Error ? error.message : String(error)
+      });
+    }
+  }
+  const durationMs = Date.now() - startTime;
+  return {
+    files: routedFiles,
+    stats: {
+      totalScanned,
+      totalMatched: routedFiles.length,
+      totalSkipped,
+      sourceProjects: Array.from(sourceProjectsSet).sort(),
+      durationMs,
+      errors
+    }
+  };
+}
+function extractProjectFromPath(filePath, org) {
+  const normalizedPath = filePath.replace(/\\/g, "/");
+  const withoutOrg = normalizedPath.startsWith(`${org}/`) ? normalizedPath.slice(org.length + 1) : normalizedPath;
+  const firstSlash = withoutOrg.indexOf("/");
+  if (firstSlash === -1) {
+    return withoutOrg;
+  }
+  return withoutOrg.slice(0, firstSlash);
+}
+async function listAllFilesRecursive(dirPath) {
+  const files = [];
+  async function scanDirectory(currentPath, relativePath = "") {
+    try {
+      const entries = await fs2__default.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;
+        if (entry.isDirectory()) {
+          if (entry.name.startsWith(".") || entry.name === "node_modules" || entry.name === "dist" || entry.name === "build") {
+            continue;
+          }
+          await scanDirectory(entryPath, entryRelativePath);
+        } else if (entry.isFile()) {
+          files.push(entryRelativePath);
+        }
+      }
+    } catch {
+    }
+  }
+  await scanDirectory(dirPath);
+  return files;
+}
 
 // src/sync/manager.ts
 var SyncManager = class {
@@ -2805,6 +2922,56 @@ var SyncManager = class {
     plan.estimatedTime = estimateSyncTime(plan);
     return plan;
   }
+  /**
+   * Create a routing-aware sync plan
+   *
+   * Scans entire codex repository and evaluates routing rules to find all files
+   * that should sync to the target project based on codex_sync_include patterns.
+   *
+   * This enables cross-project knowledge sharing where files from multiple
+   * projects can be synced to the target based on their frontmatter metadata.
+   *
+   * @param org - Organization name (e.g., "corthosai")
+   * @param project - Target project name (e.g., "lake.corthonomy.ai")
+   * @param codexDir - Path to codex repository directory
+   * @param options - Sync options
+   * @returns Sync plan with routing metadata
+   *
+   * @example
+   * ```typescript
+   * const plan = await manager.createRoutingAwarePlan(
+   *   'corthosai',
+   *   'lake.corthonomy.ai',
+   *   '/path/to/codex.corthos.ai',
+   *   { direction: 'from-codex' }
+   * )
+   *
+   * console.log(`Found ${plan.totalFiles} files from ${plan.metadata.scannedProjects.length} projects`)
+   * ```
+   */
+  async createRoutingAwarePlan(org, project, codexDir, options) {
+    const routingScan = await scanCodexWithRouting({
+      codexDir,
+      targetProject: project,
+      org,
+      rules: void 0,
+      // Use default routing rules (preventSelfSync, preventCodexSync, etc.)
+      storage: this.localStorage
+    });
+    const sourceFiles = routingScan.files.map((rf) => ({
+      path: rf.path,
+      size: rf.size,
+      mtime: rf.mtime,
+      hash: rf.hash
+    }));
+    const targetFiles = await this.listLocalFiles(process.cwd());
+    const plan = createSyncPlan(sourceFiles, targetFiles, options ?? {}, this.config);
+    plan.estimatedTime = estimateSyncTime(plan);
+    return {
+      ...plan,
+      routingScan
+    };
+  }
   /**
    * Execute a sync plan (dry run)
    *
@@ -2880,15 +3047,15 @@ var SyncManager = class {
   /**
    * Get sync status for a file
    */
-  async getFileStatus(path5) {
+  async getFileStatus(path6) {
     const manifest = await this.loadManifest();
-    return manifest?.entries[path5] ?? null;
+    return manifest?.entries[path6] ?? null;
   }
   /**
    * Check if a file is synced
    */
-  async isFileSynced(path5) {
-    const status = await this.getFileStatus(path5);
+  async isFileSynced(path6) {
+    const status = await this.getFileStatus(path6);
     return status !== null;
   }
   /**
@@ -2972,19 +3139,19 @@ function ruleMatchesContext(rule, context) {
   }
   return true;
 }
-function ruleMatchesPath(rule, path5) {
-  return micromatch2__default.default.isMatch(path5, rule.pattern);
+function ruleMatchesPath(rule, path6) {
+  return micromatch2__default.default.isMatch(path6, rule.pattern);
 }
 function ruleMatchesAction(rule, action) {
   return rule.actions.includes(action);
 }
-function evaluatePermission(path5, action, context, config) {
+function evaluatePermission(path6, 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, path5)) {
+    if (!ruleMatchesPath(rule, path6)) {
       continue;
     }
     if (!ruleMatchesAction(rule, action)) {
@@ -3003,24 +3170,24 @@ function evaluatePermission(path5, action, context, config) {
     reason: config.defaultAllow ? "Allowed by default" : "Denied by default"
   };
 }
-function isAllowed(path5, action, context, config) {
-  const result = evaluatePermission(path5, action, context, config);
+function isAllowed(path6, action, context, config) {
+  const result = evaluatePermission(path6, action, context, config);
   return result.allowed;
 }
-function hasPermission(path5, action, requiredLevel, context, config) {
-  const result = evaluatePermission(path5, action, context, config);
+function hasPermission(path6, action, requiredLevel, context, config) {
+  const result = evaluatePermission(path6, action, context, config);
   return levelGrants(result.level, requiredLevel);
 }
 function evaluatePermissions(paths, action, context, config) {
   const results = /* @__PURE__ */ new Map();
-  for (const path5 of paths) {
-    results.set(path5, evaluatePermission(path5, action, context, config));
+  for (const path6 of paths) {
+    results.set(path6, evaluatePermission(path6, action, context, config));
   }
   return results;
 }
 function filterByPermission(paths, action, context, config, requiredLevel = "read") {
-  return paths.filter((path5) => {
-    const result = evaluatePermission(path5, action, context, config);
+  return paths.filter((path6) => {
+    const result = evaluatePermission(path6, action, context, config);
     return levelGrants(result.level, requiredLevel);
   });
 }
@@ -3111,21 +3278,21 @@ var PermissionManager = class {
   /**
    * Check if an action is allowed for a path
    */
-  isAllowed(path5, action, context) {
-    const result = this.evaluate(path5, action, context);
+  isAllowed(path6, action, context) {
+    const result = this.evaluate(path6, action, context);
     return result.allowed;
   }
   /**
    * Check if a permission level is granted
    */
-  hasPermission(path5, action, requiredLevel, context) {
-    const result = this.evaluate(path5, action, context);
+  hasPermission(path6, action, requiredLevel, context) {
+    const result = this.evaluate(path6, action, context);
     return levelGrants(result.level, requiredLevel);
   }
   /**
    * Evaluate permission for a path and action
    */
-  evaluate(path5, action, context) {
+  evaluate(path6, action, context) {
     const mergedContext = { ...this.defaultContext, ...context };
     if (!this.config.enforced) {
       return {
@@ -3134,7 +3301,7 @@ var PermissionManager = class {
         reason: "Permissions not enforced"
       };
     }
-    return evaluatePermission(path5, action, mergedContext, this.config);
+    return evaluatePermission(path6, action, mergedContext, this.config);
   }
   /**
    * Filter paths by permission
@@ -3237,12 +3404,12 @@ var PermissionManager = class {
   /**
    * Assert permission (throws if denied)
    */
-  assertPermission(path5, action, requiredLevel = "read", context) {
-    const result = this.evaluate(path5, action, context);
+  assertPermission(path6, action, requiredLevel = "read", context) {
+    const result = this.evaluate(path6, action, context);
     if (!levelGrants(result.level, requiredLevel)) {
       throw new PermissionDeniedError(
-        `Permission denied for ${action} on ${path5}: ${result.reason}`,
-        path5,
+        `Permission denied for ${action} on ${path6}: ${result.reason}`,
+        path6,
         action,
         result
       );
@@ -3250,9 +3417,9 @@ var PermissionManager = class {
   }
 };
 var PermissionDeniedError = class extends Error {
-  constructor(message, path5, action, result) {
+  constructor(message, path6, action, result) {
     super(message);
-    this.path = path5;
+    this.path = path6;
     this.action = action;
     this.result = result;
     this.name = "PermissionDeniedError";
@@ -3749,8 +3916,8 @@ function convertToUri(reference, options = {}) {
   const parts = parseReference2(trimmed);
   const org = parts.org || options.defaultOrg || "_";
   const project = parts.project || options.defaultProject || "_";
-  const path5 = parts.path;
-  return `codex://${org}/${project}/${path5}`;
+  const path6 = parts.path;
+  return `codex://${org}/${project}/${path6}`;
 }
 function parseReference2(reference) {
   const trimmed = reference.trim();