rakit 0.1.5 → 0.1.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4cf9325de6845aa1235b153b42503a92c8604f447a6e6e402c891412a1157905
-  data.tar.gz: ce566e52e4889d22eb42dff316fa989b414d34f4d0b14d9595b509e5913c702f
+  metadata.gz: 8f146d5f635716871e7960854ae13c5f64dcf353d50b7b57a808f81258580972
+  data.tar.gz: 80f4539d5cb9e02c506789a3ebb4862a280eb750aea7b88449dbcf54222cf6f4
 SHA512:
-  metadata.gz: c8da52aef46f781cdf227fc0494047bdbf64869ce7dea91797ca8a79f61d41fd3a490fdb332b10413b0b2be292c2f00e0b8c2703b944eeb57779a3a517327d94
-  data.tar.gz: c9c856269882482e5e9f838e5f1f7ca89ca2ea951296cc0b24f46b642b641277bab3f833e38f670f00ad1b878cb14a678986c15b80db6a3029c0e6e1033a309d
+  metadata.gz: fe9c41e4505e458900c66bfa5fed2041fed850f568fdcb44cf0843468278a5320317d84d6b97c1b76bc303f683f79ca1b9994a69224574599c8ec5c216b00925
+  data.tar.gz: fc4fd21d2dbefede571552edc32d3f8e62e323ed008e09d7831dd282ad216aca8ba7221af3515f56b2d76897898e40f295d075dbbfb058bb2749d32aeba54507

data/exe/rakit

@@ -1,7 +1,8 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
-# CLI for rakit gem. Subcommands: file (list|copy), word-count (--json-keys), static-web-server (start|stop|running|publish).
+# CLI for rakit gem. Subcommands: markdown (pdf|amalgamate), file (list|copy), word-count (--json-keys), static-web-server (start|stop|running|publish).
+# CLI for rakit gem. Subcommands: file (list|copy), word-count (--json-keys), static-web-server (start|stop|running|publish), word-cloud (status|install|generate).
 
 require "rakit"
 
@@ -11,20 +12,25 @@ Rakit::StaticWebServer.root = ENV["RAKIT_WWW_ROOT"] if ENV["RAKIT_WWW_ROOT"]
 def usage_stderr(msg = nil)
   $stderr.puts msg if msg
   $stderr.puts "Usage: rakit <subcommand> [options] [args]"
+  $stderr.puts "  markdown pdf <input.md> [output.pdf]"
+  $stderr.puts "  markdown amalgamate <source_dir> <target.md> [--create-directories]"
   $stderr.puts "  file list <directory> [--recursive] [--include-hidden] [--format console|json|proto-json]"
   $stderr.puts "  file copy <source> <destination> [--overwrite] [--create-directories] [--format ...]"
   $stderr.puts "  word-count <file>|--stdin --json-keys [--format console|json|proto-json] [options]"
   $stderr.puts "  static-web-server <start|stop|running|publish> [options] [args]"
-  $stderr.puts "  start [--port PORT]   Start server (idempotent)"
-  $stderr.puts "  stop                  Stop server"
-  $stderr.puts "  running              Exit 0 if running, non-zero otherwise"
-  $stderr.puts "  publish <site_name> <source_dir>  Publish static site"
+  $stderr.puts "  word-cloud <status|install|generate> [options] [args]"
 end
 
 def main(argv = ARGV)
   return usage_stderr("Expected subcommand.") if argv.empty?
 
   sub = argv[0]
+  if sub == "markdown"
+    argv.shift
+    require "rakit/cli/markdown"
+    return Rakit::CLI::Markdown.run(argv)
+  end
+
   if sub == "file"
     argv.shift
     require "rakit/cli/file"
@@ -37,6 +43,12 @@ def main(argv = ARGV)
     return Rakit::CLI::WordCount.run(argv)
   end
 
+  if sub == "word-cloud"
+    argv.shift
+    require "rakit/cli/word_cloud"
+    return Rakit::CLI::WordCloud.run(argv)
+  end
+
   if sub != "static-web-server"
     usage_stderr("Unknown subcommand: #{sub}")
     return 1

data/lib/generated/data_pb.rb

@@ -2,7 +2,8 @@
 # Generated by the protocol buffer compiler.  DO NOT EDIT!
 # source: data.proto
 
