neocities-red 1.1.2 → 1.2.0

data/lib/neocities_red/services/common/pizza.rb

@@ -4,8 +4,18 @@ require "pastel"
 
 module NeocitiesRed
   module Services
+    # Shared service utilities used across file and site operations.
     module Common
+      # Easter egg — returns a random humorous excuse for why pizza
+      # is unavailable.
+      #
+      # Invoked via the +neocities-red pizza+ CLI command.
+      #
+      # @example
+      #   excuse = Pizza.new.make_order
+      #   puts excuse
       class Pizza
+        # @return [Array<String>] pool of humorous pizza excuses
         EXCUSES = [
           "Sorry, we're fresh out of pineapple today.",
           "All the toppings just went rogue and are currently answering to no god.",
@@ -24,12 +34,12 @@ module NeocitiesRed
           <<~TEXT
             WAR AND PEACE, BY LEO TOLSTOY, BOOK ONE: 1805, CHAPTER I
 
-            “Well, Prince, so Genoa and Lucca are now just family estates of the Buonapartes.
-            But I warn you, if you don’t tell me that this means war, if you still try to defend
+            "Well, Prince, so Genoa and Lucca are now just family estates of the Buonapartes.
+            But I warn you, if you don't tell me that this means war, if you still try to defend
             the infamies and horrors perpetrated by that Antichrist—I really believe he is
             Antichrist—I will have nothing more to do with you and you are no longer my friend,
-            no longer my ‘faithful slave,’ as you call yourself! But how do you do? I see I have
-            frightened you—sit down and tell me all the news.”
+            no longer my 'faithful slave,' as you call yourself! But how do you do? I see I have
+            frightened you—sit down and tell me all the news."
 
             It was in July, 1805, and the speaker was the well-known Anna Pávlovna Schérer,
             maid of honor and favorite of the Empress Márya Fëdorovna. With these words she
@@ -42,11 +52,11 @@ module NeocitiesRed
             All her invitations without exception, written in French, and delivered by a
             scarlet-liveried footman that morning, ran as follows:
 
-            “If you have nothing better to do, Count (or Prince), and if the prospect of
+            "If you have nothing better to do, Count (or Prince), and if the prospect of
             spending an evening with a poor invalid is not too terrible, I shall be very
-            charmed to see you tonight between 7 and 10—Annette Schérer.”
+            charmed to see you tonight between 7 and 10—Annette Schérer."
 
-            “Heavens! what a virulent attack!” replied the prince, not in the least disconcerted
+            "Heavens! what a virulent attack!" replied the prince, not in the least disconcerted
             by this reception.
 
             He had just entered, wearing an embroidered court uniform, knee breeches, and
@@ -59,32 +69,32 @@ module NeocitiesRed
             He went up to Anna Pávlovna, kissed her hand, presenting to her his bald, scented,
             and shining head, and complacently seated himself on the sofa.
 
-            “First of all, dear friend, tell me how you are. Set your friend’s mind at rest,”
+            "First of all, dear friend, tell me how you are. Set your friend's mind at rest,"
             said he without altering his tone, beneath the politeness and affected sympathy of
             which indifference and even irony could be discerned.
 
-            “Can one be well while suffering morally? Can one be calm in times like these if
-            one has any feeling?” said Anna Pávlovna. “You are staying the whole evening, I hope?”
+            "Can one be well while suffering morally? Can one be calm in times like these if
+            one has any feeling?" said Anna Pávlovna. "You are staying the whole evening, I hope?"
 
-            “And the fete at the English ambassador’s? Today is Wednesday. I must put in an
-            appearance there,” said the prince. “My daughter is coming for me to take me there.”
+            "And the fete at the English ambassador's? Today is Wednesday. I must put in an
+            appearance there," said the prince. "My daughter is coming for me to take me there."
 
-            “I thought today’s fete had been canceled. I confess all these festivities and
-            fireworks are becoming wearisome.”
+            "I thought today's fete had been canceled. I confess all these festivities and
+            fireworks are becoming wearisome."
 
-            “If they had known that you wished it, the entertainment would have been put off,”
+            "If they had known that you wished it, the entertainment would have been put off,"
             said the prince, who, like a wound-up clock, by force of habit said things he did
             not even wish to be believed.
 
-            “Don’t tease! Well, and what has been decided about Novosíltsev’s dispatch?
-            You know everything.”
+            "Don't tease! Well, and what has been decided about Novosíltsev's dispatch?
+            You know everything."
 
-            “What can one say about it?” replied the prince in a cold, listless tone.
-            “What has been decided? They have decided that Buonaparte has burnt his boats,
-            and I believe that we are ready to burn ours.”
+            "What can one say about it?" replied the prince in a cold, listless tone.
+            "What has been decided? They have decided that Buonaparte has burnt his boats,
+            and I believe that we are ready to burn ours."
 
             Prince Vasíli always spoke languidly, like an actor repeating a stale part.
-            Anna Pávlovna Schérer on the contrary, despite her forty years, overflowed with
+            Anna Pávlovna Schérer on the contrary, despite of her forty years, overflowed with
             animation and impulsiveness.
 
             To be an enthusiast had become her social vocation and, sometimes even when she
@@ -98,6 +108,9 @@ module NeocitiesRed
           TEXT
         ].freeze
 
