wikiwiki 0.5.0 → 0.7.0

data/lib/wikiwiki/cli/commands/auth.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Wikiwiki
+  class CLI
+    module Commands
+      # Authenticate and output JWT token
+      class Auth < Base
+        desc "Authenticate and output JWT token"
+
+        option :json, aliases: ["-j"], type: :boolean, default: false, desc: "Output as JSON"
+
+        # Execute the auth command
+        #
+        # @param options [Hash] command options including wiki_id, auth credentials, json, verbose, out, err
+        # @return [void]
+        def call(out: $stdout, err: $stderr, **options)
+          wiki = create_wiki(out:, err:, **options)
+          token = wiki.token
+
+          if options[:json]
+            out.puts Formatter::JSON.new.format({"token" => token})
+          else
+            out.puts token
+            say("Authentication successful", out:, **options)
+          end
+        end
+      end
+
+      register "auth", Auth
+    end
+  end
+end

data/lib/wikiwiki/cli/commands/base.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Wikiwiki
+  class CLI
+    # CLI command implementations
+    #
+    # This module serves as a namespace for all CLI commands.
+    # Commands are organized into submodules (Page, Attachment) for better organization.
+    module Commands
+      # Base command class with global options
+      class Base < Dry::CLI::Command
+        option :wiki_id, aliases: ["-w"], desc: "Wiki ID (or set WIKIWIKI_WIKI_ID)"
+        option :token, desc: "JWT token for authentication (or set WIKIWIKI_TOKEN)"
+        option :api_key_id, desc: "API Key ID for authentication (or set WIKIWIKI_API_KEY_ID)"
+        option :secret, desc: "API Key Secret for authentication (or set WIKIWIKI_SECRET)"
+        option :password, desc: "Password for authentication (or set WIKIWIKI_PASSWORD)"
+        option :verbose, aliases: ["-v"], type: :boolean, default: false, desc: "Verbose output"
+        option :debug, type: :boolean, default: false, desc: "Debug mode"
+
+        private def create_wiki(wiki_id: nil, token: nil, api_key_id: nil, secret: nil, password: nil, debug: false, out: $stdout, err: $stderr, **)
+          # Fallback to environment variables if options are not provided
+          wiki_id ||= ENV.fetch("WIKIWIKI_WIKI_ID", nil)
+          token ||= ENV.fetch("WIKIWIKI_TOKEN", nil)
+          api_key_id ||= ENV.fetch("WIKIWIKI_API_KEY_ID", nil)
+          secret ||= ENV.fetch("WIKIWIKI_SECRET", nil)
+          password ||= ENV.fetch("WIKIWIKI_PASSWORD", nil)
+
+          raise ArgumentError, "Wiki ID must be provided via --wiki-id or WIKIWIKI_WIKI_ID" unless wiki_id
+
+          auth = if token
+                   Wikiwiki::Auth.token(token:)
+                 elsif api_key_id && secret
+                   Wikiwiki::Auth.api_key(api_key_id:, secret:)
+                 elsif password
+                   Wikiwiki::Auth.password(password:)
+                 else
+                   raise ArgumentError, "Either --token, API key (--api-key-id and --secret), or --password must be provided (via options or environment variables)"
+                 end
+
+          logger = create_logger(debug:, out:, err:)
+          Wiki.new(wiki_id:, auth:, logger:)
+        end
+
+        private def create_logger(debug:, out: $stdout, err: $stderr)
+          if debug
+            Logger.new(err, level: Logger::DEBUG)
+          elsif out.tty?
+            Logger.new(err, level: Logger::WARN)
+          else
+            Logger.new(IO::NULL)
+          end
+        end
+
+        private def verbose?(verbose:, json: false, **) = verbose && !json
+
+        private def say(message, verbose:, out: $stdout, **)
+          return unless verbose?(verbose:)
+
+          out.puts message
+        end
+      end
+    end
+  end
+end