-require "google/protobuf"
+require 'google/protobuf'
+
 
 descriptor_data = "\n\ndata.proto\x12\nrakit.data\"h\n\x05Index\x12/\n\x07\x65ntries\x18\x01 \x03(\x0b\x32\x1e.rakit.data.Index.EntriesEntry\x1a.\n\x0c\x45ntriesEntry\x12\x0b\n\x03key\x18\x01 \x01(\t\x12\r\n\x05value\x18\x02 \x01(\t:\x02\x38\x01*^\n\x0c\x45xportFormat\x12\x19\n\x15PROTOBUF_BINARY_FILES\x10\x00\x12\x17\n\x13PROTOBUF_JSON_FILES\x10\x01\x12\x1a\n\x16PROTOBUF_BINARY_ZIPPED\x10\x02\x42\x0e\xea\x02\x0bRakit::Datab\x06proto3"
 

data/lib/generated/word_cloud_pb.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# source: word_cloud.proto
+
+require 'google/protobuf'
+
+
+descriptor_data = "\n\x10word_cloud.proto\x12\x0frakit.wordcloud\"W\n\x0fWordCloudConfig\x12\x13\n\x0bwcloud_path\x18\x01 \x01(\t\x12\x14\n\x0c\x61uto_install\x18\x02 \x01(\x08\x12\x19\n\x11working_directory\x18\x03 \x01(\t\"S\n\nTextSource\x12\x13\n\ttext_file\x18\x01 \x01(\tH\x00\x12\x15\n\x0binline_text\x18\x02 \x01(\tH\x00\x12\x0f\n\x05stdin\x18\x03 \x01(\x08H\x00\x42\x08\n\x06source\"\xa6\x02\n\x0fGenerateRequest\x12\x30\n\x06\x63onfig\x18\x01 \x01(\x0b\x32 .rakit.wordcloud.WordCloudConfig\x12)\n\x04text\x18\x02 \x01(\x0b\x32\x1b.rakit.wordcloud.TextSource\x12\x14\n\x0coutput_image\x18\x03 \x01(\t\x12\r\n\x05width\x18\x04 \x01(\x05\x12\x0e\n\x06height\x18\x05 \x01(\x05\x12\x10\n\x08rng_seed\x18\x06 \x01(\x05\x12\x12\n\nmask_image\x18\x07 \x01(\t\x12\x11\n\tfont_file\x18\x08 \x01(\t\x12\x1a\n\x12\x65xclude_words_file\x18\t \x01(\t\x12\x11\n\tmax_words\x18\n \x01(\x05\x12\x19\n\x11publish_site_name\x18\x0b \x01(\t\"\xcf\x01\n\x0eGenerateResult\x12\x0f\n\x07success\x18\x01 \x01(\x08\x12\x0f\n\x07message\x18\x02 \x01(\t\x12\x14\n\x0coutput_image\x18\x03 \x01(\t\x12\x11\n\texit_code\x18\x04 \x01(\x05\x12\x0e\n\x06stdout\x18\x05 \x01(\t\x12\x0e\n\x06stderr\x18\x06 \x01(\t\x12\x1c\n\x14wcloud_was_installed\x18\x07 \x01(\x08\x12\x1c\n\x14wcloud_resolved_path\x18\x08 \x01(\t\x12\x16\n\x0ewcloud_version\x18\t \x01(\t\"`\n\nToolStatus\x12\x14\n\x0cwcloud_found\x18\x01 \x01(\x08\x12\x13\n\x0bwcloud_path\x18\x02 \x01(\t\x12\x13\n\x0b\x63\x61rgo_found\x18\x03 \x01(\x08\x12\x12\n\ncargo_path\x18\x04 \x01(\tB\x13\xea\x02\x10Rakit::Generatedb\x06proto3"
+
+pool = ::Google::Protobuf::DescriptorPool.generated_pool
+pool.add_serialized_file(descriptor_data)
+
+module Rakit
+  module Generated
+    WordCloudConfig = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("rakit.wordcloud.WordCloudConfig").msgclass
+    TextSource = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("rakit.wordcloud.TextSource").msgclass
+    GenerateRequest = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("rakit.wordcloud.GenerateRequest").msgclass
+    GenerateResult = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("rakit.wordcloud.GenerateResult").msgclass
+    ToolStatus = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("rakit.wordcloud.ToolStatus").msgclass
+  end
+end

