neocities-red 1.1.2 → 1.2.0

data/lib/neocities_red/cli_display.rb

@@ -3,19 +3,54 @@
 require "pastel"
 
 module NeocitiesRed
+  # Terminal output helper for the CLI.
+  #
+  # Wraps all user-facing output — progress indicators, success/error
+  # messages, help screens, and the ASCII art banner. Uses Pastel for
+  # colored and styled terminal output.
+  #
+  # Every +display_*+ method prints to stdout and may call +exit+
+  # (for help screens). Non-help methods return +nil+.
+  #
+  # @example
+  #   display = NeocitiesRed::CliDisplay.new
+  #   display.display_response(result: "success", message: "Uploaded!")
+  #
+  # @see NeocitiesRed::CLI Uses this class for all terminal output
   class CliDisplay
+    # @return [Array<String>] Mouth sprites for the Penelope banner cat.
     PENELOPE_MOUTHS = %w[^ o ~ - v U].freeze
+
+    # @return [Array<String>] Eye sprites for the Penelope banner cat.
     PENELOPE_EYES = %w[o ~ O].freeze
 
+    # Creates a new display instance.
+    #
+    # @param io [IO] output stream (defaults to +$stdout+; inject a
+    #   StringIO for testing)
     def initialize(io: $stdout)
       @io = io
       @pastel = Pastel.new(eachline: "\n")
     end
 
+    # Prints a message followed by a newline.
+    #
+    # @param message [String] text to print
+    # @return [void]
     def say(message = "")
       @io.puts(message)
     end
 
+    # Displays an API response with appropriate coloring.
+    #
+    # Handles three response shapes:
+    # - +Exception+ — prints the error message in red and exits
+    # - +:result == "success"+ — prints in green
+    # - +:result == "error" && :error_type == "file_exists"+ — prints in yellow
+    # - All other errors — prints in red
+    #
+    # @param resp [Hash, Exception] API response or exception
+    # @return [void]
     def display_response(resp)
       if resp.is_a?(Exception)
         say "#{@pastel.red.bold('ERROR:')} #{resp.detailed_message}"
@@ -35,6 +70,15 @@ module NeocitiesRed
       end
     end
 
+    # Displays the results of a diff operation.
+    #
+    # Prints removed files in red, modified files in yellow,
+    # and added files in green. Each section is only shown if non-empty.
+    #
+    # @param added [Array<String>] local files not present on the server
+    # @param modified [Array<String>] files whose SHA1 hash differs
+    # @param removed [Array<String>] server files not present locally
+    # @return [void]
     def display_diff_results(added:, modified:, removed:)
       if removed.any?
         say @pastel.bold.red("Removed files")
@@ -52,52 +96,171 @@ module NeocitiesRed
       say added
     end
 
+    # Prints the interactive login prompt message.
+    #
+    # @return [void]
     def display_login_prompt
       say "Please login to get your API key:"
     end
 
+    # Confirms that the API key has been saved to disk.
+    #
+    # @param sitename [String] the site name
+    # @param path [String] the config file path where the key was stored
+    # @return [void]
     def display_api_key_saved(sitename, path)
       say "The api key for #{@pastel.bold(sitename)} has been stored in #{@pastel.bold(path)}."
     end
 
-    def display_unknown_option(option)
-      say @pastel.red.bold("Unknown option: #{option.inspect}")
-    end
-
+    # Displays a logout success message.
+    #
+    # @return [void]
     def display_logout_success
       say @pastel.bold("Your api key has been removed.")
     end
 
+    # Displays a notice that the current operation is a dry run.
+    #
+    # @return [void]
     def display_dry_run_notice
       say @pastel.green.bold("Doing a dry run, not actually pushing anything")
     end
 
+    # Prints the file deletion progress indicator (without newline).
+    #
+    # @param path [String] remote file path being deleted
+    # @return [void]
     def display_delete_progress(path)
       @io.print @pastel.bold("Deleting #{path} ... ")
     end
 
+    # Prints a green "SUCCESS" after a file is deleted.
+    #
+    # @return [void]
     def display_delete_success
       @io.print "#{@pastel.green.bold('SUCCESS')}\n"
     end
 
+    # Prints an error response that occurred during file deletion.
+    #
+    # @param resp [Hash] the API error response
+    # @return [void]
     def display_delete_error(resp)
       @io.print "\n"
       display_response(resp)
     end
 
