leechtop_downloader 0.1.3

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f9cda9290e92e0b12a23dd395a4933c29a519041b710a1ef1b2268a930d1c067
+  data.tar.gz: a85bf047dd7deb3d5b37c56a8e8d0ffc4fb8e3ad345cc59a7e9ceb677efa6df1
+SHA512:
+  metadata.gz: 0334dd930713518bcebbb1b4220cdc100c4e86a6f962c7ec76bd461a79042acd509499086a8623ec85bddaf2f3276edfd029ab6d0187f57eb11de2348db1c2ef
+  data.tar.gz: ce9b2409c63f8288826294e481347263cbb16aa8afcdc7d85ed1e60512059d92b3680835045f6e7bd7df0c0d2fb0ee93e51b569e17ec64fbccc1363b03beee15

data/Gemfile

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gemspec

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vitalii Lazebnyi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,90 @@
+# Leechtop Downloader
+
+A CLI utility for downloading files from leechtop.com.
+
+## Installation
+
+To install the gem globally, run:
+
+```bash
+gem install leechtop_downloader
+```
+
+This will make the `leechtop` command available in your terminal.
+
+## Local Development Setup
+
+Ruby `>= 3.2.0` is required to run the gem.
+
+1. Clone the repository and run:
+   ```bash
+   bundle install
+   ```
+3. Install local git hooks (if desired):
+   ```bash
+   cp .git/hooks/pre-commit .git/hooks/pre-commit.bak # if existing
+   # our automated hook is self-contained.
+   ```
+
+## Testing
+
+This project mandates 100% test coverage.
+
+```bash
+bundle exec rspec
+```
+
+## Static Analysis
+
+This project mandates zero linting or type-checking errors.
+
+```bash
+bundle exec rubocop
+bundle exec srb tc
+```
+
+## Usage
+
+The CLI can download files from direct `leechtop.com` links or automatically extract and download multiple links from any generic HTML webpage. All downloads are saved in the current folder by default, which can be overridden via the `--destination` option.
+
+### Direct Download
+Provide a direct Leechtop URL:
+```bash
+leechtop download "https://leechtop.com/example1"
+```
+
+### Batch Download via HTML Parsing
+Provide the URL of an HTML page (like a manga chapter index) containing `leechtop.com` links. The tool will parse the page, extract all valid links, and download them sequentially:
+```bash
+leechtop download "https://dl-raw.ac/example-manga-page/"
+```
+
+### Multiple URLs
+You can pass any combination of direct URLs or generic HTML pages at once:
+```bash
+leechtop download "https://leechtop.com/example1" "https://dl-raw.ac/example-page/"
+```
+
+### Batch Download via Text File
+You can also pass the path to a local text file that contains a list of URLs (one per line). The tool will read the file and download each link:
+```bash
+# links.txt contains URLs separated by newlines
+leechtop download links.txt
+```
+
+### Parallel & Concurrent Downloading
+Since `leechtop.com` does not allow parallel downloads, the tool enforces a strict global application lock. If you attempt to run multiple instances of the downloader concurrently in different terminal tabs, any secondary instances will automatically detect the active process, print an error message, and safely exit to prevent conflicts.
+
+### Options
+
+**`--skip-existing`** (Default: `true`)
+By default, the tool will skip downloading files that already exist in the destination directory. If you want to force re-downloading and overwrite existing files, pass `--no-skip-existing`:
+```bash
+leechtop download "https://leechtop.com/example1" --no-skip-existing
+```
+
+**`--destination`** (Default: `.`)
+Specify a custom destination directory for downloaded files:
+```bash
+leechtop download "https://leechtop.com/example1" --destination="/path/to/custom/dir"
+```

data/certs/leechtop_downloader-public_cert.pem