data/lib/rakit/cli/file.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+require "json"
+require "google/protobuf"
+require "rakit/file"
+
+module Rakit
+  module CLI
+    module File
+      class << self
+        # @param argv [Array<String>] arguments after "file"
+        # @return [Integer] exit code
+        def run(argv)
+          return 1 if argv.empty?
+          sub = argv.shift
+          case sub
+          when "list" then run_list(argv)
+          when "copy" then run_copy(argv)
+          else
+            $stderr.puts "Unknown command: #{sub}. Use 'list' or 'copy'."
+            $stderr.puts "  rakit file list <directory> [--recursive] [--include-hidden] [--format console|json|proto-json]"
+            $stderr.puts "  rakit file copy <source> <destination> [--overwrite] [--create-directories] [--follow-symlinks] [--format ...]"
+            1
+          end
+        end
+
+        private
+
+        def run_list(argv)
+          opts = parse_list_argv(argv)
+          return 1 if opts[:error]
+          req = Rakit::File::ListRequest.new(
+            directory: opts[:directory],
+            recursive: opts[:recursive],
+            include_hidden: opts[:include_hidden],
+            config: Rakit::File::FileConfig.new(follow_symlinks: opts[:follow_symlinks])
+          )
+          result = Rakit::File.list(req)
+          render_list_result(result, opts[:format])
+          result.exit_code
+        end
+
+        def parse_list_argv(argv)
+          opts = { format: "console", recursive: false, include_hidden: false, follow_symlinks: false, directory: nil }
+          args = argv.dup
+          while (arg = args.shift)
+            case arg
+            when "--recursive" then opts[:recursive] = true
+            when "--include-hidden" then opts[:include_hidden] = true
+            when "--follow-symlinks" then opts[:follow_symlinks] = true
+            when "--format" then opts[:format] = args.shift || "console"
+            when /^--/
+              $stderr.puts "Unknown option: #{arg}"
+              opts[:error] = true
+            else
+              opts[:directory] = arg if opts[:directory].nil?
+            end
+          end
+          unless opts[:directory] && !opts[:directory].empty?
+            $stderr.puts "list requires <directory>"
+            opts[:error] = true
+          end
+          opts
+        end
+
+        def run_copy(argv)
+          opts = parse_copy_argv(argv)
+          return 1 if opts[:error]
+          req = Rakit::File::CopyRequest.new(
+            source: opts[:source],
+            destination: opts[:destination],
+            config: Rakit::File::FileConfig.new(
+              overwrite: opts[:overwrite],
+              create_directories: opts[:create_directories],
+              follow_symlinks: opts[:follow_symlinks]
+            )
+          )
+          result = Rakit::File.copy(req)
+          render_copy_result(result, opts[:format])
+          result.exit_code
+        end
+
+        def parse_copy_argv(argv)
+          opts = { format: "console", overwrite: false, create_directories: false, follow_symlinks: false, source: nil, destination: nil }
+          args = argv.dup
+          while (arg = args.shift)
+            case arg
+            when "--overwrite" then opts[:overwrite] = true
+            when "--create-directories" then opts[:create_directories] = true
+            when "--follow-symlinks" then opts[:follow_symlinks] = true
+            when "--format" then opts[:format] = args.shift || "console"
+            when /^--/
+              $stderr.puts "Unknown option: #{arg}"
+              opts[:error] = true
+            else
+              if opts[:source].nil?
+                opts[:source] = arg
+              elsif opts[:destination].nil?
+                opts[:destination] = arg
+              else
+                $stderr.puts "Unexpected argument: #{arg}"
+                opts[:error] = true
+              end
+            end
+          end
+          unless opts[:source] && opts[:destination]
+            $stderr.puts "copy requires <source> and <destination>"
+            opts[:error] = true
+          end
+          opts
+        end
+
+        def render_list_result(result, format)
+          $stderr.puts result.stderr if result.stderr && !result.stderr.empty? && !result.success
+          case format
+          when "json"
+            puts list_result_to_json(result)
+          when "proto-json"
+            puts Google::Protobuf.encode_json(result)
+          else
+            result.entries.each do |e|
+              puts "#{e.path}\t#{e.name}\t#{e.is_directory ? 'dir' : 'file'}"
+            end
+          end
+        end
+
+        def list_result_to_json(result)
+          h = {
+            success: result.success,
+            message: result.message.to_s,
+            entries: result.entries.map { |e| { path: e.path, name: e.name, is_directory: e.is_directory, is_symlink: e.is_symlink, size_bytes: e.size_bytes, modified_unix_ms: e.modified_unix_ms } },
+            exit_code: result.exit_code
+          }
+          JSON.generate(h)
+        end
+
+        def render_copy_result(result, format)
+          $stderr.puts result.stderr if result.stderr && !result.stderr.empty? && !result.success
+          case format
+          when "json"
+            puts copy_result_to_json(result)
+          when "proto-json"
+            puts Google::Protobuf.encode_json(result)
+          else
+            puts "Copied #{result.source} → #{result.destination}" if result.success
+          end
+        end
+
+        def copy_result_to_json(result)
+          h = {
+            success: result.success,
+            message: result.message.to_s,
+            source: result.source.to_s,
+            destination: result.destination.to_s,
+            exit_code: result.exit_code,
+            bytes_copied: result.bytes_copied
+          }
+          JSON.generate(h)
+        end
+      end
+    end
+  end
+end