data/lib/wikiwiki/cli/commands/page/delete.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Wikiwiki
+  class CLI
+    module Commands
+      module Page
+        # Delete a page
+        class Delete < Base
+          desc "Delete a page"
+
+          argument :page_name, required: true, desc: "Page name"
+
+          # Execute the delete command
+          #
+          # @param page_name [String] name of the page to delete
+          # @param out [IO] output stream
+          # @param err [IO] error stream
+          # @return [void]
+          def call(page_name:, out: $stdout, err: $stderr, **)
+            wiki = create_wiki(out:, err:, **)
+
+            wiki.delete_page(page_name:)
+
+            say("Page '#{page_name}' deleted successfully", out:, **)
+          end
+        end
+      end
+
+      register "page delete", Page::Delete
+    end
+  end
+end

data/lib/wikiwiki/cli/commands/page/get.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Wikiwiki
+  class CLI
+    module Commands
+      module Page
+        # Get page content
+        class Get < Base
+          desc "Get page content"
+
+          argument :page_name, required: true, desc: "Page name"
+          argument :output_file, required: false, desc: "Output file (stdout if omitted)"
+          option :force, aliases: ["-f"], type: :boolean, default: false, desc: "Overwrite existing file"
+
+          # Execute the get command
+          #
+          # @param page_name [String] name of the page to get
+          # @param output_file [String, nil] optional output file path
+          # @param force [Boolean] whether to overwrite existing file
+          # @param out [IO] output stream
+          # @param err [IO] error stream
+          # @return [void]
+          def call(page_name:, output_file: nil, force: false, out: $stdout, err: $stderr, **)
+            wiki = create_wiki(out:, err:, **)
+
+            # Check if output file exists when not forcing
+            if output_file && File.exist?(output_file) && !force
+              raise ArgumentError, "File '#{output_file}' already exists. Use --force to overwrite."
+            end
+
+            page = wiki.page(page_name:)
+
+            if output_file
+              File.write(output_file, page.source)
+              say("Page '#{page_name}' (#{page.source.bytesize} bytes) saved to #{output_file}", out:, **)
+            else
+              out.puts page.source
+            end
+          end
+        end
+      end
+
+      register "page get", Page::Get
+    end
+  end
+end

data/lib/wikiwiki/cli/commands/page/list.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Wikiwiki
+  class CLI
+    # CLI command implementations
+    module Commands
+      # Page-related commands
+      module Page
+        # List all pages in the wiki
+        class List < Base
+          desc "List all pages"
+
+          option :json, aliases: ["-j"], type: :boolean, default: false, desc: "Output as JSON"
+
+          # Execute the list command
+          #
+          # @param options [Hash] command options including wiki_id, auth, json, verbose, out, err
+          # @return [void]
+          def call(out: $stdout, err: $stderr, **options)
+            wiki = create_wiki(out:, err:, **options)
+            page_names = wiki.page_names
+
+            if options[:json]
+              out.puts Formatter::JSON.new.format(page_names)
+            else
+              page_names.each {|name| out.puts name }
+              say("#{page_names.size} pages found", out:, **options)
+            end
+          end
+        end
+      end
+
+      register "page list", Page::List
+    end
+  end
+end

data/lib/wikiwiki/cli/commands/page/put.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Wikiwiki
+  class CLI
+    module Commands
+      module Page
+        # Upload/update page content (creates if not exists)
+        class Put < Base
+          desc "Upload/update page content (creates if not exists)"
+
+          argument :page_name, required: true, desc: "Page name"
+          argument :input_file, required: false, desc: "Input file (stdin if omitted)"
+
+          # Execute the put command
+          #
+          # @param page_name [String] name of the page to update
+          # @param input_file [String, nil] optional input file path (uses stdin if nil)
+          # @param out [IO] output stream
+          # @param err [IO] error stream
+          # @return [void]
+          # @raise [ArgumentError] if source content is empty
+          # @note To delete a page, use `wikiwiki page delete` instead
+          def call(page_name:, input_file: nil, out: $stdout, err: $stderr, **)
+            wiki = create_wiki(out:, err:, **)
+
+            source = if input_file
+                       File.read(input_file)
+                     else
+                       $stdin.read
+                     end
+
+            raise ArgumentError, "Page source must not be empty. Use 'wikiwiki page delete' to delete a page." if source.empty?
+
+            wiki.update_page(page_name:, source:)
+
+            say("Page '#{page_name}' updated successfully", out:, **)
+          end
+        end
+      end
+
+      register "page put", Page::Put
+    end
+  end
+end