+    # Displays a hint that .gitignore entries are being excluded.
+    #
+    # @return [void]
     def display_gitignore_hint
       say "Not pushing .gitignore entries (--no-gitignore to disable)"
     end
 
+    # Prints the file upload progress indicator (without newline).
+    #
+    # @param path [String] local file path being uploaded
+    # @param remote_path [String] remote destination path
+    # @return [void]
+    def display_upload_progress(path, remote_path)
+      @io.print @pastel.bold("Uploading #{path} to #{remote_path} ... ")
+    end
+
+    # Prints a green "SUCCESS" after a file is uploaded.
+    #
+    # @return [void]
+    def display_upload_success
+      @io.print "#{@pastel.green.bold('SUCCESS')}\n"
+    end
+
+    # Prints a yellow "EXISTS" when the uploaded file already matches remotely.
+    #
+    # @return [void]
+    def display_upload_exists
+      @io.print "#{@pastel.yellow.bold('EXISTS')}\n"
+    end
+
+    # Displays a message that a directory path is being skipped.
+    #
+    # @param path [String] the directory path that was skipped
+    # @return [void]
+    def display_skip_directory(path)
+      say @pastel.bold("#{path} is a directory, skipping")
+    end
+
+    # Displays a message that a non-directory path is being skipped
+    # (during folder upload).
+    #
+    # @param path [String] the file path that was skipped
+    # @return [void]
+    def display_skip_file(path)
+      say @pastel.bold("#{path} is not a directory, skipping")
+    end
+
+    # Displays a message that all file uploads are complete.
+    #
+    # @return [void]
     def display_upload_complete
       say "All files uploaded."
     end
 
+    # Renders a TTY::Table to the output stream.
+    #
+    # @param table [TTY::Table] the table to display
+    # @return [void]
+    def display_list_table(table)
+      say table
+    end
+
+    # Prints the file pull progress indicator (without newline).
+    #
+    # @param path [String] remote file path being pulled
+    # @return [void]
+    def display_pull_progress(path)
+      @io.print @pastel.bold("Pulling #{path} ... ")
+    end
+
+    # Prints "NO NEW UPDATES" in yellow for files skipped during pull.
+    #
+    # @return [void]
+    def display_pull_no_updates
+      @io.print "#{@pastel.yellow.bold('NO NEW UPDATES')}\n"
+    end
+
+    # Prints a green "SUCCESS" after a file is pulled.
+    #
+    # @return [void]
+    def display_pull_success
+      @io.print "#{@pastel.green.bold('SUCCESS')}\n"
+    end
+
+    # Prints a red "FAIL" when a file pull fails.
+    #
+    # @return [void]
+    def display_pull_failure
+      @io.print "#{@pastel.red.bold('FAIL')}\n"
+    end
+
+    # Displays a summary of pull statistics.
+    #
+    # @param success_loaded [Integer] number of files successfully downloaded
+    # @param total_time [Float] total elapsed time in seconds
+    # @return [void]
+    def display_pull_stats(success_loaded, total_time)
+      say @pastel.green "\nSuccessfully fetched #{success_loaded} files in #{total_time.round(2)} seconds"
+    end
+
+    # Displays the pizza easter egg help screen and exits.
+    #
+    # @return [void]
     def display_pizza_help_and_exit
       say Services::Common::Pizza.new.make_order
       exit
     end
 
+    # Displays the help screen for the +list+ command and exits.
+    #
+    # @return [void]
     def display_list_help_and_exit
       display_banner
 
@@ -115,6 +278,9 @@ module NeocitiesRed
       exit
     end
 
+    # Displays the help screen for the +delete+ command and exits.
+    #
+    # @return [void]
     def display_delete_help_and_exit
       display_banner
 
@@ -132,6 +298,9 @@ module NeocitiesRed
       exit
     end
 
+    # Displays the help screen for the +upload+ command and exits.
+    #
+    # @return [void]
     def display_upload_help_and_exit
       display_banner
 
@@ -157,6 +326,9 @@ module NeocitiesRed
       exit
     end
 
+    # Displays the help screen for the +pull+ command and exits.
+    #
+    # @return [void]
     def display_pull_help_and_exit
       display_banner
 
@@ -166,6 +338,9 @@ module NeocitiesRed
       exit
     end
 
+    # Displays the help screen for the +push+ command and exits.
+    #
+    # @return [void]
     def display_push_help_and_exit
       display_banner
 