data/lib/rakit/cli/markdown.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require "rakit/markdown"
+
+module Rakit
+  module CLI
+    module Markdown
+      class << self
+        # @param argv [Array<String>] arguments after "markdown"
+        # @return [Integer] exit code
+        def run(argv)
+          return 1 if argv.empty?
+          sub = argv.shift
+          case sub
+          when "pdf" then run_pdf(argv)
+          when "amalgamate" then run_amalgamate(argv)
+          else
+            $stderr.puts "Unknown command: #{sub}. Use 'pdf' or 'amalgamate'."
+            $stderr.puts "  rakit markdown pdf <input.md> [output.pdf]"
+            $stderr.puts "  rakit markdown amalgamate <source_dir> <target.md> [--create-directories]"
+            1
+          end
+        end
+
+        private
+
+        def run_pdf(argv)
+          opts = parse_pdf_argv(argv)
+          return 1 if opts[:error]
+          result = Rakit::Markdown.generate_pdf(opts[:input], opts[:output])
+          $stderr.puts result[:stderr] if result[:stderr] && !result[:stderr].empty? && !result[:success]
+          $stderr.puts result[:message] if result[:message] && !result[:message].empty? && !result[:success]
+          result[:exit_code] || (result[:success] ? 0 : 1)
+        end
+
+        def parse_pdf_argv(argv)
+          opts = { input: nil, output: nil, error: false }
+          args = argv.dup
+          pos = []
+          while (arg = args.shift)
+            if arg.start_with?("--")
+              $stderr.puts "Unknown option: #{arg}"
+              opts[:error] = true
+            else
+              pos << arg
+            end
+          end
+          opts[:input] = pos[0]
+          opts[:output] = pos[1] if pos.length > 1
+          unless opts[:input] && !opts[:input].empty?
+            $stderr.puts "pdf requires <input.md>"
+            opts[:error] = true
+          end
+          opts
+        end
+
+        def run_amalgamate(argv)
+          opts = parse_amalgamate_argv(argv)
+          return 1 if opts[:error]
+          result = Rakit::Markdown.amalgamate(opts[:source_dir], opts[:target], create_directories: opts[:create_directories])
+          $stderr.puts result[:message] if result[:message] && !result[:message].empty? && !result[:success]
+          result[:exit_code] || (result[:success] ? 0 : 1)
+        end
+
+        def parse_amalgamate_argv(argv)
+          opts = { source_dir: nil, target: nil, create_directories: false, error: false }
+          args = argv.dup
+          pos = []
+          while (arg = args.shift)
+            case arg
+            when "--create-directories" then opts[:create_directories] = true
+            when /^--/
+              $stderr.puts "Unknown option: #{arg}"
+              opts[:error] = true
+            else
+              pos << arg
+            end
+          end
+          opts[:source_dir] = pos[0]
+          opts[:target] = pos[1]
+          unless opts[:source_dir] && opts[:target]
+            $stderr.puts "amalgamate requires <source_dir> and <target.md>"
+            opts[:error] = true
+          end
+          opts
+        end
+      end
+    end
+  end
+end

data/lib/rakit/file.rb

