Archive Operations

/**
 * Execute archive tasks with the provided options
 * @param tasks Array of archive tasks to execute
 * @param taskOptions Task execution options including logger and error handling
 */
function archiveAction(tasks: ArchiveTask[], taskOptions: TaskOptions): Promise<void>;

export default archiveAction;

/**
 * Configuration for archive operations
 */
type ArchiveAction = {
  /** Source file, directory, or glob pattern */
  source: string;
  /** Archive destination file path */
  destination: string;
  /** Archive format - defaults to file extension */
  format?: 'zip' | 'tar';
  /** Archiver options and glob options */
  options?: ArchiverOptions;
};

/**
 * Archive options extending archiver.js options
 */
interface ArchiverOptions extends ArchiverJSOptions {
  /** Glob options for pattern-based archiving */
  globOptions?: ReaddirGlobOptions;
}

/**
 * Glob options for readdir-glob functionality
 */
interface ReaddirGlobOptions {
  /** Glob pattern or patterns to match files */
  pattern?: string | string[];
  /** Glob pattern or patterns to exclude */
  ignore?: string | string[];
  /** Glob pattern or patterns to skip directories */
  skip?: string | string[];
  /** Add trailing slash to directory matches */
  mark?: boolean;
  /** Stat all results (reduces performance) */
  stat?: boolean;
  /** Suppress warning messages */
  silent?: boolean;
  /** Do not match directories, only files */
  nodir?: boolean;
  /** Follow symbolic links */
  follow?: boolean;
  /** Match files starting with dot */
  dot?: boolean;
  /** Disable ** globstar matching */
  noglobstar?: boolean;
  /** Case-insensitive matching */
  nocase?: boolean;
  /** Basename-only matching */
  matchBase?: boolean;
}

/**
 * Internal task structure for archive operations
 */
interface ArchiveTask {
  source: string;
  absoluteSource: string;
  absoluteDestination: string;
  context?: string;
  format?: 'zip' | 'tar';
  options?: ArchiverOptions;
}

// Basic ZIP archive
{
  archive: [
    { source: './dist', destination: './release.zip' }
  ]
}

// TAR archive with explicit format
{
  archive: [
    { source: './build', destination: './backup.tar', format: 'tar' }
  ]
}

// Compressed TAR archive
{
  archive: [
    {
      source: './dist',
      destination: './release.tar.gz',
      format: 'tar',
      options: {
        gzip: true,
        gzipOptions: {
          level: 9    // Maximum compression
        }
      }
    }
  ]
}

// Archive with glob patterns
{
  archive: [
    {
      source: './src/**/*.js',
      destination: './scripts.zip',
      options: {
        globOptions: {
          ignore: ['**/*.test.js', '**/*.spec.js']
        }
      }
    }
  ]
}

// Archive single file
{
  archive: [
    { source: './bundle.js', destination: './bundle.zip' }
  ]
}

// Archive with custom archiver options
{
  archive: [
    {
      source: './dist',
      destination: './app.zip',
      options: {
        zlib: { level: 1 },    // Fast compression
        globOptions: {
          dot: true,           // Include hidden files
          ignore: ['**/node_modules/**', '**/*.log']
        }
      }
    }
  ]
}

// ZIP compression
{
  options: {
    zlib: { level: 6 }    // 0-9, higher = better compression
  }
}

// TAR with gzip
{
  options: {
    gzip: true,
    gzipOptions: {
      level: 6,           // 0-9, higher = better compression
      chunkSize: 1024     // Buffer size
    }
  }
}