@fractary/codex 0.7.0 → 0.8.0

package/dist/index.d.cts

@@ -424,6 +424,43 @@ declare const CodexConfigSchema: z.ZodObject<{
         default_to_codex?: string[] | undefined;
         default_from_codex?: string[] | undefined;
     }>>;
+    archive: z.ZodOptional<z.ZodObject<{
+        projects: z.ZodRecord<z.ZodString, z.ZodObject<{
+            enabled: z.ZodBoolean;
+            handler: z.ZodEnum<["s3", "r2", "gcs", "local"]>;
+            bucket: z.ZodOptional<z.ZodString>;
+            prefix: z.ZodOptional<z.ZodString>;
+            patterns: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        }, "strip", z.ZodTypeAny, {
+            enabled: boolean;
+            handler: "local" | "s3" | "r2" | "gcs";
+            patterns?: string[] | undefined;
+            bucket?: string | undefined;
+            prefix?: string | undefined;
+        }, {
+            enabled: boolean;
+            handler: "local" | "s3" | "r2" | "gcs";
+            patterns?: string[] | undefined;
+            bucket?: string | undefined;
+            prefix?: string | undefined;
+        }>>;
+    }, "strip", z.ZodTypeAny, {
+        projects: Record<string, {
+            enabled: boolean;
+            handler: "local" | "s3" | "r2" | "gcs";
+            patterns?: string[] | undefined;
+            bucket?: string | undefined;
+            prefix?: string | undefined;
+        }>;
+    }, {
+        projects: Record<string, {
+            enabled: boolean;
+            handler: "local" | "s3" | "r2" | "gcs";
+            patterns?: string[] | undefined;
+            bucket?: string | undefined;
+            prefix?: string | undefined;
+        }>;
+    }>>;
 }, "strict", z.ZodTypeAny, {
     organizationSlug: string;
     directories?: {
@@ -449,6 +486,15 @@ declare const CodexConfigSchema: z.ZodObject<{
         default_to_codex?: string[] | undefined;
         default_from_codex?: string[] | undefined;
     } | undefined;
+    archive?: {
+        projects: Record<string, {
+            enabled: boolean;
+            handler: "local" | "s3" | "r2" | "gcs";
+            patterns?: string[] | undefined;
+            bucket?: string | undefined;
+            prefix?: string | undefined;
+        }>;
+    } | undefined;
 }, {
     organizationSlug: string;
     directories?: {
@@ -474,6 +520,15 @@ declare const CodexConfigSchema: z.ZodObject<{
         default_to_codex?: string[] | undefined;
         default_from_codex?: string[] | undefined;
     } | undefined;
+    archive?: {
+        projects: Record<string, {
+            enabled: boolean;
+            handler: "local" | "s3" | "r2" | "gcs";
+            patterns?: string[] | undefined;
+            bucket?: string | undefined;
+            prefix?: string | undefined;
+        }>;
+    } | undefined;
 }>;
 type CodexConfig = z.infer<typeof CodexConfigSchema>;
 
@@ -549,7 +604,7 @@ interface CustomSyncDestination {
 declare function parseCustomDestination(value: string): CustomSyncDestination;
 declare function getCustomSyncDestinations(metadata: Metadata): CustomSyncDestination[];
 
-type StorageProviderType = 'local' | 'github' | 'http' | 's3' | 'r2' | 'gcs' | 'drive';
+type StorageProviderType = 'local' | 'github' | 'http' | 's3' | 's3-archive' | 'r2' | 'gcs' | 'drive';
 interface FetchResult {
     content: Buffer;
     contentType: string;
@@ -653,10 +708,23 @@ declare class HttpStorage implements StorageProvider {
 }
 declare function createHttpStorage(options?: HttpStorageOptions): HttpStorage;
 
+interface ArchiveProjectConfig {
+    enabled: boolean;
+    handler: 's3' | 'r2' | 'gcs' | 'local';
+    bucket?: string;
+    prefix?: string;
+    patterns?: string[];
+}
+interface S3ArchiveStorageOptions {
+    projects?: Record<string, ArchiveProjectConfig>;
+    fractaryCli?: string;
+}
+
 interface StorageManagerConfig {
     local?: LocalStorageOptions;
     github?: GitHubStorageOptions;
     http?: HttpStorageOptions;
+    s3Archive?: S3ArchiveStorageOptions;
     priority?: StorageProviderType[];
     enableCaching?: boolean;
 }

package/dist/index.d.ts

@@ -424,6 +424,43 @@ declare const CodexConfigSchema: z.ZodObject<{
         default_to_codex?: string[] | undefined;
         default_from_codex?: string[] | undefined;
     }>>;
+    archive: z.ZodOptional<z.ZodObject<{
+        projects: z.ZodRecord<z.ZodString, z.ZodObject<{
+            enabled: z.ZodBoolean;
+            handler: z.ZodEnum<["s3", "r2", "gcs", "local"]>;
+            bucket: z.ZodOptional<z.ZodString>;
+            prefix: z.ZodOptional<z.ZodString>;
+            patterns: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        }, "strip", z.ZodTypeAny, {
+            enabled: boolean;
+            handler: "local" | "s3" | "r2" | "gcs";
+            patterns?: string[] | undefined;
+            bucket?: string | undefined;
+            prefix?: string | undefined;
+        }, {
+            enabled: boolean;
+            handler: "local" | "s3" | "r2" | "gcs";
+            patterns?: string[] | undefined;
+            bucket?: string | undefined;
+            prefix?: string | undefined;
+        }>>;
+    }, "strip", z.ZodTypeAny, {
+        projects: Record<string, {
+            enabled: boolean;
+            handler: "local" | "s3" | "r2" | "gcs";
+            patterns?: string[] | undefined;
+            bucket?: string | undefined;
+            prefix?: string | undefined;
+        }>;
+    }, {
+        projects: Record<string, {
+            enabled: boolean;
+            handler: "local" | "s3" | "r2" | "gcs";
+            patterns?: string[] | undefined;
+            bucket?: string | undefined;
+            prefix?: string | undefined;
+        }>;
+    }>>;
 }, "strict", z.ZodTypeAny, {
     organizationSlug: string;
     directories?: {
@@ -449,6 +486,15 @@ declare const CodexConfigSchema: z.ZodObject<{
         default_to_codex?: string[] | undefined;
         default_from_codex?: string[] | undefined;
     } | undefined;
+    archive?: {
+        projects: Record<string, {
+            enabled: boolean;
+            handler: "local" | "s3" | "r2" | "gcs";
+            patterns?: string[] | undefined;
+            bucket?: string | undefined;
+            prefix?: string | undefined;
+        }>;
+    } | undefined;
 }, {
     organizationSlug: string;
     directories?: {
@@ -474,6 +520,15 @@ declare const CodexConfigSchema: z.ZodObject<{
         default_to_codex?: string[] | undefined;
         default_from_codex?: string[] | undefined;
     } | undefined;
+    archive?: {
+        projects: Record<string, {
+            enabled: boolean;
+            handler: "local" | "s3" | "r2" | "gcs";
+            patterns?: string[] | undefined;
+            bucket?: string | undefined;
+            prefix?: string | undefined;
+        }>;
+    } | undefined;
 }>;
 type CodexConfig = z.infer<typeof CodexConfigSchema>;
 
@@ -549,7 +604,7 @@ interface CustomSyncDestination {
 declare function parseCustomDestination(value: string): CustomSyncDestination;
 declare function getCustomSyncDestinations(metadata: Metadata): CustomSyncDestination[];
 
-type StorageProviderType = 'local' | 'github' | 'http' | 's3' | 'r2' | 'gcs' | 'drive';
+type StorageProviderType = 'local' | 'github' | 'http' | 's3' | 's3-archive' | 'r2' | 'gcs' | 'drive';
 interface FetchResult {
     content: Buffer;
     contentType: string;
@@ -653,10 +708,23 @@ declare class HttpStorage implements StorageProvider {
 }
 declare function createHttpStorage(options?: HttpStorageOptions): HttpStorage;
 
+interface ArchiveProjectConfig {
+    enabled: boolean;
+    handler: 's3' | 'r2' | 'gcs' | 'local';
+    bucket?: string;
+    prefix?: string;
+    patterns?: string[];
+}
+interface S3ArchiveStorageOptions {
+    projects?: Record<string, ArchiveProjectConfig>;
+    fractaryCli?: string;
+}
+
 interface StorageManagerConfig {
     local?: LocalStorageOptions;
     github?: GitHubStorageOptions;
     http?: HttpStorageOptions;
+    s3Archive?: S3ArchiveStorageOptions;
     priority?: StorageProviderType[];
     enableCaching?: boolean;
 }

package/dist/index.js

@@ -1,9 +1,10 @@
 import micromatch3 from 'micromatch';
 import path3 from 'path';
-import { execSync } from 'child_process';
+import { execFile, execSync } from 'child_process';
 import { z } from 'zod';
 import yaml from 'js-yaml';
 import fs2 from 'fs/promises';
+import { promisify } from 'util';
 
 var __defProp = Object.defineProperty;
 var __getOwnPropNames = Object.getOwnPropertyNames;
@@ -834,6 +835,16 @@ var DirectionalSyncSchema = z.object({
   default_to_codex: z.array(z.string()).optional(),
   default_from_codex: z.array(z.string()).optional()
 });
+var ArchiveProjectConfigSchema = z.object({
+  enabled: z.boolean(),
+  handler: z.enum(["s3", "r2", "gcs", "local"]),
+  bucket: z.string().optional(),
+  prefix: z.string().optional(),
+  patterns: z.array(z.string()).optional()
+});
+var ArchiveConfigSchema = z.object({
+  projects: z.record(ArchiveProjectConfigSchema)
+});
 var CodexConfigSchema = z.object({
   organizationSlug: z.string(),
   directories: z.object({
@@ -843,7 +854,9 @@ var CodexConfigSchema = 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;
@@ -968,11 +981,17 @@ function getDefaultRules() {
     defaultExclude: []
   };
 }
+function getDefaultArchiveConfig() {
+  return {
+    projects: {}
+  };
+}
 function getDefaultConfig(orgSlug) {
   return {
     organizationSlug: orgSlug,
     directories: getDefaultDirectories(orgSlug),
-    rules: getDefaultRules()
+    rules: getDefaultRules(),
+    archive: getDefaultArchiveConfig()
   };
 }
 
@@ -1694,6 +1713,190 @@ var HttpStorage = class {
 function createHttpStorage(options) {
   return new HttpStorage(options);
 }
+var execFileAsync = promisify(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 {
@@ -1703,7 +1906,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