data/lib/wikiwiki/cli/commands/page/show.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Wikiwiki
+  class CLI
+    module Commands
+      module Page
+        # Show page metadata
+        class Show < Base
+          desc "Show page metadata"
+
+          argument :page_name, required: true, desc: "Page name"
+          option :json, aliases: ["-j"], type: :boolean, default: false, desc: "Output as JSON"
+
+          # Execute the show command
+          #
+          # @param page_name [String] name of the page to show
+          # @param options [Hash] command options including wiki_id, auth, json, verbose, out, err
+          # @return [void]
+          def call(page_name:, out: $stdout, err: $stderr, **options)
+            wiki = create_wiki(out:, err:, **options)
+            page = wiki.page(page_name:)
+
+            metadata = {
+              "name" => page.name,
+              "timestamp" => page.timestamp.iso8601,
+              "source_size" => page.source.bytesize
+            }
+
+            if options[:json]
+              out.puts Formatter::JSON.new.format(metadata)
+            else
+              out.puts "Name: #{metadata["name"]}"
+              out.puts "Timestamp: #{metadata["timestamp"]}"
+              out.puts "Source size: #{metadata["source_size"]} bytes"
+              say("Page metadata retrieved", out:, **options)
+            end
+          end
+        end
+      end
+
+      register "page show", Page::Show
+    end
+  end
+end

data/lib/wikiwiki/cli/formatter/json.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Wikiwiki
+  class CLI
+    module Formatter
+      # JSON output formatter for CLI commands
+      class JSON
+        # Format data as pretty-printed JSON
+        #
+        # @param data [Object] data to format (Hash, Array, etc.)
+        # @return [String] formatted JSON string
+        def format(data) = ::JSON.pretty_generate(data)
+      end
+    end
+  end
+end

data/lib/wikiwiki/cli.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require "dry/cli"
+require "logger"
+
+module Wikiwiki
+  # Command-line interface for Wikiwiki
+  #
+  # Provides commands for managing wiki pages and attachments through the terminal.
+  # Supports authentication via API key or password, with configurable logging and output modes.
+  class CLI
+    # Initialize the CLI with output streams
+    #
+    # @param out [IO] standard output (defaults to $stdout)
+    # @param err [IO] error output (defaults to $stderr)
+    def initialize(out: $stdout, err: $stderr)
+      @out = out
+      @err = err
+      @dry_cli = Dry::CLI.new(Commands)
+    end
+
+    # Run the CLI with given arguments
+    #
+    # @param argv [Array<String>] command-line arguments
+    # @return [Integer] exit code (0 for success, 1 for error)
+    def run(argv)
+      @debug = argv.include?("--debug")
+      @dry_cli.call(arguments: argv, out: @out, err: @err)
+      0
+    rescue => e
+      handle_error(e)
+      1
+    end
+
+    attr_reader :out
+    attr_reader :err
+
+    # Handle and display errors
+    #
+    # @param error [Exception] the error to handle
+    # @return [void]
+    private def handle_error(error) = err.puts(@debug ? error.full_message : error.message)
+
+    # Command registry
+    module Commands
+      extend Dry::CLI::Registry
+    end
+  end
+end

data/lib/wikiwiki/rate_limiter.rb

@@ -84,9 +84,7 @@ module Wikiwiki
     #
     # @return [void]
     # @raise [RateLimitError] if rate limit is exceeded (with raise strategy)
-    def acquire!
-      @strategy.acquire!(self)
-    end
+    def acquire! = @strategy.acquire!(self)
 
     # Get time in seconds until next request can be made
     #
@@ -100,23 +98,17 @@ module Wikiwiki
     # Check if a request can be made without exceeding any limits
     #
     # @return [Boolean] true if request is allowed
-    def can_request?
-      @windows.all?(&:can_request?)
-    end
+    def can_request? = @windows.all?(&:can_request?)
 
     # Record a new request across all window limiters
     #
     # @return [void]
-    def record!
-      @windows.each(&:record!)
-    end
+    def record! = @windows.each(&:record!)
 
     # Get maximum wait time across all window limiters
     #
     # @return [Float, nil] seconds to wait