+        # Returns a random pizza excuse.
+        #
+        # @return [String] a humorous excuse rendered in bright red via Pastel
         def make_order
           Pastel.new(enabled: true).bright_red(EXCUSES.sample)
         end

data/lib/neocities_red/services/common/worker_pool.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module NeocitiesRed
+  module Services
+    module Common
+      # A simple thread pool for parallel task execution.
+      #
+      # Processes a list of items concurrently using a fixed number of
+      # worker threads. Each item is passed to the block provided at
+      # construction time.
+      #
+      # @example
+      #   pool = WorkerPool.new(5) { |item| puts item }
+      #   pool.process([1, 2, 3, 4, 5])
+      #
+      # @see NeocitiesRed::Services::File::FolderUploader Uses for parallel uploads
+      # @see NeocitiesRed::Services::Site::Pusher Uses for parallel uploads
+      class WorkerPool
+        # @param size [Integer] number of concurrent worker threads
+        # @yield [item] block to execute for each item
+        # @yieldparam item [Object] an item from the processing queue
+        def initialize(size, &block)
+          @size = size
+          @block = block
+        end
+
+        # Processes all items in the pool using worker threads.
+        #
+        # Items are placed in a thread-safe queue and consumed by workers.
+        # The method blocks until all items have been processed.
+        #
+        # @param items [Array<Object>] items to process
+        # @return [void]
+        def process(items)
+          queue = Queue.new
+          items.each { |item| queue << item }
+
+          workers = Array.new(@size) do
+            Thread.new do
+              loop do
+                item = queue.pop(true)
+                @block.call(item)
+              rescue ThreadError
+                break
+              end
+            end
+          end
+
+          workers.each(&:join)
+        end
+      end
+    end
+  end
+end

data/lib/neocities_red/services/file/folder_uploader.rb

@@ -1,30 +1,52 @@
 # frozen_string_literal: true
 
 require "pathname"
-require "pastel"
 
 module NeocitiesRed
   module Services
     module File
-      # warning - the big quantity of working threads could be considered like-a DDOS.
-      # Your ip-address could get banned for a few days.
+      # Maximum number of concurrent upload threads.
+      #
+      # Warning: a high thread count may be flagged as DDOS-like traffic
+      # by Neocities, potentially resulting in a temporary IP ban.
       MAX_THREADS = 5
 
+      # Uploads all files in a local directory to the remote site in parallel.
+      #
+      # Uses a {Services::Common::WorkerPool} to upload files concurrently
+      # up to {MAX_THREADS} threads. Each file is uploaded via {Uploader}.
+      #
+      # @example
+      #   folder = NeocitiesRed::Services::File::FolderUploader.new(client, "./dist", "assets", display: display)
+      #   files = folder.files
+      #   folder.upload(files)
+      #
+      # @see NeocitiesRed::Services::File::Uploader Individual file upload
+      # @see NeocitiesRed::Services::Common::WorkerPool Thread pool
       class FolderUploader
-        def initialize(client, filepath, remote_path)
+        # @param client [NeocitiesRed::Client] authenticated API client
+        # @param filepath [String] local directory path to upload
+        # @param remote_path [String] remote destination directory
+        # @param display [NeocitiesRed::CliDisplay] output helper
+        def initialize(client, filepath, remote_path, display: NeocitiesRed::CliDisplay.new)
           @client = client
           @filepath = filepath
           @remote_path = remote_path
-          @pastel = Pastel.new(eachline: "\n")
+          @display = display
         end
 
+        # Recursively lists all files in the local directory.
+        #
+        # @return [Array<String>] relative file paths within the directory
+        # @raise [NeocitiesRed::FileNotFoundError] if the directory does not exist
+        # @return [nil] if the path is a file (not a directory)
         def files
           path = Pathname.new(::File.expand_path(@filepath))
 