@@ -0,0 +1,181 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "generated/rakit.file_pb"
+
+module Rakit
+  # Protobuf-first file operations (list directory, copy file). See specs/005-file-ops/contracts/ruby-api.md.
+  module File
+    class << self
+      # @param request [Rakit::File::ListRequest]
+      # @return [Rakit::File::ListResult]
+      def list(request)
+        dir_path = normalize_path(request.directory.to_s)
+        if dir_path.nil?
+          return error_list_result("Empty or invalid directory path", 1)
+        end
+        unless ::File.exist?(dir_path)
+          return error_list_result("Directory does not exist: #{dir_path}", 1)
+        end
+        unless ::File.directory?(dir_path)
+          return error_list_result("Not a directory: #{dir_path}", 1)
+        end
+
+        include_hidden = request.include_hidden
+        follow_symlinks = request.config&.follow_symlinks == true
+        entries = request.recursive ? list_entries_recursive(dir_path, include_hidden, follow_symlinks) : list_entries_one_dir(dir_path, include_hidden, follow_symlinks)
+
+        ListResult.new(
+          success: true,
+          message: "",
+          entries: entries,
+          exit_code: 0,
+          stderr: ""
+        )
+      rescue => e
+        error_list_result("#{e.message}", 1)
+      end
+
+      # @param request [Rakit::File::CopyRequest]
+      # @return [Rakit::File::CopyResult]
+      def copy(request)
+        config = request.config || FileConfig.new
+        src = normalize_path(request.source.to_s)
+        dest_raw = normalize_path(request.destination.to_s)
+
+        if src.nil? || dest_raw.nil?
+          return error_copy_result(request.source.to_s, request.destination.to_s, "Empty or invalid path", 1)
+        end
+        unless ::File.exist?(src)
+          return error_copy_result(src, dest_raw, "Source does not exist: #{src}", 1)
+        end
+        if ::File.directory?(src)
+          return error_copy_result(src, dest_raw, "Source is a directory (MVP: file only)", 1)
+        end
+
+        dest_path = resolve_copy_destination(src, dest_raw)
+        parent = ::File.dirname(dest_path)
+
+        unless ::File.directory?(parent)
+          if config.create_directories
+            FileUtils.mkdir_p(parent)
+          else
+            return error_copy_result(src, dest_path, "Parent directory does not exist: #{parent}", 1)
+          end
+        end
+
+        if ::File.file?(dest_path) && !config.overwrite
+          return error_copy_result(src, dest_path, "Destination file exists (use overwrite to replace)", 1)
+        end
+
+        bytes = perform_copy(src, dest_path, config)
+        CopyResult.new(
+          success: true,
+          message: "",
+          source: src,
+          destination: dest_path,
+          exit_code: 0,
+          stderr: "",
+          bytes_copied: bytes || 0
+        )
+      rescue => e
+        error_copy_result(request.source.to_s, request.destination.to_s, e.message, 1)
+      end
+
+      private
+
+      # T004: Path normalization. Returns expanded absolute path or nil if nil/empty.
+      def normalize_path(path, base_dir = nil)
+        return nil if path.nil?
+        s = path.to_s.strip
+        return nil if s.empty?
+        base = base_dir || Dir.pwd
+        ::File.expand_path(s, base)
+      end
+
+      def error_list_result(message, exit_code)
+        ListResult.new(success: false, message: message, entries: [], exit_code: exit_code, stderr: message)
+      end
+
+      def error_copy_result(source, destination, message, exit_code)
+        CopyResult.new(success: false, message: message, source: source.to_s, destination: destination.to_s, exit_code: exit_code, stderr: message)
+      end
+
+      # T005: List entries for one directory; sort by name; filter hidden; best-effort metadata.
+      def list_entries_one_dir(dir_path, include_hidden, follow_symlinks)
+        names = Dir.children(dir_path)
+        names.reject! { |n| n.start_with?(".") } unless include_hidden
+        names.sort!
+        names.map { |name| file_entry_for(::File.join(dir_path, name), name, follow_symlinks) }
+      end
+
+      def file_entry_for(abs_path, name, follow_symlinks)
+        stat = follow_symlinks ? (::File.stat(abs_path) rescue nil) : (::File.lstat(abs_path) rescue nil)
+        is_symlink = ::File.symlink?(abs_path)
+        is_dir = stat ? stat.directory? : false
+        size_bytes = (stat && stat.file?) ? (stat.size rescue 0) : 0
+        modified_unix_ms = stat ? (stat.mtime.to_f * 1000).to_i : 0
+        FileEntry.new(
+          path: abs_path,
+          name: name,
+          is_directory: is_dir,
+          is_symlink: is_symlink,
+          size_bytes: size_bytes,
+          modified_unix_ms: modified_unix_ms
+        )
+      rescue
+        FileEntry.new(path: abs_path, name: name, is_directory: false, is_symlink: false, size_bytes: 0, modified_unix_ms: 0)
+      end
+
+      # T006: Depth-first recursive list; children at each level sorted by name.
+      def list_entries_recursive(dir_path, include_hidden, follow_symlinks)
+        entries = list_entries_one_dir(dir_path, include_hidden, follow_symlinks)
+        result = []
+        entries.each do |entry|
+          result << entry
+          if entry.is_directory
+            result.concat(list_entries_recursive(entry.path, include_hidden, follow_symlinks))
+          end
+        end
+        result
+      end
+
+      # Resolve destination: if existing directory, copy into it with basename(source); else file path.
+      def resolve_copy_destination(source, destination)
+        return ::File.join(destination, ::File.basename(source)) if ::File.exist?(destination) && ::File.directory?(destination)
+        destination
+      end
+
+      # T007: Atomic copy where possible (temp then rename); respect follow_symlinks for source.
+      def perform_copy(source, dest_path, config)
+        if !config.follow_symlinks && ::File.symlink?(source)
+          # Copy symlink itself: create new symlink with same target
+          target = ::File.readlink(source)
+          ::File.delete(dest_path) if ::File.exist?(dest_path)
+          ::File.symlink(target, dest_path)
+          return 0 # best-effort bytes
+        end
+
+        content = ::File.binread(source)
+        dest_dir = ::File.dirname(dest_path)
+        temp_path = ::File.join(dest_dir, ".rakit_copy_#{Process.pid}_#{object_id}_#{::File.basename(dest_path)}")
+        bytes = nil
+        begin
+          ::File.write(temp_path, content)
+          bytes = content.bytesize
+          ::File.rename(temp_path, dest_path)
+        rescue Errno::EXDEV, Errno::EPERM
+          # Cross-filesystem or rename not allowed: fall back to overwrite
+          ::File.write(dest_path, content)
+          bytes = content.bytesize
+          ::File.delete(temp_path) if ::File.exist?(temp_path)
+        ensure
+          ::File.delete(temp_path) if ::File.exist?(temp_path)
+        end
+        bytes
+      rescue => e
+        raise "Failed to copy: #{e.message}"
+      end
+    end
+  end
+end