@@ -0,0 +1,25 @@
+-----BEGIN CERTIFICATE-----
+MIIEOTCCAqGgAwIBAgIUBONmsFo7fxLGkUHsKe65onH+5ogwDQYJKoZIhvcNAQEL
+BQAwLDEqMCgGA1UEAwwhdml0YWxpaS5sYXplYm55aS5naXRodWJAZ21haWwuY29t
+MB4XDTI2MDQxNTEzNTMyOVoXDTM2MDQxMjEzNTMyOVowLDEqMCgGA1UEAwwhdml0
+YWxpaS5sYXplYm55aS5naXRodWJAZ21haWwuY29tMIIBojANBgkqhkiG9w0BAQEF
+AAOCAY8AMIIBigKCAYEA5zdezJE+Zrsk9j53/IxBfRoaqvLcPvrcfl+EaEwWhIkV
+0+08GtgS9N7VpB8cgaH2rkLJPjHIetsN/g5GMkDRsbJNXMrPVhxe1e1lI/r6j0Tm
+JD0PaU4r8VzitxkqY9BBmSI8GjDjAfrT1u5jSXH1iAtKUoq5F116uYrxbgiDpvqa
+kUQYcTf+6cZaPlF4KKhULnhKqs8u/NxyH4vPZyxEfg/gA4bODvcjW1A6d59BTiLV
+yrJPebwU+F+URb8aoQ4AGvPKFiG1Y1fxRHuPrOpyymFnBnjwgMyQkNHtzTeEriV9
+z1BUb10Pb/pjLBCrOvnStTPmcm1GE8HL2psYvlLvBlYqq3gzpQPBBKE3Jefa7ilC
+cYsBYOGpynpA9uu9cXKa4jtpPDGQ7Qrpnk9gHy/0xfbgLdAkRCoZJeR7wDL/1xmm
+nXwcUOLSOBj1Y4P9M+uQSQUZFTAaLbwyaBfE1gvVjwbTv3+rNP1ck1hACt+numGG
+m7R6MF+Hmh8pNnDBYpBNAgMBAAGjUzBRMB0GA1UdDgQWBBRbuaz1EhdG6T4KIeWr
+ac8LULxO9zAfBgNVHSMEGDAWgBRbuaz1EhdG6T4KIeWrac8LULxO9zAPBgNVHRMB
+Af8EBTADAQH/MA0GCSqGSIb3DQEBCwUAA4IBgQBgfGTDIMxlm6o8o7dzCR0HosRm
+DSeUrx46EG1knTEqO05CooEHW98hrHa1/EwzkPaH1KhjjserQb6VtczMnySlfySu
+HbKWAIaqzlpf8zaE5tCiAKgFKr77b2XB7xKt25p/Vf/Kn/RLm3+sYQ2izzzMimei
+tBHo29cLV9bB/5HHFDwjrtdC5a0HJHiir0w4MCSDDGtnsKird4RKD2xESpoVjiNg
+L9nEGk25YDeIfKn8UtxduMv53T86CiBSsDcEb6oVjNiMOA0HFucwFKX+Vy5u0/qx
+ZRoLbZiCkTTGyNkBh4o6RCCTn37Lj98FBxYMbAHLNhEcKnAGxB7XP/CYsV4+QHOy
+h0PctylhIvm24QeKgIWJUWamFPfqdvlP660T4umxl2wMqvNpWmGMmGTMCraoKwxl
+zpp6uA15MXgTU7CxGivRgUKM64TqBMZKkOJcCtPkruSobxiR8cROrBNTqEbrmedM
+26EUEoxwDzfSzHU2SKz5pMR+8DClMUKB1rctg68=
+-----END CERTIFICATE-----

data/exe/leechtop

@@ -0,0 +1,10 @@
+#!/usr/bin/env ruby
+# typed: true
+# frozen_string_literal: true
+
+Encoding.default_external = Encoding::UTF_8
+Encoding.default_internal = Encoding::UTF_8
+
+require 'leechtop_downloader'
+
+LeechtopDownloader::CLI.start(ARGV)

data/leechtop_downloader.gemspec

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require_relative 'lib/leechtop_downloader/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'leechtop_downloader'
+  spec.version       = LeechtopDownloader::VERSION
+  spec.authors       = ['Vitalii Lazebnyi']
+  spec.email         = ['vitalii.lazebnyi.github@gmail.com']
+
+  spec.summary       = 'CLI utility to download files from leechtop.com.'
+  spec.description   = 'A robust command-line tool that automates extracting direct ' \
+                       'download links and saving files from leechtop.com. ' \
+                       'Supports batch processing, duplicate skipping, and safe concurrency.'
+  spec.homepage      = 'https://github.com/VitaliiLazebnyi/leechtop-downloader'
+  spec.license       = 'MIT'
+  spec.cert_chain    = ['certs/leechtop_downloader-public_cert.pem']
+  if $PROGRAM_NAME.end_with?('gem') && File.exist?(File.expand_path('~/.gem/gem-private_key.pem'))
+    spec.signing_key = File.expand_path('~/.gem/gem-private_key.pem')
+  end
+  spec.required_ruby_version = '>= 3.2.0'
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  # Specify which files should be added to the gem when it is released.
+  spec.files = %w[
+    Gemfile
+    LICENSE.txt
+    README.md
+    leechtop_downloader.gemspec
+  ] + Dir.glob('{exe,lib,certs}/**/*', base: __dir__).select do |f|
+    File.file?(File.expand_path(f, __dir__))
+  end
+
+  spec.bindir        = 'exe'
+  spec.executables   = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  # Runtime dependencies
+  spec.add_dependency 'dotenv', '~> 3.0'
+  spec.add_dependency 'down', '~> 5.0'
+  spec.add_dependency 'faraday', '~> 2.0'
+  spec.add_dependency 'nokogiri', '~> 1.0'
+  spec.add_dependency 'sorbet-runtime', '~> 0.6'
+  spec.add_dependency 'thor', '~> 1.0'
+
+  # Development dependencies
+  spec.add_development_dependency 'rspec', '~> 3.13'
+  spec.add_development_dependency 'rubocop', '~> 1.86'
+  spec.add_development_dependency 'rubocop-rspec', '~> 3.9'
+  spec.add_development_dependency 'rubocop-sorbet', '~> 0.12'
+  spec.add_development_dependency 'simplecov', '~> 0.22'
+  spec.add_development_dependency 'sorbet', '~> 0.6'
+  spec.add_development_dependency 'tapioca', '~> 0.19'
+  spec.add_development_dependency 'webmock', '~> 3.26'
+  spec.add_development_dependency 'yard', '~> 0.9'
+  spec.add_development_dependency 'yard-sorbet', '~> 0.9'
+end