-          raise FileIsNotExists, "#{path} does not exist locally." unless path.exist?
+          raise NeocitiesRed::FileNotFoundError, "#{path} does not exist locally." unless path.exist?
 
           if path.file?
-            puts @pastel.bold("#{path} is not a directory, skipping")
+            @display.display_skip_file(path)
             return
           end
 
@@ -34,30 +56,22 @@ module NeocitiesRed
           end
         end
 
+        # Uploads all files in the list concurrently.
+        #
+        # @param files_list [Array<String>] relative file paths to upload
+        # @param threads [Integer] maximum concurrent upload threads (default: {MAX_THREADS})
+        # @return [void]
         def upload(files_list, threads = MAX_THREADS)
           base = ::File.expand_path(@filepath)
 
-          queue = Queue.new
-          files_list.each { |file| queue << file }
+          worker_pool = Services::Common::WorkerPool.new(threads) do |file|
+            local_path  = ::File.join(base, file)
+            remote_path = ::File.join(@remote_path, file)
 
-          workers = Array.new(threads) do
-            Thread.new do
-              loop do
-                begin
-                  file = queue.pop(true)
-                rescue ThreadError
-                  break
-                end
-
-                local_path  = ::File.join(base, file)
-                remote_path = ::File.join(@remote_path, file)
-
-                Uploader.new(@client, local_path, remote_path).upload
-              end
-            end
+            Uploader.new(@client, local_path, remote_path, display: @display).upload
           end
 
-          workers.each(&:join)
+          worker_pool.process(files_list)
         end
       end
     end

data/lib/neocities_red/services/file/list.rb

@@ -6,58 +6,88 @@ require "tty/table"
 
 module NeocitiesRed
   module Services
+    # File-level operations: upload, delete, and list.
     module File
+      # Lists files on the remote Neocities site.
+      #
+      # Supports both a simple list mode and a detailed table mode
+      # with file size, SHA1 hash, and last-updated timestamp.
+      #
+      # @example Simple listing
+      #   list = NeocitiesRed::Services::File::List.new(client, nil, false, display: display)
+      #   files = list.show
+      #
+      # @example Detailed table
+      #   list = NeocitiesRed::Services::File::List.new(client, nil, true, display: display)
+      #   list.show  # renders TTY::Table
+      #
+      # @see NeocitiesRed::Client#list Underlying API call
       class List
-        def initialize(client, path, detail)
+        # @param client [NeocitiesRed::Client] authenticated API client
+        # @param path [String, nil] remote directory path to list (nil for root)
+        # @param detail [Boolean] when true, renders a detailed table with
+        #   size, hash, and timestamp columns
+        # @param display [NeocitiesRed::CliDisplay] output helper
+        def initialize(client, path, detail, display: NeocitiesRed::CliDisplay.new)
           @client = client
           @path = path
           @detail = detail || false
+          @display = display
           @pastel = Pastel.new(eachline: "\n")
         end
 
+        # Returns the raw list of remote files.
+        #
+        # @return [Array<Hash>] array of file hashes with +:path+, +:is_directory+,
+        #   +:size+, +:sha1_hash+, and +:updated_at+ keys
+        # @raise [NeocitiesRed::APIError] if the API returns an error
         def list
-          resp = @client.list(@path)
-
-          display_error_and_exit(resp) if resp[:result] == "error"
-
-          resp[:files]
+          files_from_response
         end
 
+        # Returns the file list, optionally rendered as a detailed table.
+        #
+        # In detail mode, displays a colored table with Path, Size, SHA1 Hash,
+        # and Updated columns. Directories are shown in blue, files in green.
+        #
+        # @return [Array<Hash>] the file list hashes
+        # @raise [NeocitiesRed::APIError] if the API returns an error
         def show
-          resp = @client.list(@path)
-
-          display_error_and_exit(resp) if resp[:result] == "error"
+          files = files_from_response
 
-          if @detail
-            out = [
-              [@pastel.bold("Path"), @pastel.bold("Size"), @pastel.bold("sha1_Hash"),
-               @pastel.bold("Updated")]
-            ]
+          return files unless @detail
 
-            resp[:files].each do |file|
-              out.push([
-                         @pastel.send(file[:is_directory] ? :blue : :green).bold(file[:path]),
-                         file[:size] || "",
-                         file[:sha1_hash],
-                         Time.parse(file[:updated_at]).localtime
-                       ])
-            end
+          out = [
+            [@pastel.bold("Path"), @pastel.bold("Size"), @pastel.bold("sha1_Hash"),
+             @pastel.bold("Updated")]
+          ]
 