data/lib/rakit/gem.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 require "fileutils"
+require "json"
+require "open3"
 require "rubygems/package"
 
 module Rakit
@@ -44,9 +46,8 @@ module Rakit
       raise "Gem not found: #{gem_path}. Run rake package first." unless ::File.file?(gem_path)
 
       base = ::File.basename(gem_path, ".gem")
-      parts = base.split("-")
-      version = parts.pop
-      name = parts.join("-")
+      name, version = parse_gem_basename(base)
+      raise "Could not parse name/version from #{base}.gem" unless name && version
 
       if version_published?(name, version)
         warn "publish: Version #{version} of #{name} is already published on rubygems.org. Skipping push. Bump the version in the gemspec to publish again."
@@ -57,14 +58,86 @@ module Rakit
       raise "gem push failed" unless success
     end
 
+    # Parse "name-version" basename (no .gem) into [name, version].
+    # Version is the last hyphen-separated segment that looks like a version (e.g. 0.1.5).
+    def self.parse_gem_basename(base)
+      # Match name (may contain hyphens) and version (digits and dots, optional pre-release suffix).
+      m = base.match(/\A(.+)-(\d+(?:\.\d+)*(?:\.\w+)?)\z/)
+      m ? [m[1], m[2]] : nil
+    end
+
     def self.version_published?(name, version)
+      begin
+        return true if version_published_gem_list?(name, version)
+      rescue StandardError
+        # try API fallbacks
+      end
+      begin
+        return true if version_published_v2?(name, version)
+      rescue StandardError
+        # try v1 fallback
+      end
+      begin
+        return true if version_published_v1?(name, version)
+      rescue StandardError
+        nil
+      end
+      false
+    end
+
+    # Run `gem list NAME --remote` and check if version appears in the output.
+    def self.version_published_gem_list?(name, version)
+      out, err, status = Open3.capture3("gem", "list", name, "--remote")
+      return false unless status.success?
+      # Output format: "name (1.0.0, 0.9.0)" or "name (1.0.0)"
+      combined = "#{out}#{err}"
+      combined.each_line do |line|
+        next unless line.include?(name)
+        if line =~ /\s*#{Regexp.escape(name)}\s*\((.*)\)/
+          versions = Regexp.last_match(1).split(",").map(&:strip)
+          return true if versions.include?(version)
+        end
+      end
+      false
+    end
+
+    # GET /api/v2/rubygems/{name}/versions/{version}.json (follows redirects)
+    def self.version_published_v2?(name, version)
       require "net/http"
       require "uri"
       uri = URI("https://rubygems.org/api/v2/rubygems/#{URI::DEFAULT_PARSER.escape(name)}/versions/#{URI::DEFAULT_PARSER.escape(version)}.json")
-      response = Net::HTTP.get_response(uri)
+      response = http_get_following_redirects(uri)
       response.is_a?(Net::HTTPSuccess)