@@ -191,6 +366,9 @@ module NeocitiesRed
       exit
     end
 
+    # Displays the help screen for the +diff+ command and exits.
+    #
+    # @return [void]
     def display_diff_help_and_exit
       display_banner
 
@@ -210,6 +388,9 @@ module NeocitiesRed
       exit
     end
 
+    # Displays the help screen for the +info+ command and exits.
+    #
+    # @return [void]
     def display_info_help_and_exit
       display_banner
 
@@ -223,6 +404,9 @@ module NeocitiesRed
       exit
     end
 
+    # Displays the help screen for the +logout+ command and exits.
+    #
+    # @return [void]
     def display_logout_help_and_exit
       display_banner
 
@@ -236,6 +420,9 @@ module NeocitiesRed
       exit
     end
 
+    # Displays the help screen for the +purge+ command and exits.
+    #
+    # @return [void]
     def display_purge_help_and_exit
       display_banner
 
@@ -244,11 +431,16 @@ module NeocitiesRed
 
         #{@pastel.dim 'Examples:'}
 
-        #{@pastel.green '$ neocities-red purge -y'}
+        #{@pastel.green '$ neocities-red purge -y'}                Delete all files from your site
+
+        #{@pastel.green '$ neocities-red purge -y --dry-run'}      Show what would be deleted
       HERE
       exit
     end
 
+    # Renders the ASCII art banner with a random Penelope cat face.
+    #
+    # @return [void]
     def display_banner
       say <<~HERE
 
@@ -259,6 +451,9 @@ module NeocitiesRed
       HERE
     end
 
+    # Displays the main help screen listing all available subcommands and exits.
+    #
+    # @return [void]
     def display_help_and_exit
       display_banner
       say <<~HERE

data/lib/neocities_red/client.rb

@@ -11,9 +11,7 @@ require "json"
 require "pathname"
 require "uri"
 require "digest"
-require "pastel"
 require "date"
-require "whirly"
 
 require "faraday"
 require "faraday/retry"
@@ -21,13 +19,35 @@ require "faraday/multipart"
 require "faraday/follow_redirects"
 
 module NeocitiesRed
+  # HTTP client for the Neocities API.
+  #
+  # Wraps all API interactions — listing, uploading, deleting, and querying
+  # site information. Supports both API-key (Bearer) and basic-auth
+  # (sitename/password) authentication.
+  #
+  # Retries transient failures (429, 5xx) automatically via Faraday::Retry.
+  #
+  # @example API key authentication
+  #   client = NeocitiesRed::Client.new(api_key: "your-api-key")
+  #   client.list
+  #
+  # @example Basic auth authentication
+  #   client = NeocitiesRed::Client.new(sitename: "my-site", password: "secret")
+  #   client.list
   class Client
+    # @return [String] Base URL for the Neocities REST API.
     API_URI = "https://neocities.org/api/"
 
+    # Creates a new API client.
+    #
+    # @param opts [Hash] authentication options
+    # @option opts [String] :api_key Bearer token for API-key authentication
+    # @option opts [String] :sitename site name for basic-auth (requires +:password+)
+    # @option opts [String] :password site password for basic-auth (requires +:sitename+)
+    # @raise [ArgumentError] if neither +:api_key+ nor (+:sitename+ and +:password+) are provided
     def initialize(opts = {})
       @uri = URI.parse API_URI
       @opts = opts
-      @pastel = Pastel.new eachline: "\n"
       @conn = Faraday.new(@uri) do |conn|
         conn.options.timeout = 30
         conn.options.open_timeout = 10
@@ -59,87 +79,45 @@ module NeocitiesRed
       end
     end
 
+    # Lists files on the remote Neocities site.
+    #
+    # @param path [String, nil] directory path to list (nil for root)
+    # @return [Hash] parsed API response containing +:files+ array
     def list(path = nil)
       get "list", path: path
     end
 