-            puts TTY::Table.new(out)
+          files.each do |file|
+            out.push([
+                       @pastel.send(file[:is_directory] ? :blue : :green).bold(file[:path]),
+                       file[:size] || "",
+                       file[:sha1_hash],
+                       Time.parse(file[:updated_at]).localtime
+                     ])
           end
 
-          resp[:files].map do |file|
-            @pastel.send(file[:is_directory] ? :blue : :green).bold(file[:path])
-          end
+          @display.display_list_table(TTY::Table.new(out))
 
-          resp[:files]
+          files
         end
 
         private
 
-        def display_error_and_exit(resp)
-          puts(resp[:message] || resp[:error_type] || resp.inspect)
-          exit
+        # Fetches and validates the file list from the API.
+        #
+        # @return [Array<Hash>] file hashes from the API response
+        # @raise [NeocitiesRed::APIError] if the response indicates an error
+        def files_from_response
+          resp = @client.list(@path)
+
+          raise NeocitiesRed::APIError, resp[:message] || resp[:error_type] || resp.inspect if resp[:result] == "error"
+
+          resp[:files]
         end
       end
     end

data/lib/neocities_red/services/file/remover.rb

@@ -1,30 +1,45 @@
 # frozen_string_literal: true
 
-require "pastel"
-
 module NeocitiesRed
   module Services
     module File
+      # Deletes a single file from the remote Neocities site.
+      #
+      # Displays progress and result feedback via {CliDisplay}.
+      #
+      # @example
+      #   remover = NeocitiesRed::Services::File::Remover.new(client, "old-file.html", display: display)
+      #   remover.remove
+      #
+      # @see NeocitiesRed::Client#delete Underlying delete API call
       class Remover
-        attr_accessor :client, :filepath
+        # @return [NeocitiesRed::Client] the authenticated API client
+        attr_reader :client
+
+        # @return [String] the remote file path to delete
+        attr_accessor :filepath
 
-        def initialize(client, filepath)
+        # @param client [NeocitiesRed::Client] authenticated API client
+        # @param filepath [String] remote file path to delete
+        # @param display [NeocitiesRed::CliDisplay] output helper
+        def initialize(client, filepath, display: NeocitiesRed::CliDisplay.new)
           @client = client
           @filepath = filepath
-          @pastel = Pastel.new(eachline: "\n")
+          @display = display
         end
 
+        # Deletes the file from the remote site.
+        #
+        # @return [Hash] API response with +:result+ key ("success" or "error")
         def remove
-          puts @pastel.bold("Deleting #{filepath} ...")
+          @display.display_delete_progress(filepath)
 
           response = @client.delete(filepath)
 
-          puts @pastel.bold(response[:message]) if response[:result] == "error"
-
-          if response[:result] == "error" && response[:error_type] == "file_exists"
-            print @pastel.yellow.bold("EXISTS")
-          elsif response[:result] == "success"
-            print @pastel.green.bold("SUCCESS")
+          if response[:result] == "success"
+            @display.display_delete_success
+          else
+            @display.display_delete_error(response)
           end
 
           response

data/lib/neocities_red/services/file/uploader.rb

@@ -1,40 +1,60 @@
 # frozen_string_literal: true
 
 require "pathname"
-require "pastel"
 
 module NeocitiesRed
   module Services
     module File
-      class FileIsNotExists < StandardError; end
-
+      # Uploads a single file to the Neocities site.
+      #
+      # Handles display feedback for the upload lifecycle: progress,
+      # success, already-exists, and directory-skip scenarios.
+      #
+      # @example
+      #   uploader = NeocitiesRed::Services::File::Uploader.new(client, "index.html", display: display)
+      #   uploader.upload
+      #
+      # @see NeocitiesRed::Client#upload Underlying upload method
       class Uploader
-        def initialize(client, filepath, remote_path = nil)
+        # @param client [NeocitiesRed::Client] authenticated API client
+        # @param filepath [String] local file path to upload
+        # @param remote_path [String, nil] remote destination path;
+        #   defaults to the file's basename
+        # @param display [NeocitiesRed::CliDisplay] output helper
+        def initialize(client, filepath, remote_path = nil, display: NeocitiesRed::CliDisplay.new)
           @client = client
           @filepath = filepath
           @remote_path = remote_path
-          @pastel = Pastel.new(eachline: "\n")
+          @display = display
         end
 
+        # Uploads the file to the remote site.
+        #
+        # Skips directories with a display message. Computes the SHA1 hash
+        # and skips the upload if the remote file is identical.
+        #
+        # @return [Hash] API response with +:result+ key
+        # @raise [NeocitiesRed::FileNotFoundError] if the local file does not exist
         def upload
           path = Pathname.new(@filepath)
 