data/lib/leechtop_downloader/cli.rb

@@ -0,0 +1,167 @@
+# typed: true
+# frozen_string_literal: true
+
+require 'sorbet-runtime'
+require 'thor'
+require 'digest'
+require 'fileutils'
+require 'tmpdir'
+require_relative 'cli_helpers'
+
+module LeechtopDownloader
+  # CLI is the Thor application for handling commands.
+  class CLI < Thor
+    extend T::Sig
+    include CLIHelpers
+
+    # Ensure Thor exits with an error status on failure.
+    # @return [T::Boolean] true
+    def self.exit_on_failure?
+      true
+    end
+
+    method_option :skip_existing, type: :boolean, default: true, desc: 'Skip downloading already existing files'
+    method_option :destination, type: :string, default: '.', desc: 'Destination folder for downloaded files'
+    desc 'download URL_OR_FILE...', 'Download one or more URLs (or a text file with links) from leechtop.com'
+    # LT-REQ-001, LT-REQ-002
+    # Main entry point to download files.
+    # @param urls [Array<String>] The URLs or file paths to download from.
+    def download(*urls)
+      if urls.empty?
+        puts 'Error: You must provide at least one URL or file path.'
+        exit 1
+      end
+
+      with_app_lock do
+        skip_existing = options.fetch(:skip_existing, true)
+        destination = options.fetch(:destination, '.')
+
+        urls.each { |arg| process_argument(arg, skip_existing, destination) }
+      end
+    end
+
+    private
+
+    # Processes a single CLI argument (file or URL).
+    # @param arg [String] The argument string.
+    # @param skip_existing [T::Boolean] Whether to skip existing files.
+    # @param destination [String] The download destination directory.
+    sig { params(arg: String, skip_existing: T::Boolean, destination: String).void }
+    def process_argument(arg, skip_existing, destination)
+      if File.file?(arg)
+        File.readlines(arg, chomp: true).each do |line|
+          link = line.strip
+          process_url(link, skip_existing: skip_existing, destination: destination) unless link.empty?
+        end
+      else
+        process_url(arg, skip_existing: skip_existing, destination: destination)
+      end
+    end
+
+    # Processes a single URL to determine if it is a direct download or page parsing.
+    # @param url [String] The URL string.
+    # @param skip_existing [T::Boolean] Whether to skip existing files.
+    # @param destination [String] The download destination directory.
+    sig { params(url: String, skip_existing: T::Boolean, destination: String).void }
+    def process_url(url, skip_existing: true, destination: '.')
+      if url.match?(%r{^https?://(?:www\.)?leechtop\.com/})
+        download_single(url, skip_existing: skip_existing, destination: destination)
+      else
+        extract_and_download_links(url, skip_existing: skip_existing, destination: destination)
+      end
+    end
+
+    # Extracts multiple links from a given URL and downloads them.
+    # @param url [String] The URL string.
+    # @param skip_existing [T::Boolean] Whether to skip existing files.
+    # @param destination [String] The download destination directory.
+    sig { params(url: String, skip_existing: T::Boolean, destination: String).void }
+    def extract_and_download_links(url, skip_existing: true, destination: '.')
+      puts "Fetching links from: #{url}"
+      links = Client.extract_page_links(url)
+      if links.empty?
+        puts "No leechtop.com links found on #{url}"
+      else
+        puts "Found #{links.size} leechtop.com link(s). Downloading..."
+        links.each { |link| download_single(link, skip_existing: skip_existing, destination: destination) }
+      end
+    end
+
+    # Downloads a single specific file.
+    # @param url [String] The URL string.
+    # @param skip_existing [T::Boolean] Whether to skip existing files.
+    # @param destination [String] The download destination directory.
+    sig { params(url: String, skip_existing: T::Boolean, destination: String).void }
+    def download_single(url, skip_existing: true, destination: '.')
+      puts "Downloading: #{url}\nBypassing countdown and extracting direct link..."
+      metadata = Client.fetch_metadata(url)
+      return if skip_download?(metadata.fetch(:filename), skip_existing, destination)
+
+      download_with_lock(url, metadata, metadata.fetch(:filename), destination)
+    rescue Error => e
+      puts "Error downloading #{url}: #{e.message}"
+    end
+
+    # Wraps a block execution with a file-based lock.
+    # @param url [String] The URL string.
+    # @param filename_hint [String] The filename used for the lock.
+    # @param destination [String] The download destination directory.
+    # @yield The block to execute if the lock is acquired.
+    sig { params(url: String, filename_hint: String, destination: String, blk: T.proc.void).void }
+    def with_lock(url, filename_hint, destination, &blk)
+      lock_path = lock_path_for(url, filename_hint, destination)
+      acquired = acquire_lock(lock_path)
+      return skip_locked(filename_hint) unless acquired
+
+      blk.call
+    ensure
+      FileUtils.rm_f(lock_path) if acquired
+    end
+
+    # Prepares the destination and initiates the download with a lock.
+    # @param url [String] The URL string.
+    # @param metadata [Hash<Symbol, String>] Extracted metadata from the page.
+    # @param filename_hint [String] The filename to use.
+    # @param destination [String] The download destination directory.
+    sig { params(url: String, metadata: T::Hash[Symbol, String], filename_hint: String, destination: String).void }
+    def download_with_lock(url, metadata, filename_hint, destination)
+      FileUtils.mkdir_p(destination)
+      with_lock(url, filename_hint, destination) do
+        perform_download(url, metadata, filename_hint, destination)
+      end
+    end
+
+    # Performs the actual downloading process.
+    # @param url [String] The URL string.
+    # @param metadata [Hash<Symbol, String>] Extracted metadata from the page.
+    # @param filename_hint [String] The filename to use.
+    # @param destination [String] The download destination directory.
+    sig { params(url: String, metadata: T::Hash[Symbol, String], filename_hint: String, destination: String).void }
+    def perform_download(url, metadata, filename_hint, destination)
+      display_name = filename_hint.empty? ? 'unknown' : filename_hint
+      puts "Starting download of file: #{display_name}..."
+      io = Client.download_from_html(metadata.fetch(:html))
+      filename = extract_filename(url, io, filename_hint)
+      bytes_written, resolved_filename = FileManager.save_stream(io, filename, destination)
+      puts "Successfully downloaded #{resolved_filename} (#{bytes_written} bytes)"
+    end
+
+    # Helper method to extract filename, falling back to a default if necessary
+    # @param _url [String] The URL string.
+    # @param io [IO, StringIO, Tempfile] The IO object.
+    # @param filename_hint [String] The filename hint.
+    # @return [String] The final extracted filename.
+    sig { params(_url: String, io: T.any(IO, StringIO, Tempfile), filename_hint: String).returns(String) }
+    def extract_filename(_url, io, filename_hint = '')
+      if io.respond_to?(:original_filename) && T.unsafe(io).original_filename
+        name = T.cast(T.unsafe(io).original_filename, String)
+        fix_encoding(name)
+      elsif !filename_hint.empty?
+        filename_hint
+      else
+        # Fallback metric timestamp based filename if no headers present
+        "leechtop_#{Time.now.utc.to_i}.bin"
+      end
+    end
+  end
+end

data/lib/leechtop_downloader/cli_helpers.rb

@@ -0,0 +1,85 @@
+# typed: true
+# frozen_string_literal: true
+
+require 'sorbet-runtime'
+require 'tmpdir'
+
+module LeechtopDownloader
+  # CLIHelpers provides shared utility methods for CLI operations
+  module CLIHelpers
+    extend T::Sig
+
+    # Acquires an application-level lock to prevent concurrent executions.
+    # @yield The block to execute if the lock is acquired.
+    sig { params(blk: T.proc.void).void }
+    def with_app_lock(&blk)
+      lock_path = File.join(Dir.tmpdir, 'leechtop_downloader.lock')
+      File.open(lock_path, 'w') do |file|
+        unless file.flock(File::LOCK_EX | File::LOCK_NB)
+          Kernel.puts 'Error: Another instance of leechtop downloader is already running.'
+          Kernel.exit(1)
+        end
+
+        blk.call
+      end
+    end
+
+    # Checks if a download should be skipped because the file already exists.
+    # @param filename_hint [String] The name of the file.
+    # @param skip_existing [T::Boolean] Whether to skip existing files.
+    # @param destination [String] The download destination directory.
+    # @return [T::Boolean] true if the download should be skipped, false otherwise.
+    sig { params(filename_hint: String, skip_existing: T::Boolean, destination: String).returns(T::Boolean) }
+    def skip_download?(filename_hint, skip_existing, destination)
+      return false unless skip_existing && !filename_hint.empty?
+
+      if File.exist?(File.join(destination, filename_hint))
+        Kernel.puts "File #{filename_hint} already exists. Skipping."
+        true
+      else
+        false
+      end
+    end
+
+    # Generates a lock file path for a specific download.
+    # @param url [String] The URL being downloaded.
+    # @param filename_hint [String] The name of the file.
+    # @param destination [String] The download destination directory.
+    # @return [String] The lock file path.
+    sig { params(url: String, filename_hint: String, destination: String).returns(String) }
+    def lock_path_for(url, filename_hint, destination)
+      lock_filename = filename_hint.empty? ? "#{Digest::MD5.hexdigest(url)}.lock" : "#{filename_hint}.lock"
+      File.join(destination, lock_filename)
+    end
+
+    # Attempts to acquire a file-based lock.
+    # @param lock_path [String] The path to the lock file.
+    # @return [T::Boolean] true if lock acquired successfully, false if already exists.
+    sig { params(lock_path: String).returns(T::Boolean) }
+    def acquire_lock(lock_path)
+      File.new(lock_path, File::WRONLY | File::CREAT | File::EXCL).close
+      true
+    rescue Errno::EEXIST
+      false
+    end
+
+    # Prints a message indicating a file is currently being downloaded.
+    # @param filename_hint [String] The name of the file.
+    sig { params(filename_hint: String).void }
+    def skip_locked(filename_hint)
+      name = filename_hint.empty? ? 'File' : "File #{filename_hint}"
+      Kernel.puts "#{name} is currently being downloaded by another process. Skipping."
+    end
+
+    # Fixes mojibake or broken encoding strings to valid UTF-8.
+    # @param name [String] The possibly corrupted string.
+    # @return [String] A valid UTF-8 string.
+    sig { params(name: String).returns(String) }
+    def fix_encoding(name)
+      fixed = name.encode('iso-8859-1').force_encoding('utf-8')
+      fixed.valid_encoding? ? fixed : name
+    rescue EncodingError
+      name
+    end
+  end
+end

data/lib/leechtop_downloader/client.rb

@@ -0,0 +1,145 @@
+# typed: true
+# frozen_string_literal: true
+
+require 'sorbet-runtime'
+require 'down'
+require 'faraday'
+require 'nokogiri'
+require 'json'
+
+module LeechtopDownloader
+  # Client handles the network requests to Leechtop.
+  class Client
+    extend T::Sig
+
+    # Error class for download-specific errors.
+    class DownloadError < Error; end
+
+    # LT-REQ-002, LT-REQ-003
+    # Downloads a file from the given direct URL.
+    # @param url [String] The URL to download.
+    # @return [IO, StringIO, Tempfile] The downloaded stream.
+    sig { params(url: String).returns(T.any(IO, StringIO, Tempfile)) }
+    def self.download(url)
+      direct_url = extract_direct_url(url)
+      Down.download(direct_url, open_timeout: 10, read_timeout: 60)
+    rescue Down::NotFound
+      raise DownloadError, 'The file could not be found on the host server (404 Not Found). It may have been deleted.'
+    rescue Down::ClientError, Down::ServerError => e
+      raise DownloadError, "The host server rejected the download: #{e.message}"
+    rescue StandardError => e
+      raise DownloadError, "Network or extraction failure: #{e.message}"
+    end
+
+    # Downloads a file by extracting the direct link from the page HTML.
+    # @param html [String] The HTML content of the page.
+    # @return [IO, StringIO, Tempfile] The downloaded stream.
+    sig { params(html: String).returns(T.any(IO, StringIO, Tempfile)) }
+    def self.download_from_html(html)
+      tokens = parse_tokens(html)
+      direct_url = fetch_ajax_direct_link(tokens)
+      Down.download(direct_url, open_timeout: 10, read_timeout: 60)
+    rescue Down::NotFound
+      raise DownloadError, 'The file could not be found on the host server (404 Not Found). It may have been deleted.'
+    rescue Down::ClientError, Down::ServerError => e
+      raise DownloadError, "The host server rejected the download: #{e.message}"
+    rescue StandardError => e
+      raise DownloadError, "Network or extraction failure: #{e.message}"
+    end
+
+    # Fetches the HTML and metadata (filename) from a given URL.
+    # @param url [String] The URL to fetch.
+    # @return [Hash<Symbol, String>] The parsed metadata including html and filename.
+    sig { params(url: String).returns(T::Hash[Symbol, String]) }
+    def self.fetch_metadata(url)
+      html = fetch_html(url)
+      document = Nokogiri::HTML(html, nil, 'UTF-8')
+      h4 = document.at_css('h4.mb-2')
+      filename = h4&.text&.strip || ''
+
+      { html: html, filename: filename }
+    end
+
+    # Extracts the direct URL from the page HTML via AJAX.
+    # @param url [String] The URL to fetch.
+    # @return [String] The extracted direct URL.
+    sig { params(url: String).returns(String) }
+    def self.extract_direct_url(url)
+      html = fetch_html(url)
+      tokens = parse_tokens(html)
+      fetch_ajax_direct_link(tokens)
+    end
+
+    # Fetches the raw HTML content from a URL.
+    # @param url [String] The URL to fetch.
+    # @return [String] The HTML content.
+    sig { params(url: String).returns(String) }
+    def self.fetch_html(url)
+      response = Faraday.new(request: { open_timeout: 10, timeout: 60 }).get(url)
+      raise "Failed to load page: HTTP #{response.status}" unless response.status == 200
+
+      response.body
+    end
+
+    # Parses the necessary tokens from the given HTML string.
+    # @param html [String] The HTML content.
+    # @return [Hash<Symbol, String>] The extracted tokens.
+    sig { params(html: String).returns(T::Hash[Symbol, String]) }
+    def self.parse_tokens(html)
+      document = Nokogiri::HTML(html, nil, 'UTF-8')
+
+      button = document.at_css('.go-download-direct')
+      raise 'Could not find download button in HTML' unless button
+
+      nonce_match = html.match(/"nonce":"([^"]+)"/)
+      raise 'Could not extract nonce from page' unless nonce_match
+
+      {
+        p: T.must(button['data-p']),
+        mb: T.must(button['data-mb']),
+        nonce: T.must(nonce_match[1])
+      }
+    end
+
+    # Submits the parsed tokens via AJAX to obtain the direct download link.
+    # @param tokens [Hash<Symbol, String>] The extracted tokens.
+    # @return [String] The direct download link.
+    sig { params(tokens: T::Hash[Symbol, String]).returns(String) }
+    def self.fetch_ajax_direct_link(tokens)
+      ajax_url = 'https://leechtop.com/wp-admin/admin-ajax.php'
+      body = URI.encode_www_form({ action: 'z_do_ajax', _action: 'directDownload' }.merge(tokens))
+      post_response = Faraday.new(request: { open_timeout: 10, timeout: 60 }).post(ajax_url, body)
+
+      raise "AJAX request failed: HTTP #{post_response.status}" unless post_response.status == 200
+
+      parse_ajax_response(post_response.body)
+    end
+
+    # Parses the AJAX response to extract the direct link.
+    # @param body [String] The JSON string.
+    # @return [String] The extracted direct download link.
+    sig { params(body: String).returns(String) }
+    def self.parse_ajax_response(body)
+      json = JSON.parse(body)
+      direct_link = json['mes']
+
+      raise "Server rejected download request: #{json}" if direct_link == 'no' || direct_link.nil?
+
+      direct_link
+    end
+
+    # Extracts all Leechtop links from a given page HTML.
+    # @param url [String] The URL to fetch.
+    # @return [Array<String>] The extracted URLs.
+    sig { params(url: String).returns(T::Array[String]) }
+    def self.extract_page_links(url)
+      html = fetch_html(url)
+      document = Nokogiri::HTML(html, nil, 'UTF-8')
+
+      document.css('a').filter_map do |a|
+        href = a['href']
+        href if href&.match?(%r{^https?://(?:www\.)?leechtop\.com/})
+      end
+    end
+  end
+end

data/lib/leechtop_downloader/file_manager.rb

@@ -0,0 +1,82 @@
+# typed: true
+# frozen_string_literal: true
+
+require 'sorbet-runtime'
+require 'fileutils'
+
+module LeechtopDownloader
+  # FileManager handles the physical saving of files using Metric/UTC standards.
+  class FileManager
+    extend T::Sig
+
+    # LT-REQ-003, LT-REQ-004, LT-REQ-005, LT-REQ-006, BUG-LT-001
+    # Saves an IO stream to the specified destination directory.
+    # @param io [IO, StringIO, Tempfile] The stream to read from.
+    # @param filename [String] The name of the file to save.
+    # @param destination [String] The directory where the file will be saved.
+    # @return [Array<Integer, String>] The number of bytes written and the final resolved filename.
+    sig { params(io: T.any(IO, StringIO, Tempfile), filename: String, destination: String).returns([Integer, String]) }
+    def self.save_stream(io, filename, destination = '.')
+      # Enforcement of UTC and Metric standards
+      FileUtils.mkdir_p(destination)
+      resolved_filename = resolve_filename(filename, destination)
+      filepath = File.join(destination, resolved_filename)
+
+      bytes_written = write_stream(io, filepath)
+
+      # Enforce UTC timestamps on the generated file
+      utc_now = Time.now.utc
+      File.utime(utc_now, utc_now, filepath)
+
+      [bytes_written, resolved_filename]
+    end
+
+    # Resolves a unique filename within the specified directory.
+    # @param original_filename [String] The original requested filename.
+    # @param directory [String] The destination directory.
+    # @return [String] A unique filename string.
+    sig { params(original_filename: String, directory: String).returns(String) }
+    def self.resolve_filename(original_filename, directory)
+      return original_filename unless File.exist?(File.join(directory, original_filename))
+
+      ext = File.extname(original_filename)
+      base = File.basename(original_filename, ext)
+      find_unique_filename(base, ext, directory, original_filename)
+    end
+
+    # Finds a unique filename by appending an incremental counter.
+    # @param base [String] The base filename without extension.
+    # @param ext [String] The file extension.
+    # @param dir [String] The directory to check for existence.
+    # @param orig [String] The original filename, used for warning messages.
+    # @return [String] A unique filename string.
+    sig { params(base: String, ext: String, dir: String, orig: String).returns(String) }
+    def self.find_unique_filename(base, ext, dir, orig)
+      counter = 1
+      loop do
+        name = "#{base}_#{counter}#{ext}"
+        unless File.exist?(File.join(dir, name))
+          puts "Warning: File '#{orig}' already exists. Saving as '#{name}'"
+          return name
+        end
+        counter += 1
+      end
+    end
+
+    # Writes chunks of data from an IO stream to a physical file.
+    # @param io [IO, StringIO, Tempfile] The stream to read from.
+    # @param filepath [String] The full path to the destination file.
+    # @return [Integer] The total number of bytes written.
+    sig { params(io: T.any(IO, StringIO, Tempfile), filepath: String).returns(Integer) }
+    def self.write_stream(io, filepath)
+      bytes_written = 0
+      File.open(filepath, 'wb') do |file|
+        while (chunk = io.read(8192)) # 8 KB metric chunking
+          file.write(chunk)
+          bytes_written += chunk.bytesize
+        end
+      end
+      bytes_written
+    end
+  end
+end

data/lib/leechtop_downloader/version.rb

@@ -0,0 +1,8 @@
+# typed: true
+# frozen_string_literal: true
+
+# The main module for the LeechtopDownloader application.
+module LeechtopDownloader
+  # The current version of the application.
+  VERSION = '0.1.3'
+end

data/lib/leechtop_downloader.rb

@@ -0,0 +1,16 @@
+# typed: true
+# frozen_string_literal: true
+
+require 'sorbet-runtime'
+require 'dotenv/load'
+
+# The main module for the LeechtopDownloader application.
+module LeechtopDownloader
+  # Standard Error class for the application.
+  class Error < StandardError; end
+end
+
+require_relative 'leechtop_downloader/version'
+require_relative 'leechtop_downloader/file_manager'
+require_relative 'leechtop_downloader/client'
+require_relative 'leechtop_downloader/cli'

metadata

@@ -0,0 +1,306 @@
+--- !ruby/object:Gem::Specification
+name: leechtop_downloader
+version: !ruby/object:Gem::Version
+  version: 0.1.3
+platform: ruby
+authors:
+- Vitalii Lazebnyi
+bindir: exe
+cert_chain:
+- |
+  -----BEGIN CERTIFICATE-----
+  MIIEOTCCAqGgAwIBAgIUBONmsFo7fxLGkUHsKe65onH+5ogwDQYJKoZIhvcNAQEL
+  BQAwLDEqMCgGA1UEAwwhdml0YWxpaS5sYXplYm55aS5naXRodWJAZ21haWwuY29t
+  MB4XDTI2MDQxNTEzNTMyOVoXDTM2MDQxMjEzNTMyOVowLDEqMCgGA1UEAwwhdml0
+  YWxpaS5sYXplYm55aS5naXRodWJAZ21haWwuY29tMIIBojANBgkqhkiG9w0BAQEF
+  AAOCAY8AMIIBigKCAYEA5zdezJE+Zrsk9j53/IxBfRoaqvLcPvrcfl+EaEwWhIkV
+  0+08GtgS9N7VpB8cgaH2rkLJPjHIetsN/g5GMkDRsbJNXMrPVhxe1e1lI/r6j0Tm
+  JD0PaU4r8VzitxkqY9BBmSI8GjDjAfrT1u5jSXH1iAtKUoq5F116uYrxbgiDpvqa
+  kUQYcTf+6cZaPlF4KKhULnhKqs8u/NxyH4vPZyxEfg/gA4bODvcjW1A6d59BTiLV
+  yrJPebwU+F+URb8aoQ4AGvPKFiG1Y1fxRHuPrOpyymFnBnjwgMyQkNHtzTeEriV9
+  z1BUb10Pb/pjLBCrOvnStTPmcm1GE8HL2psYvlLvBlYqq3gzpQPBBKE3Jefa7ilC
+  cYsBYOGpynpA9uu9cXKa4jtpPDGQ7Qrpnk9gHy/0xfbgLdAkRCoZJeR7wDL/1xmm
+  nXwcUOLSOBj1Y4P9M+uQSQUZFTAaLbwyaBfE1gvVjwbTv3+rNP1ck1hACt+numGG
+  m7R6MF+Hmh8pNnDBYpBNAgMBAAGjUzBRMB0GA1UdDgQWBBRbuaz1EhdG6T4KIeWr
+  ac8LULxO9zAfBgNVHSMEGDAWgBRbuaz1EhdG6T4KIeWrac8LULxO9zAPBgNVHRMB
+  Af8EBTADAQH/MA0GCSqGSIb3DQEBCwUAA4IBgQBgfGTDIMxlm6o8o7dzCR0HosRm
+  DSeUrx46EG1knTEqO05CooEHW98hrHa1/EwzkPaH1KhjjserQb6VtczMnySlfySu
+  HbKWAIaqzlpf8zaE5tCiAKgFKr77b2XB7xKt25p/Vf/Kn/RLm3+sYQ2izzzMimei
+  tBHo29cLV9bB/5HHFDwjrtdC5a0HJHiir0w4MCSDDGtnsKird4RKD2xESpoVjiNg
+  L9nEGk25YDeIfKn8UtxduMv53T86CiBSsDcEb6oVjNiMOA0HFucwFKX+Vy5u0/qx
+  ZRoLbZiCkTTGyNkBh4o6RCCTn37Lj98FBxYMbAHLNhEcKnAGxB7XP/CYsV4+QHOy
+  h0PctylhIvm24QeKgIWJUWamFPfqdvlP660T4umxl2wMqvNpWmGMmGTMCraoKwxl
+  zpp6uA15MXgTU7CxGivRgUKM64TqBMZKkOJcCtPkruSobxiR8cROrBNTqEbrmedM
+  26EUEoxwDzfSzHU2SKz5pMR+8DClMUKB1rctg68=
+  -----END CERTIFICATE-----
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: dotenv
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: down
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: nokogiri
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: sorbet-runtime
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.6'
+- !ruby/object:Gem::Dependency
+  name: thor
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.86'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.86'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.9'
+- !ruby/object:Gem::Dependency
+  name: rubocop-sorbet
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.12'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+- !ruby/object:Gem::Dependency
+  name: sorbet
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.6'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.6'
+- !ruby/object:Gem::Dependency
+  name: tapioca
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.19'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.19'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.26'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.26'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+- !ruby/object:Gem::Dependency
+  name: yard-sorbet
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+description: A robust command-line tool that automates extracting direct download
+  links and saving files from leechtop.com. Supports batch processing, duplicate skipping,
+  and safe concurrency.
+email:
+- vitalii.lazebnyi.github@gmail.com
+executables:
+- leechtop
+extensions: []
+extra_rdoc_files: []
+files:
+- Gemfile
+- LICENSE.txt
+- README.md
+- certs/leechtop_downloader-public_cert.pem
+- exe/leechtop
+- leechtop_downloader.gemspec
+- lib/leechtop_downloader.rb
+- lib/leechtop_downloader/cli.rb
+- lib/leechtop_downloader/cli_helpers.rb
+- lib/leechtop_downloader/client.rb
+- lib/leechtop_downloader/file_manager.rb
+- lib/leechtop_downloader/version.rb
+homepage: https://github.com/VitaliiLazebnyi/leechtop-downloader
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.10
+specification_version: 4
+summary: CLI utility to download files from leechtop.com.
+test_files: []

metadata.gz.sig

@@ -0,0 +1 @@
+5e�s�%����]���T��A