@fractary/codex-cli 0.4.0 → 0.5.0

package/README.md

@@ -153,6 +153,41 @@ Options:
   --parallel <n>       Number of parallel sync operations (default: 3)
 ```
 
+**Routing-Aware Sync (v4.1+):**
+
+When using `--from-codex` direction, the sync command uses **routing-aware file discovery** to find all files across the entire codex that should sync to your project based on `codex_sync_include` frontmatter patterns.
+
+How it works:
+1. Clones the entire codex repository to a temporary directory (`/tmp/fractary-codex-clone/`)
+2. Scans ALL markdown files in the codex recursively
+3. Evaluates `codex_sync_include` patterns in each file's frontmatter
+4. Returns only files that match your project name or pattern
+
+**Example frontmatter in source files:**
+```yaml
+---
+codex_sync_include: ['*']                  # Syncs to ALL projects
+codex_sync_include: ['lake-*', 'api-*']    # Syncs to lake-* and api-* projects
+codex_sync_exclude: ['*-test']             # Except *-test projects
+---
+```
+
+**Trade-offs:**
+- **Efficient for discovery**: Finds all relevant files across hundreds of projects
+- **Inefficient for execution**: Clones entire codex repository (uses shallow clone for speed)
+- **Best practice**: Use `codex://` URI references + cache purging for most workflows; use sync occasionally when needed
+
+**Recommended workflow:**
+```bash
+# Primary: Reference files via codex:// URIs (no sync needed)
+fractary-codex fetch codex://org/project/path/file.md
+
+# When you need latest versions: Purge cache
+fractary-codex cache clear --pattern "codex://org/project/*"
+
+# Then MCP will re-fetch fresh content automatically
+```
+
 ### `types` - Type Registry Management
 
 Manage custom artifact types for classification and caching.

package/dist/cli.cjs

@@ -5,6 +5,8 @@ var fs = require('fs/promises');
 var path3 = require('path');
 var yaml = require('js-yaml');
 var codex = require('@fractary/codex');
+var os = require('os');
+var child_process = require('child_process');
 var commander = require('commander');
 var chalk8 = require('chalk');
 var crypto = require('crypto');
@@ -32,6 +34,7 @@ function _interopNamespace(e) {
 var fs__namespace = /*#__PURE__*/_interopNamespace(fs);
 var path3__namespace = /*#__PURE__*/_interopNamespace(path3);
 var yaml__namespace = /*#__PURE__*/_interopNamespace(yaml);
+var os__namespace = /*#__PURE__*/_interopNamespace(os);
 var chalk8__default = /*#__PURE__*/_interopDefault(chalk8);
 var crypto__namespace = /*#__PURE__*/_interopNamespace(crypto);
 
@@ -619,6 +622,178 @@ var init_codex_client = __esm({
   }
 });
 