-          raise FileIsNotExists, "#{path} does not exist locally." unless path.exist?
+          raise NeocitiesRed::FileNotFoundError, "#{path} does not exist locally." unless path.exist?
 
           if path.directory?
-            puts @pastel.bold("#{path} is a directory, skipping")
+            @display.display_skip_directory(path)
             return
           end
 
-          puts @pastel.bold("Uploading #{path} to #{@remote_path} ...")
+          @display.display_upload_progress(path, @remote_path)
 
           response = @client.upload(path, @remote_path)
-          puts response if response[:result] == "error"
 
-          if response[:result] == "error" && response[:error_type] == "file_exists"
-            puts @pastel.yellow.bold("EXISTS")
-          elsif response[:result] == "success"
-            puts @pastel.green.bold("SUCCESS")
+          if response[:result] == "success"
+            @display.display_upload_success
+          elsif response[:result] == "error" && response[:error_type] == "file_exists"
+            @display.display_upload_exists
+          else
+            @display.display_response(response)
           end
 
           response

data/lib/neocities_red/services/site/differencer.rb

@@ -6,7 +6,29 @@ require "tty/table"
 module NeocitiesRed
   module Services
     module Site
+      # Compares local files against the remote Neocities site.
+      #
+      # Identifies three categories of differences:
+      # - **Added** — files present locally but not on the server
+      # - **Modified** — files present in both but with different SHA1 hashes
+      # - **Removed** — files present on the server but not locally
+      #
+      # Results are color-coded: green for added, yellow for modified,
+      # red for removed.
+      #
+      # @example
+      #   differencer = NeocitiesRed::Services::Site::Differencer.new(
+      #     client, path: ".", detail: false, ignore_dotfiles: false, exclude: []
+      #   )
+      #   added, modified, removed = differencer.show
+      #
+      # @see NeocitiesRed::Services::File::List Fetches the remote file list
       class Differencer
+        # @param client [NeocitiesRed::Client] authenticated API client
+        # @param path [String] local directory path to compare (default: ".")
+        # @param detail [Boolean] whether to show detailed output (default: false)
+        # @param ignore_dotfiles [Boolean] when true, ignores files starting with "."
+        # @param exclude [Array<String>] local paths to exclude from comparison
         def initialize(client, path: ".", detail: false, ignore_dotfiles: false, exclude: [])
           @client = client
           @path = path
@@ -16,6 +38,11 @@ module NeocitiesRed
           @pastel = Pastel.new(eachline: "\n")
         end
 
+        # Computes the diff between local and remote files.
+        #
+        # @return [Array(Array<String>, Array<String>, Array<String>)]
+        #   a tuple of +[added, modified, removed]+, where each element
+        #   is an array of color-coded file path strings
         def show
           server_files = Services::File::List.new(@client, nil, @detail).show
 
@@ -28,27 +55,30 @@ module NeocitiesRed
           Dir.chdir(root_path) do
             paths = Dir.glob(::File.join("**", "*"), ::File::FNM_DOTMATCH)
 
-            local_paths = paths.reject { |path| path.start_with?(".") }
-            local_files = local_paths.select { |path| ::File.file?(path) }.map do |path|
-              {
-                path: path,
-                sha1_hash: Digest::SHA1.file(path).hexdigest
-              }
-            end
-            server_paths = server_files.map { |n| n[:path] }
-
-            server_file_map = server_files.to_h do |file|
+            server_file_entries = server_files.reject { |file| file[:is_directory] }
+            server_paths = server_file_entries.map { |file| file[:path] }
+            server_file_map = server_file_entries.to_h do |file|
               [file[:path], file[:sha1_hash]]
             end
 
+            local_paths = paths
+
             if @ignore_dotfiles
               server_paths = server_paths.reject { |path| path.start_with?(".") }
               local_paths = local_paths.reject { |path| path.start_with?(".") }
             end
 
+            local_files = local_paths.select { |path| ::File.file?(path) }.map do |path|
+              {
+                path: path,
+                sha1_hash: Digest::SHA1.file(path).hexdigest
+              }
+            end
+
             if @exclude.any?
-              server_paths -= @exclude
-              local_paths -= @exclude
+              normalized_exclude = @exclude.map { |path| Pathname.new(path).cleanpath.to_s }
+              server_paths -= normalized_exclude
+              local_paths -= normalized_exclude
             end
 
             removed_paths = server_paths - local_paths