-    # TODO: refactor
-    def pull(sitename, last_pull_time = nil, last_pull_loc = nil, quiet: true)
-      site_info = info(sitename)
-
-      raise ArgumentError, site_info[:message] if site_info[:result] == "error"
-
-      info_data = site_info[:info]
-
-      domain =
-        if info_data[:domain].to_s.empty?
-          "https://#{sitename}.neocities.org/"
-        else
-          "https://#{info_data[:domain]}/"
-        end
-
-      # start stats
-      success_loaded = 0
-      start_time = Time.now
-      curr_dir = Dir.pwd
-
-      # get list of files
-      resp = list
-
-      raise ArgumentError, resp[:message] if resp[:result] == "error"
-
-      # fetch each file
-      uri_parser = URI::Parser.new
-      resp[:files].each do |file|
-        if file[:is_directory]
-          FileUtils.mkdir_p file[:path].to_s
-        else
-          print @pastel.bold("Pulling #{file[:path]} ... ") unless quiet
-
-          if last_pull_time &&
-             last_pull_loc &&
-             Time.parse(file[:updated_at]) <= Time.parse(last_pull_time) &&
-             last_pull_loc == curr_dir &&
-             File.exist?(file[:path]) # case when user deletes file
-
-            # case when file hasn't been updated since last
-            print "#{@pastel.yellow.bold 'NO NEW UPDATES'}\n" unless quiet
-
-            next
-          end
-
-          pathtotry = uri_parser.escape(domain + file[:path])
-          fileconts = @conn.get pathtotry
-
-          if fileconts.status == 200
-            print "#{@pastel.green.bold 'SUCCESS'}\n" unless quiet
-            success_loaded += 1
-
-            File.write(file[:path].to_s, fileconts.body)
-          elsif !quiet
-            print "#{@pastel.red.bold 'FAIL'}\n"
-          end
-        end
-      end
-
-      # calculate time command took
-      total_time = Time.now - start_time
-
-      # stop the spinner, if there is one
-      Whirly.stop if quiet
-
-      # display stats
-      puts @pastel.green "\nSuccessfully fetched #{success_loaded} files in #{total_time.round(2)} seconds"
-    end
-
+    # Retrieves the API key for the currently authenticated user.
+    #
+    # Only meaningful when authenticated via basic-auth (sitename/password).
+    #
+    # @return [Hash] parsed API response containing +:api_key+
     def key
       get "key"
     end
 
+    # Checks whether the remote file matches the given SHA1 hash.
+    #
+    # Used by {#upload} to skip uploading files that haven't changed.
+    #
+    # @param remote_path [String] remote file path to check
+    # @param sha1_hash [String] hex-encoded SHA1 hash of the local file
+    # @return [Hash] parsed API response with +:files+ mapping paths to booleans
     def upload_hash(remote_path, sha1_hash)
       post "upload_hash", remote_path => sha1_hash
     end
 
+    # Uploads a single file to the Neocities site.
+    #
+    # Computes the SHA1 hash of the local file and compares it with the
+    # remote version. If the file already exists remotely with the same
+    # hash, the upload is skipped and an "exists" response is returned.
+    #
+    # @param path [String, Pathname] local file path to upload
+    # @param remote_path [String, nil] remote destination path; defaults to the basename of +path+
+    # @param dry_run [Boolean] when true, simulates the upload without sending data
+    # @return [Hash] API response with +:result+ key ("success", "error", or "file_exists")
+    # @raise [ArgumentError] if the local file does not exist
     def upload(path, remote_path = nil, dry_run: false)
       path = Pathname path
       raise ArgumentError, "#{path} does not exist." unless path.exist?
@@ -147,11 +125,7 @@ module NeocitiesRed
       rpath = remote_path || path.basename
       res = upload_hash(rpath.to_s, Digest::SHA1.file(path.to_s).hexdigest)
 