-    def wait_time
-      @windows.map(&:wait_time).max
-    end
+    def wait_time = @windows.map(&:wait_time).max
 
     attr_reader :mutex
   end

data/lib/wikiwiki/sliding_window.rb

@@ -24,9 +24,7 @@ module Wikiwiki
     # Record a new request timestamp
     #
     # @return [void]
-    def record!
-      @requests << Time.now
-    end
+    def record! = (@requests << Time.now)
 
     # Get time in seconds until next request can be made
     #

data/lib/wikiwiki/version.rb

@@ -2,6 +2,6 @@
 
 module Wikiwiki
   # The gem version
-  VERSION = "0.5.0"
+  VERSION = "0.7.0"
   public_constant :VERSION
 end

data/lib/wikiwiki/wiki.rb

@@ -17,8 +17,6 @@ module Wikiwiki
   class Wiki
     attr_reader :logger
 
-    private attr_reader :api, :wiki_id
-
     # Initializes a new Wiki instance
     #
     # @param wiki_id [String] the wiki ID
@@ -34,6 +32,13 @@ module Wikiwiki
       @api = API.new(wiki_id:, auth:, logger:, rate_limiter:)
     end
 
+    # Returns the authentication token
+    #
+    # @return [String] JWT authentication token
+    def token = api.token
+
+    private attr_reader :api, :wiki_id
+
     # Returns the wiki URL
     #
     # @return [URI::HTTPS] the frozen wiki URL
@@ -65,14 +70,28 @@ module Wikiwiki
     # Updates a page with new content
     #
     # @param page_name [String] the name of the page to update
-    # @param source [String] the new page source content
+    # @param source [String] the new page source content (must not be empty)
     # @return [void]
+    # @raise [ArgumentError] if source is empty
     # @raise [Wikiwiki::Error] if the update fails
+    # @note To delete a page, use {#delete_page} instead
     def update_page(page_name:, source:)
+      raise ArgumentError, "Page source must not be empty. Use delete_page to delete a page." if source.empty?
+
       encoded_page_name = ERB::Util.url_encode(page_name)
       api.put_page(encoded_page_name:, source:)
     end
 
+    # Deletes a page
+    #
+    # @param page_name [String] the name of the page to delete
+    # @return [void]
+    # @raise [Wikiwiki::Error] if the deletion fails
+    def delete_page(page_name:)
+      encoded_page_name = ERB::Util.url_encode(page_name)
+      api.put_page(encoded_page_name:, source: "")
+    end
+
     # Retrieves attachment file names on a page
     #
     # @param page_name [String] the name of the page

data/lib/wikiwiki.rb

@@ -32,12 +32,16 @@ module Wikiwiki
   # Raised when HTTP status is 404
   class ResourceNotFoundError < APIError; end
 
+  # Conflict error
+  # Raised when HTTP status is 409
+  class ConflictError < APIError; end
+
   # Server error
   # Raised when HTTP status is 5xx
   class ServerError < APIError; end
 
   loader = Zeitwerk::Loader.for_gem
-  loader.inflector.inflect("api" => "API")
+  loader.inflector.inflect("api" => "API", "cli" => "CLI", "json" => "JSON")
   loader.setup
   loader.eager_load
 end

data/sig/dry/cli.rbs

@@ -0,0 +1,9 @@
+module Dry
+  module CLI
+    class Command
+    end
+
+    module Registry
+    end
+  end
+end

data/sig/wikiwiki/api.rbs

@@ -1,8 +1,9 @@
 module Wikiwiki
   class API
     attr_reader logger: Logger
+    attr_reader token: String
 
-    def initialize: (wiki_id: String, auth: Auth::Password | Auth::ApiKey, logger: Logger, ?rate_limiter: RateLimiter) -> void
+    def initialize: (wiki_id: String, auth: Auth::Password | Auth::ApiKey | Auth::Token, logger: Logger, ?rate_limiter: RateLimiter) -> void
 
     def get_pages: () -> Hash[String, Array[Hash[String, String]]]
 
@@ -20,7 +21,9 @@ module Wikiwiki
 
     private
 