+// src/utils/codex-repository.ts
+var codex_repository_exports = {};
+__export(codex_repository_exports, {
+  ensureCodexCloned: () => ensureCodexCloned,
+  getCodexRepoUrl: () => getCodexRepoUrl,
+  getTempCodexPath: () => getTempCodexPath,
+  isValidGitRepo: () => isValidGitRepo
+});
+function spawnAsync(command, args, options) {
+  return new Promise((resolve, reject) => {
+    const child = child_process.spawn(command, args, {
+      ...options,
+      env: process.env
+    });
+    let stdout = "";
+    let stderr = "";
+    child.stdout.on("data", (data) => {
+      stdout += data.toString();
+    });
+    child.stderr.on("data", (data) => {
+      stderr += data.toString();
+    });
+    child.on("error", (error) => {
+      reject(error);
+    });
+    child.on("close", (code) => {
+      if (code !== 0) {
+        const error = new Error(stderr || `Command exited with code ${code}`);
+        error.code = code;
+        reject(error);
+      } else {
+        resolve(stdout);
+      }
+    });
+  });
+}
+function sanitizePathComponent(component) {
+  if (!component || typeof component !== "string") {
+    throw new Error("Path component must be a non-empty string");
+  }
+  const sanitized = component.replace(/\.\./g, "").replace(/[/\\]/g, "").trim();
+  if (!sanitized) {
+    throw new Error(`Invalid path component: ${component}`);
+  }
+  return sanitized;
+}
+function validateGitHubName(name, type) {
+  if (!name || typeof name !== "string") {
+    throw new Error(`GitHub ${type} name must be a non-empty string`);
+  }
+  if (!/^[a-zA-Z0-9._-]+$/.test(name)) {
+    throw new Error(`Invalid GitHub ${type} name: ${name}. Must contain only alphanumeric characters, hyphens, underscores, and dots.`);
+  }
+  if (name.startsWith(".") || name.startsWith("-")) {
+    throw new Error(`GitHub ${type} name cannot start with a dot or hyphen: ${name}`);
+  }
+}
+function getTempCodexPath(config) {
+  const codexRepo = config.codex_repository || "codex";
+  const sanitizedOrg = sanitizePathComponent(config.organization);
+  const sanitizedRepo = sanitizePathComponent(codexRepo);
+  return path3__namespace.join(
+    os__namespace.tmpdir(),
+    "fractary-codex-clone",
+    `${sanitizedOrg}-${sanitizedRepo}-${process.pid}`
+  );
+}
+async function isValidGitRepo(repoPath) {
+  try {
+    const gitDir = path3__namespace.join(repoPath, ".git");
+    const stats = await fs__namespace.stat(gitDir);
+    return stats.isDirectory();
+  } catch {
+    return false;
+  }
+}
+function getCodexRepoUrl(config) {
+  const codexRepo = config.codex_repository || "codex";
+  validateGitHubName(config.organization, "organization");
+  validateGitHubName(codexRepo, "repository");
+  return `https://github.com/${config.organization}/${codexRepo}.git`;
+}
+async function execGit(repoPath, args) {
+  try {
+    const stdout = await spawnAsync("git", args, {
+      cwd: repoPath
+    });
+    return stdout;
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      throw new Error(`Git command not found. Ensure git is installed and in PATH.`);
+    }
+    if (error.code === "EACCES") {
+      throw new Error(`Permission denied accessing repository at ${repoPath}`);
+    }
+    if (error.code === 128) {
+      throw new Error(`Git authentication failed. Check your credentials and repository access.`);
+    }
+    throw error;
+  }
+}
+async function gitClone(url, targetPath, options) {
+  const parentDir = path3__namespace.dirname(targetPath);
+  await fs__namespace.mkdir(parentDir, { recursive: true });
+  const args = ["clone"];
+  if (options?.depth) {
+    if (!Number.isInteger(options.depth) || options.depth <= 0) {
+      throw new Error(`Invalid depth parameter: ${options.depth}. Must be a positive integer.`);
+    }
+    args.push("--depth", String(options.depth));
+  }
+  if (options?.branch) {
+    if (!/^[\w\-./]+$/.test(options.branch)) {
+      throw new Error(`Invalid branch name: ${options.branch}`);
+    }
+    args.push("--branch", options.branch);
+  }
+  args.push("--single-branch");
+  args.push(url, targetPath);
+  await spawnAsync("git", args, { cwd: parentDir });
+}
+async function gitFetch(repoPath, branch) {
+  {
+    if (!/^[\w\-./]+$/.test(branch)) {
+      throw new Error(`Invalid branch name: ${branch}`);
+    }
+    await execGit(repoPath, ["fetch", "origin", `${branch}:${branch}`]);
+  }
+}
+async function gitCheckout(repoPath, branch) {
+  if (!/^[\w\-./]+$/.test(branch)) {
+    throw new Error(`Invalid branch name: ${branch}`);
+  }
+  await execGit(repoPath, ["checkout", branch]);
+}
+async function gitPull(repoPath) {
+  await execGit(repoPath, ["pull"]);
+}
+async function ensureCodexCloned(config, options) {
+  const tempPath = getTempCodexPath(config);
+  const branch = options?.branch || "main";
+  if (await isValidGitRepo(tempPath) && !options?.force) {
+    try {
+      await gitFetch(tempPath, branch);
+      await gitCheckout(tempPath, branch);
+      await gitPull(tempPath);
+      return tempPath;
+    } catch (error) {
+      console.warn(`Failed to update existing clone: ${error.message}`);
+      console.warn(`Removing and cloning fresh...`);
+      await fs__namespace.rm(tempPath, { recursive: true, force: true });
+    }
+  }
+  const repoUrl = getCodexRepoUrl(config);
+  try {
+    await fs__namespace.rm(tempPath, { recursive: true, force: true });
+  } catch (error) {
+    console.warn(`Could not remove existing directory ${tempPath}: ${error.message}`);
+  }
+  await gitClone(repoUrl, tempPath, {
+    branch,
+    depth: 1
+    // Shallow clone for efficiency
+  });
+  return tempPath;
+}
+var init_codex_repository = __esm({
+  "src/utils/codex-repository.ts"() {
+    init_cjs_shims();
+  }
+});
+
 // src/cli.ts
 init_cjs_shims();
 