-      file_exists_remotely = if res[:files]
-                               res[:files][rpath.to_s.to_sym] == true || res[:files][rpath.to_s] == true
-                             else
-                               false
-                             end
+      file_exists_remotely = res[:files] ? res[:files][rpath.to_s.to_sym] == true : false
 
       if file_exists_remotely
         {
@@ -168,20 +142,40 @@ module NeocitiesRed
       end
     end
 
+    # Deletes one or more remote files, with optional dry-run support.
+    #
+    # @param paths [Array<String>] remote file paths to delete
+    # @param dry_run [Boolean] when true, simulates the deletion
+    # @return [Hash] API response with +:result+ key
     def delete_wrapper_with_dry_run(paths, dry_run: false)
       return { result: "success" } if dry_run
 
       delete(paths)
     end
 
+    # Deletes one or more files from the remote Neocities site.
+    #
+    # @param paths [Array<String>] remote file paths to delete
+    # @return [Hash] parsed API response
     def delete(*paths)
       post "delete", "filenames" => paths
     end
 
+    # Retrieves information and statistics for a Neocities site.
+    #
+    # @param sitename [String] the site name to query
+    # @return [Hash] parsed API response containing +:info+ hash with
+    #   site metadata (domain, created_at, last_updated, bandwidth, etc.)
+    # @raise [NeocitiesRed::APIError] if the API returns an error
     def info(sitename)
       get "info", sitename: sitename
     end
 
+    # Performs an HTTP GET request to the Neocities API.
+    #
+    # @param path [String] API endpoint path (e.g. "list", "info")
+    # @param params [Hash] query parameters
+    # @return [Hash] parsed JSON response with symbolized keys
     def get(path, params = {})
       uri = @uri + path
       uri.query = URI.encode_www_form params
@@ -190,6 +184,19 @@ module NeocitiesRed
       JSON.parse resp.body, symbolize_names: true
     end
 
+    # Downloads a file from a URL.
+    #
+    # @param url [String] full URL to download
+    # @return [Faraday::Response] raw Faraday response object
+    def download(url)
+      @conn.get(url)
+    end
+
+    # Performs an HTTP POST request to the Neocities API.
+    #
+    # @param path [String] API endpoint path (e.g. "upload", "delete")
+    # @param args [Hash] request body parameters
+    # @return [Hash] parsed JSON response with symbolized keys
     def post(path, args = {})
       uri = @uri + path
       resp = @conn.post(uri, args)

data/lib/neocities_red/errors.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module NeocitiesRed
+  # Base error class for all NeocitiesRed exceptions.
+  #
+  # @abstract Subclass this for domain-specific errors.
+  class Error < StandardError; end
+
+  # Raised when the Neocities API returns a non-success response.
+  #
+  # Wraps error messages from the remote API so callers can inspect
+  # the +:message+ and +:error_type+ fields from the response.
+  class APIError < Error; end
+
+  # Raised when a referenced file does not exist on the local filesystem.
+  #
+  # Typically raised by upload services when the source file
+  # cannot be found at the given path.
+  class FileNotFoundError < Error; end
+end

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

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require "pathname"
+
+module NeocitiesRed
+  module Services
+    module Common
+      # Builds normalized exclusion lists from user-provided paths.
+      #
+      # Given a list of file or directory paths, expands them into all
+      # contained files and normalizes them relative to a base path.
+      # This is used by {NeocitiesRed::Services::Site::Pusher} to apply
+      # the +--exclude+ option.
+      #
+      # @example
+      #   excluded = Exclusions.build(["node_modules", "secret.txt"], base_path: ".")
+      #   # => ["node_modules/...", "secret.txt"]
+      #
+      # @see NeocitiesRed::Services::Site::Pusher#push Uses exclusions during push
+      module Exclusions
+        module_function
+
+        # Builds a normalized exclusion list from the given entries.
+        #
+        # For each entry:
+        # - If it is a file, includes it directly
+        # - If it is a directory, recursively includes all contained files
+        # - Non-existent entries are silently skipped
+        #
+        # @param excluded_entries [Array<String>] file or directory paths to exclude
+        # @param base_path [String, nil] base directory for path normalization;
+        #   when provided, paths are made relative to this base
+        # @return [Array<String>] flattened, deduplicated list of normalized paths
+        def build(excluded_entries, base_path: nil)
+          base = base_path && Pathname.new(base_path).expand_path
+
+          excluded_entries.flat_map do |entry|
+            target = base ? Pathname.new(entry).expand_path : Pathname.new(entry).cleanpath
+            next [] unless target.exist?
+
+            paths =
+              if ::File.file?(target)
+                [target.to_s]
+              elsif ::File.directory?(target)
+                Dir.glob(::File.join(target, "**", "*"), ::File::FNM_DOTMATCH)
+              else
+                []
+              end
+
+            paths.push(target.to_s) if ::File.directory?(target)
+            paths.map { |path| normalize(path, base) }.uniq
+          end
+        end
+
+        # Normalizes a path relative to a base directory.
+        #
+        # @param path [String] absolute or relative path
+        # @param base [String, nil] base directory; when nil, returns the path as-is
+        # @return [String] the path relative to +base+, or the original path
+        def normalize(path, base)
+          return path unless base
+
+          Pathname.new(path).expand_path.relative_path_from(base).to_s
+        end
+        private_class_method :normalize
+      end
+    end
+  end
+end