-    def authenticate: (Auth::Password | Auth::ApiKey auth) -> String
+    def authenticate: (Auth::Password | Auth::ApiKey | Auth::Token auth) -> String
+
+    def validate_token_expiry: (String token) -> void
 
     def parse_json_response: (Net::HTTPResponse response) -> Hash[String, untyped]
 
@@ -31,6 +34,5 @@ module Wikiwiki
     def log_response: (Net::HTTPResponse response) -> void
 
     attr_reader wiki_id: String
-    attr_reader token: String
   end
 end

data/sig/wikiwiki/auth/token.rbs

@@ -0,0 +1,9 @@
+module Wikiwiki
+  module Auth
+    class Token
+      attr_reader token: String
+
+      def initialize: (token: String) -> void
+    end
+  end
+end

data/sig/wikiwiki/auth.rbs

@@ -3,5 +3,7 @@ module Wikiwiki
     def self.password: (String password) -> Auth::Password
 
     def self.api_key: (String api_key_id, String secret) -> Auth::ApiKey
+
+    def self.token: (String token) -> Auth::Token
   end
 end

data/sig/wikiwiki/cli/commands/attachment.rbs

@@ -0,0 +1,87 @@
+module Wikiwiki
+  class CLI
+    module Commands
+      module Attachment
+        class List < Base
+          def call: (
+            page_name: String,
+            ?out: IO,
+            ?err: IO,
+            ?wiki_id: String?,
+            ?api_key_id: String?,
+            ?secret: String?,
+            ?password: String?,
+            ?json: bool,
+            ?verbose: bool,
+            ?debug: bool
+          ) -> void
+        end
+
+        class Show < Base
+          def call: (
+            page_name: String,
+            file_name: String,
+            ?out: IO,
+            ?err: IO,
+            ?wiki_id: String?,
+            ?api_key_id: String?,
+            ?secret: String?,
+            ?password: String?,
+            ?json: bool,
+            ?verbose: bool,
+            ?debug: bool
+          ) -> void
+        end
+
+        class Get < Base
+          def call: (
+            page_name: String,
+            file_name: String,
+            ?directory: String?,
+            ?force: bool,
+            ?out: IO,
+            ?err: IO,
+            ?wiki_id: String?,
+            ?api_key_id: String?,
+            ?secret: String?,
+            ?password: String?,
+            ?verbose: bool,
+            ?debug: bool
+          ) -> void
+        end
+
+        class Put < Base
+          def call: (
+            page_name: String,
+            file_path: String,
+            ?name: String?,
+            ?force: bool,
+            ?out: IO,
+            ?err: IO,
+            ?wiki_id: String?,
+            ?api_key_id: String?,
+            ?secret: String?,
+            ?password: String?,
+            ?verbose: bool,
+            ?debug: bool
+          ) -> void
+        end
+
+        class Delete < Base
+          def call: (
+            page_name: String,
+            file_name: String,
+            ?out: IO,
+            ?err: IO,
+            ?wiki_id: String?,
+            ?api_key_id: String?,
+            ?secret: String?,
+            ?password: String?,
+            ?verbose: bool,
+            ?debug: bool
+          ) -> void
+        end
+      end
+    end
+  end
+end

data/sig/wikiwiki/cli/commands/auth.rbs

@@ -0,0 +1,9 @@
+module Wikiwiki
+  class CLI
+    module Commands
+      class Auth < Base
+        def call: (?out: IO, ?err: IO, **untyped options) -> void
+      end
+    end
+  end
+end

data/sig/wikiwiki/cli/commands/base.rbs

@@ -0,0 +1,27 @@
+module Wikiwiki
+  class CLI
+    module Commands
+      class Base < Dry::CLI::Command
+        private
+
+        def create_wiki: (
+          ?wiki_id: String?,
+          ?token: String?,
+          ?api_key_id: String?,
+          ?secret: String?,
+          ?password: String?,
+          ?debug: bool,
+          ?out: IO,
+          ?err: IO,
+          **untyped
+        ) -> Wiki
+
+        def create_logger: (debug: bool, ?out: IO, ?err: IO) -> Logger
+
+        def verbose?: (verbose: bool, ?json: bool, **untyped) -> bool
+
+        def say: (String message, verbose: bool, ?out: IO, **untyped) -> void
+      end
+    end
+  end
+end