@fractary/codex 0.7.0 → 0.8.0

package/dist/index.cjs

@@ -6,6 +6,7 @@ var child_process = require('child_process');
 var zod = require('zod');
 var yaml = require('js-yaml');
 var fs2 = require('fs/promises');
+var util = require('util');
 
 function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
 
@@ -843,6 +844,16 @@ var DirectionalSyncSchema = zod.z.object({
   default_to_codex: zod.z.array(zod.z.string()).optional(),
   default_from_codex: zod.z.array(zod.z.string()).optional()
 });
+var ArchiveProjectConfigSchema = zod.z.object({
+  enabled: zod.z.boolean(),
+  handler: zod.z.enum(["s3", "r2", "gcs", "local"]),
+  bucket: zod.z.string().optional(),
+  prefix: zod.z.string().optional(),
+  patterns: zod.z.array(zod.z.string()).optional()
+});
+var ArchiveConfigSchema = zod.z.object({
+  projects: zod.z.record(ArchiveProjectConfigSchema)
+});
 var CodexConfigSchema = zod.z.object({
   organizationSlug: zod.z.string(),
   directories: zod.z.object({
@@ -852,7 +863,9 @@ var CodexConfigSchema = zod.z.object({
   }).optional(),
   rules: SyncRulesSchema.optional(),
   // Directional sync configuration
-  sync: DirectionalSyncSchema.optional()
+  sync: DirectionalSyncSchema.optional(),
+  // Archive configuration
+  archive: ArchiveConfigSchema.optional()
 }).strict();
 function parseMetadata(content, options = {}) {
   const { strict = true, normalize = true } = options;
@@ -977,11 +990,17 @@ function getDefaultRules() {
     defaultExclude: []
   };
 }
+function getDefaultArchiveConfig() {
+  return {
+    projects: {}
+  };
+}
 function getDefaultConfig(orgSlug) {
   return {
     organizationSlug: orgSlug,
     directories: getDefaultDirectories(orgSlug),
-    rules: getDefaultRules()
+    rules: getDefaultRules(),
+    archive: getDefaultArchiveConfig()
   };
 }
 
@@ -1703,6 +1722,190 @@ var HttpStorage = class {
 function createHttpStorage(options) {
   return new HttpStorage(options);
 }
+var execFileAsync = util.promisify(child_process.execFile);
+async function execFileNoThrow(command, args = [], options) {
+  try {
+    const { stdout, stderr } = await execFileAsync(command, args, {
+      ...options,
+      maxBuffer: options?.maxBuffer || 1024 * 1024 * 10
+      // 10MB default
+    });
+    return {
+      stdout: stdout || "",
+      stderr: stderr || "",
+      exitCode: 0
+    };
+  } catch (error) {
+    const exitCode = typeof error.exitCode === "number" ? error.exitCode : 1;
+    return {
+      stdout: error.stdout || "",
+      stderr: error.stderr || error.message || "",
+      exitCode
+    };
+  }
+}
+
+// src/storage/s3-archive.ts
+var S3ArchiveStorage = class {
+  name = "s3-archive";
+  type = "s3-archive";
+  projects;
+  fractaryCli;
+  constructor(options = {}) {
+    this.projects = options.projects || {};
+    this.fractaryCli = options.fractaryCli || "fractary";
+  }
+  /**
+   * Check if this provider can handle the reference
+   *
+   * S3 Archive provider handles references that:
+   * 1. Are for the current project (same org/project)
+   * 2. Have archive enabled in config
+   * 3. Match configured patterns (if specified)
+   */
+  canHandle(reference) {
+    if (!reference.isCurrentProject) {
+      return false;
+    }
+    const projectKey = `${reference.org}/${reference.project}`;
+    const config = this.projects[projectKey];
+    if (!config || !config.enabled) {
+      return false;
+    }
+    if (config.patterns && config.patterns.length > 0) {
+      return this.matchesPatterns(reference.path, config.patterns);
+    }
+    return true;
+  }
+  /**
+   * Fetch content from S3 archive via fractary-file CLI
+   */
+  async fetch(reference, options) {
+    const opts = mergeFetchOptions(options);
+    const projectKey = `${reference.org}/${reference.project}`;
+    const config = this.projects[projectKey];
+    if (!config) {
+      throw new Error(`No archive config for project: ${projectKey}`);
+    }
+    const archivePath = this.calculateArchivePath(reference, config);
+    try {
+      const result = await execFileNoThrow(
+        this.fractaryCli,
+        [
+          "file",
+          "read",
+          "--remote-path",
+          archivePath,
+          "--handler",
+          config.handler,
+          ...config.bucket ? ["--bucket", config.bucket] : []
+        ],
+        {
+          timeout: opts.timeout
+        }
+      );
+      if (result.exitCode !== 0) {
+        throw new Error(`fractary-file read failed: ${result.stderr}`);
+      }
+      const content = Buffer.from(result.stdout);
+      return {
+        content,
+        contentType: detectContentType(reference.path),
+        size: content.length,
+        source: "s3-archive",
+        metadata: {
+          archivePath,
+          bucket: config.bucket,
+          handler: config.handler
+        }
+      };
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      throw new Error(`Failed to fetch from archive: ${message}`);
+    }
+  }
+  /**
+   * Check if archived file exists
+   *
+   * Note: This currently downloads the file to check existence.
+   * TODO: Optimize by using fractary-file 'stat' or 'head' command when available
+   * to avoid downloading full file for existence checks.
+   */
+  async exists(reference, options) {
+    const projectKey = `${reference.org}/${reference.project}`;
+    const config = this.projects[projectKey];
+    if (!config) {
+      return false;
+    }
+    try {
+      await this.fetch(reference, { ...options, timeout: 5e3 });
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  /**
+   * Calculate archive path from reference
+   *
+   * Pattern: {prefix}/{type}/{org}/{project}/{original-path}
+   *
+   * Examples (with default prefix "archive/"):
+   *   specs/WORK-123.md → archive/specs/org/project/specs/WORK-123.md
+   *   docs/api.md → archive/docs/org/project/docs/api.md
+   *
+   * Examples (with custom prefix "archived-docs/"):
+   *   specs/WORK-123.md → archived-docs/specs/org/project/specs/WORK-123.md
+   */
+  calculateArchivePath(reference, config) {
+    const type = this.detectType(reference.path);
+    const prefix = config.prefix || "archive/";
+    const trimmedPrefix = prefix.trim();
+    if (!trimmedPrefix) {
+      throw new Error("Archive prefix cannot be empty or whitespace-only");
+    }
+    const normalizedPrefix = trimmedPrefix.endsWith("/") ? trimmedPrefix : `${trimmedPrefix}/`;
+    return `${normalizedPrefix}${type}/${reference.org}/${reference.project}/${reference.path}`;
+  }
+  /**
+   * Detect artifact type from path
+   *
+   * 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";
+    return "misc";
+  }
+  /**
+   * Check if path matches any of the patterns
+   *
+   * Supports glob-style patterns:
+   * - specs/** (all files in specs/)
+   * - *.md (all markdown files)
+   * - docs/*.md (markdown files in docs/)
+   */
+  matchesPatterns(path6, patterns) {
+    for (const pattern of patterns) {
+      if (this.matchesPattern(path6, pattern)) {
+        return true;
+      }
+    }
+    return false;
+  }
+  /**
+   * Check if path matches a single pattern
+   */
+  matchesPattern(path6, 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);
+  }
+};
 
 // src/storage/manager.ts
 var StorageManager = class {
@@ -1712,7 +1915,10 @@ var StorageManager = class {
     this.providers.set("local", new LocalStorage(config.local));
     this.providers.set("github", new GitHubStorage(config.github));
     this.providers.set("http", new HttpStorage(config.http));
-    this.priority = config.priority || ["local", "github", "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"]);
   }
   /**
    * Register a custom storage provider