-    rescue StandardError
-      false
+    end
+
+    # GET /api/v1/versions/{name}.json and check if version is in the list
+    def self.version_published_v1?(name, version)
+      require "net/http"
+      require "json"
+      require "uri"
+      uri = URI("https://rubygems.org/api/v1/versions/#{URI::DEFAULT_PARSER.escape(name)}.json")
+      response = http_get_following_redirects(uri)
+      return false unless response.is_a?(Net::HTTPSuccess)
+      list = JSON.parse(response.body)
+      list.is_a?(Array) && list.any? { |h| h["number"] == version }
+    end
+
+    def self.http_get_following_redirects(uri, limit: 5)
+      raise ArgumentError, "redirect limit exceeded" if limit <= 0
+      require "net/http"
+      response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https", open_timeout: 10, read_timeout: 10) do |http|
+        request = Net::HTTP::Get.new(uri)
+        request["User-Agent"] = "rakit (https://rubygems.org/gems/rakit)"
+        http.request(request)
+      end
+      case response
+      when Net::HTTPRedirection
+        location = response["location"]
+        next_uri = location.match?(/\Ahttps?:\/\//) ? URI(location) : URI.join(uri, location)
+        http_get_following_redirects(next_uri, limit: limit - 1)
+      else
+        response
+      end
     end
   end
 end

data/lib/rakit/markdown.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+require "kramdown"
+require "fileutils"
+
+module Rakit
+  module Markdown
+    class << self
+      # @param source_path [String] path to markdown file
+      # @param output_path [String, nil] path for PDF; default same dir, .pdf extension
+      # @return [Hash] { success: Boolean, message: String, exit_code: Integer, stderr: String (optional) }
+      def generate_pdf(source_path, output_path = nil)
+        validated = validate_file_path(source_path)
+        unless validated
+          return { success: false, message: "Source path must exist and be a file", exit_code: 1, stderr: "" }
+        end
+        # Explicit output_path is relative to CWD (or absolute); default is same dir as source, .pdf extension
+        out_path = if output_path.to_s.strip.empty?
+          nil
+        else
+          ::File.expand_path(output_path.to_s.strip)
+        end
+        out_path ||= ::File.join(::File.dirname(validated), ::File.basename(validated, ".*") + ".pdf")
+        out_path = ::File.expand_path(out_path)
+
+        unless wkhtmltopdf_available?
+          msg = wkhtmltopdf_install_message
+          return { success: false, message: msg, exit_code: 1, stderr: msg }
+        end
+
+        temp_html = nil
+        begin
+          md_content = ::File.read(validated, encoding: "UTF-8")
+          html = markdown_to_html(md_content)
+          temp_html = ::File.join(::File.dirname(out_path), ".rakit_md_#{Process.pid}_#{object_id}.html")
+          ::File.write(temp_html, html, encoding: "UTF-8")
+          ok = system("wkhtmltopdf", "-q", temp_html, out_path, out: ::File::NULL, err: ::File::NULL)
+          unless ok
+            ::File.unlink(out_path) if ::File.file?(out_path)
+            return { success: false, message: "wkhtmltopdf failed", exit_code: 1, stderr: "" }
+          end
+          { success: true, message: "", exit_code: 0, stderr: "" }
+        rescue => e
+          ::File.unlink(out_path) if out_path && ::File.file?(out_path)
+          { success: false, message: e.message, exit_code: 1, stderr: "" }
+        ensure
+          ::File.unlink(temp_html) if temp_html && ::File.file?(temp_html)
+        end
+      end
+
+      # @param source_dir [String] directory to collect .md files from
+      # @param target_path [String] path to output markdown file
+      # @param create_directories [Boolean]
+      # @return [Hash] { success: Boolean, message: String, exit_code: Integer }
+      def amalgamate(source_dir, target_path, create_directories: false)
+        validated_dir = validate_dir_path(source_dir)
+        unless validated_dir
+          return { success: false, message: "Source directory must exist and be a directory", exit_code: 1 }
+        end
+        target_norm = normalize_path(target_path)
+        unless target_norm
+          return { success: false, message: "Target path is required", exit_code: 1 }
+        end
+        unless target_outside_source?(validated_dir, target_norm)
+          return { success: false, message: "Target path must be outside source directory", exit_code: 1 }
+        end
+        parent = ::File.dirname(target_norm)
+        unless ::File.directory?(parent)
+          if create_directories
+            ::FileUtils.mkdir_p(parent)
+          else
+            return { success: false, message: "Parent directory does not exist; use create_directories: true", exit_code: 1 }
+          end
+        end
+        begin
+          content = amalgamate_collect(validated_dir)
+          ::File.write(target_norm, content, encoding: "UTF-8")
+          { success: true, message: "", exit_code: 0 }
+        rescue => e
+          ::File.unlink(target_norm) if ::File.file?(target_norm)
+          { success: false, message: e.message, exit_code: 1 }
+        end
+      end
+
+      private
+
+      # T004: Normalize path; return nil if nil/empty after strip.
+      def normalize_path(path, base_dir = nil)
+        return nil if path.nil?
+        s = path.to_s.strip
+        return nil if s.empty?
+        base_dir ? ::File.expand_path(s, base_dir) : ::File.expand_path(s)
+      end
+
+      # T004: Validate path exists and is a file. Return expanded path or nil.
+      def validate_file_path(path)
+        norm = normalize_path(path)
+        return nil unless norm
+        return nil unless ::File.file?(norm)
+        norm
+      end
+
+      # T004: Validate path exists and is a directory. Return expanded path or nil.
+      def validate_dir_path(path)
+        norm = normalize_path(path)
+        return nil unless norm
+        return nil unless ::File.directory?(norm)
+        norm
+      end
+
+      # T005: Target is outside source_dir (not equal, not under). Both should be normalized.
+      def target_outside_source?(source_dir, target_path)
+        src = source_dir.to_s.gsub(::File::SEPARATOR, "/").chomp("/")
+        target = ::File.expand_path(target_path).to_s.gsub(::File::SEPARATOR, "/")
+        target_dir = ::File.dirname(target).gsub(::File::SEPARATOR, "/")
+        return false if target_dir == src
+        return false if target_dir.start_with?(src + "/")
+        return false if target == src
+        true
+      end
+
+      # T006: True if wkhtmltopdf is available.
+      def wkhtmltopdf_available?
+        out = `wkhtmltopdf --version 2>&1`
+        $?.success?
+      end
+
+      # T006: Platform-specific install message for wkhtmltopdf.
+      def wkhtmltopdf_install_message
+        if ::Gem.win_platform?
+          "Install wkhtmltopdf: choco install wkhtmltopdf"
+        elsif ::File.exist?("/usr/bin/sw_vers") || RUBY_PLATFORM.include?("darwin")
+          "Install wkhtmltopdf: brew install wkhtmltopdf"
+        else
+          "Install wkhtmltopdf: e.g. apt install wkhtmltopdf or yum install wkhtmltopdf"
+        end
+      end
+
+      # T007: Convert markdown string to HTML. Empty input -> minimal HTML.
+      def markdown_to_html(md_string)
+        return "" if md_string.nil? || md_string.to_s.strip.empty?
+        Kramdown::Document.new(md_string.to_s).to_html
+      end
+
+      # T008: Collect all **/*.md under source_dir, sort by path, concatenate with separator. Return string.
+      AMALGAM_SEPARATOR = "\n\n"
+
+      def amalgamate_collect(source_dir)
+        norm_dir = ::File.expand_path(source_dir)
+        pattern = ::File.join(norm_dir, "**", "*.md")
+        paths = ::Dir.glob(pattern).select { |p| ::File.file?(p) }.sort
+        return "" if paths.empty?
+        paths.map { |p| ::File.read(p, encoding: "UTF-8") }.join(AMALGAM_SEPARATOR)
+      end
+    end
+  end
+end

data/lib/rakit/static_web_server.rb

@@ -102,6 +102,7 @@ module Rakit
       root_path = ::File.expand_path(root)
       pid = spawn(bin, root_path, "--port", p.to_s, out: ::File::NULL, err: ::File::NULL)
       Process.detach(pid)
+      FileUtils.mkdir_p(::File.dirname(pid_file_path))
       ::File.write(pid_file_path, pid.to_s)
       true
     end

data/lib/rakit.rb

@@ -26,6 +26,7 @@ require_relative "rakit/protobuf"
 autoload :Shell, "rakit/shell"
 require_relative "rakit/static_web_server"
 require_relative "rakit/word_count"
+require_relative "rakit/word_cloud"
 require_relative "rakit/file"
 require_relative "rakit/azure/dev_ops"
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rakit
 version: !ruby/object:Gem::Version
-  version: 0.1.5
+  version: 0.1.7
 platform: ruby
 authors:
 - rakit
@@ -41,16 +41,22 @@ dependencies:
   name: google-protobuf
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '3.25'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '6'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '3.25'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '6'
 - !ruby/object:Gem::Dependency
   name: rubyzip
   requirement: !ruby/object:Gem::Requirement
@@ -65,6 +71,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: kramdown
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.4'
 - !ruby/object:Gem::Dependency
   name: grpc-tools
   requirement: !ruby/object:Gem::Requirement
@@ -106,11 +126,16 @@ files:
 - lib/generated/rakit.word_count_pb.rb
 - lib/generated/shell_pb.rb
 - lib/generated/static_web_server_pb.rb
+- lib/generated/word_cloud_pb.rb
 - lib/rakit.rb
 - lib/rakit/azure/dev_ops.rb
+- lib/rakit/cli/file.rb
+- lib/rakit/cli/markdown.rb
 - lib/rakit/cli/word_count.rb
+- lib/rakit/file.rb
 - lib/rakit/gem.rb
 - lib/rakit/git.rb
+- lib/rakit/markdown.rb
 - lib/rakit/protobuf.rb
 - lib/rakit/shell.rb
 - lib/rakit/static_web_server.rb