@@ -1501,15 +1676,50 @@ function syncCommand() {
       let plan;
       let routingScan;
       if (direction === "from-codex") {
-        const codexRepoPath = config.cacheDir || path3__namespace.join(process.cwd(), ".fractary", "codex-cache");
-        if (options.json) {
-          console.log(JSON.stringify({
-            info: "Routing-aware sync: scanning entire codex repository for files targeting this project",
-            codexPath: codexRepoPath
-          }, null, 2));
-        } else {
-          console.log(chalk8__default.default.blue("\u2139 Using routing-aware sync"));
-          console.log(chalk8__default.default.dim("  Scanning entire codex for files routing to this project...\n"));
+        let codexRepoPath;
+        try {
+          const { ensureCodexCloned: ensureCodexCloned2 } = await Promise.resolve().then(() => (init_codex_repository(), codex_repository_exports));
+          if (!options.json) {
+            console.log(chalk8__default.default.blue("\u2139 Cloning/updating codex repository..."));
+          }
+          codexRepoPath = await ensureCodexCloned2(config, {
+            branch: targetBranch
+          });
+          if (!options.json) {
+            console.log(chalk8__default.default.dim(`  Codex cloned to: ${codexRepoPath}`));
+            console.log(chalk8__default.default.dim("  Scanning for files routing to this project...\n"));
+          } else {
+            console.log(JSON.stringify({
+              info: "Routing-aware sync: cloned codex repository and scanning for files targeting this project",
+              codexPath: codexRepoPath
+            }, null, 2));
+          }
+        } catch (error) {
+          console.error(chalk8__default.default.red("Error:"), "Failed to clone codex repository");
+          console.error(chalk8__default.default.dim(`  ${error.message}`));
+          console.log(chalk8__default.default.yellow("\nTroubleshooting:"));
+          if (error.message.includes("Git command not found")) {
+            console.log(chalk8__default.default.dim("  Git is not installed or not in PATH."));
+            console.log(chalk8__default.default.dim("  Install git: https://git-scm.com/downloads"));
+          } else if (error.message.includes("authentication failed") || error.message.includes("Authentication failed")) {
+            console.log(chalk8__default.default.dim("  GitHub authentication is required for private repositories."));
+            console.log(chalk8__default.default.dim("  1. Check auth status: gh auth status"));
+            console.log(chalk8__default.default.dim("  2. Login if needed: gh auth login"));
+            console.log(chalk8__default.default.dim("  3. Or set GITHUB_TOKEN environment variable"));
+          } else if (error.message.includes("Permission denied")) {
+            console.log(chalk8__default.default.dim("  Permission denied accessing repository files."));
+            console.log(chalk8__default.default.dim("  1. Check file/directory permissions"));
+            console.log(chalk8__default.default.dim("  2. Ensure you have access to the repository"));
+          } else if (error.message.includes("not found") || error.message.includes("does not exist")) {
+            console.log(chalk8__default.default.dim(`  Repository not found: ${config.organization}/${config.codex_repository || "codex"}`));
+            console.log(chalk8__default.default.dim("  1. Verify the repository exists on GitHub"));
+            console.log(chalk8__default.default.dim("  2. Check organization and repository names in config"));
+          } else {
+            console.log(chalk8__default.default.dim("  1. Ensure git is installed: git --version"));
+            console.log(chalk8__default.default.dim("  2. Check GitHub auth: gh auth status"));
+            console.log(chalk8__default.default.dim(`  3. Verify repo exists: ${config.organization}/${config.codex_repository || "codex"}`));
+          }
+          process.exit(1);
         }
         const planWithRouting = await syncManager.createRoutingAwarePlan(
           config.organization,