rakpak 1.1.0 → 1.2.0

data/lib/rakpak/entry.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 module Rakpak
-  # One filesystem row. Stats are taken once, lazily, and never raise.
   class Entry
     attr_reader :path, :name
 
@@ -64,13 +63,11 @@ module Rakpak
       Theme::NORMAL
     end
 
-    # The name as comparable text: lowercased, with bytes that are not
-    # valid UTF-8 replaced so downcase cannot raise on them.
+    # Scrub invalid UTF-8 first, or downcase raises.
     def fold
       @fold ||= (@name.valid_encoding? ? @name : @name.scrub("?")).downcase
     end
 
-    # Dirs first, then case-insensitive natural order.
     def sort_key
       [dir? ? 0 : 1, fold, @name]
     end

data/lib/rakpak/formats.rb

@@ -1,9 +1,6 @@
 # frozen_string_literal: true
 
 module Rakpak
-  # What this machine can actually do. Nothing here is assumed; every codec
-  # is probed against PATH so the UI can grey out what is missing instead of
-  # failing halfway through a job.
   module Tools
     module_function
 
@@ -27,8 +24,7 @@ module Rakpak
       @zip_bz2 = false
     end
 
-    # GNU tar, bsdtar (macOS) and busybox tar disagree about flags. Detect
-    # once so the UI only offers switches this tar actually understands.
+    # GNU tar, bsdtar (macOS) and busybox tar disagree about flags.
     def tar_flavor
       return @tar_flavor if defined?(@tar_flavor)
 
@@ -54,7 +50,6 @@ module Rakpak
 
   end
 
-  # A tar compression backend.
   Codec = Struct.new(:id, :label, :ext, :bin, :levels, :default, :threads, :blurb,
                      :level_opt, keyword_init: true) do
     def available? = bin.nil? || Tools.available?(bin)
@@ -62,10 +57,8 @@ module Rakpak
     def why_not = available? ? nil : "#{bin} not installed"
     def container? = false
 
-    # ".tar.gz" for a tarball, ".gz" when compressing a lone file.
     def single_ext = ext.delete_prefix(".tar")
 
-    # The compressor reading a named file and writing to stdout.
     def argv(level)
       return nil if bin.nil?
 
@@ -76,8 +69,7 @@ module Rakpak
       parts
     end
 
-    # tar's --use-compress-program string; tar splits it on spaces itself.
-    # The long form is understood by both GNU tar and bsdtar.
+    # tar splits --use-compress-program on spaces itself; GNU tar and bsdtar both accept it.
     def filter(level) = argv(level)&.join(" ")
   end
 
@@ -102,7 +94,6 @@ module Rakpak
 
   def self.tar_codec(id) = TAR_CODECS.find { |c| c.id == id }
 
-  # A zip container written by Info-ZIP, with one of its entry methods.
   ZipMethod = Struct.new(:id, :label, :flag, :levels, :default, :blurb, keyword_init: true) do
     def available?
       flag == "bzip2" ? Tools.zip_has_bzip2? : Tools.available?("zip")
@@ -127,15 +118,11 @@ module Rakpak
                   blurb: ".zip with no compression")
   ].freeze
 
-  # Everything the zip target can produce: a .zip of anything, or a lone
-  # file run through one compressor (notes.txt.gz).
   COMPRESSORS = (ZIP_METHODS + TAR_CODECS.reject { |c| c.id == :none }).freeze
 
   def self.compressor(id) = COMPRESSORS.find { |c| c.id == id }
 
-  # Toggleable switches, rendered as a checklist.
   Flag = Struct.new(:id, :label, :args, :on, :blurb, :needs, keyword_init: true) do
-    # `needs` lists the tar flavours that understand this switch.
     def supported?(flavor) = needs.nil? || needs.include?(flavor)
   end
 
@@ -143,7 +130,6 @@ module Rakpak
   BOTH = %i[gnu bsd unknown].freeze
   ALL  = %i[gnu bsd busybox unknown].freeze
 
-  # Only flags this machine's tar understands are offered.
   def self.tar_flags(flavor = Tools.tar_flavor)
     [
       Flag.new(id: :verbose, label: "verbose", args: ["-v"], on: true, needs: ALL,

data/lib/rakpak/job.rb

@@ -3,8 +3,6 @@
 require_relative "plan"
 
 module Rakpak
-  # Runs a plan's steps on a worker thread, streaming output into a ring
-  # buffer. The UI polls it; backgrounding is just "stop looking at it".
   class Job
     KEEP = 400
 
@@ -24,7 +22,7 @@ module Rakpak
       @verbose = true
       @cancel = false
       @pid = nil
-      @spawned = nil # output path of the step currently being written
+      @spawned = nil
       @started_at = nil
       @finished_at = nil
     end
@@ -57,8 +55,6 @@ module Rakpak
 
     def total_files = @total_files
 
-    # nil when there is nothing to measure progress against: no file total,
-    # or a step whose tool is not listing members (verbose off).
     def fraction
       return nil unless @total_files&.positive? && @verbose
 
@@ -67,8 +63,7 @@ module Rakpak
       [base + (per * [@file_count.to_f / @total_files, 1.0].min), 1.0].min
     end
 
-    # Bytes on disk for whatever this step is writing right now. A folder
-    # being extracted into has only its own inode size, which means nothing.
+    # A directory's own size means nothing mid-extraction.
     def output_size
       out = writing_now
       return nil if out.nil? || File.directory?(out)
@@ -78,8 +73,6 @@ module Rakpak
       nil
     end
 
-    # A step redirected to a file is writing that file; otherwise the tool is
-    # writing the plan's output itself.
     def writing_now
       i = [@step_index, @steps.size - 1].min
       @steps[i]&.[](3) || @plan.outputs[[i, @plan.outputs.size - 1].min]
@@ -101,7 +94,6 @@ module Rakpak
       kill_current
     end
 
-    # Blocks until the worker is finished, for at most `secs`.
     def wait(secs = nil) = @thread&.join(secs)
 
     private
@@ -113,7 +105,7 @@ module Rakpak
       return unless pid
 
       begin
-        Process.kill("TERM", -pid) # the whole group: tar and its compressor
+        Process.kill("TERM", -pid) # whole group: tar and its compressor
       rescue StandardError
         nil
       end
@@ -145,7 +137,7 @@ module Rakpak
         @step_index = idx
         @file_count = 0
         @verbose = verbose
-        # A cancel that lands between steps must not start the next one.
+        # A cancel between steps must not start the next one.
         return finish(:cancelled) if @cancel
 
         push("▸ #{label}: #{Plan.show_cmd(argv, stdout)}")
@@ -166,8 +158,7 @@ module Rakpak
     end
 
     def failure_message(label, status)
-      # status is nil when the command could not be spawned at all; in that
-      # case run_step already recorded the useful message.
+      # nil status: spawn failed and run_step already set @error.
       return @error || "#{label} could not be started" if status.nil?
 
       if status.signaled?
@@ -187,14 +178,8 @@ module Rakpak
       @finished_at = now
     end
 
-    # A half-written archive is worse than no archive: it opens, lists a few
-    # members, then fails. Remove it, but only the output of the step that
-    # was actually interrupted. Archives finished by earlier steps are whole
-    # and must survive, and a step that never spawned wrote nothing.
-    #
-    # An extraction is the other way round: its output is a folder full of
-    # files that were there before, or are the part of the job that did
-    # work. Those are not ours to throw away.
+    # Remove only the interrupted step's half-written archive; earlier ones are whole.
+    # Extraction output may hold pre-existing files, so it is never removed.
     def cleanup_incomplete
       return unless @plan.clobbers_output?
 
@@ -207,15 +192,9 @@ module Rakpak
       push("could not remove #{File.basename(path)}: #{e.message}")
     end
 
-    # `stdout` names a file the command's output is the archive for (gzip -c);
-    # otherwise stdout joins stderr in the log.
     def run_step(argv, stdout = nil)
       out = stdout || @plan.outputs[@step_index]
-      # Every tool asked to create an archive gets a clear path to write to,
-      # and the confirm screen has said an existing one will be overwritten.
-      # zip would otherwise update it in place, keeping members that no
-      # longer exist. An extraction writes into a folder instead, which must
-      # be left exactly as it is.
+      # zip would otherwise update an existing archive in place, keeping stale members.
       clear_path(out) if @plan.clobbers_output?
       @spawned = out
 
@@ -250,8 +229,7 @@ module Rakpak
           rescue EOFError
             break
           end
-          # A pipe hands back binary. Filenames are arbitrary bytes, so this
-          # has to be made printable before it can meet the UTF-8 frame.
+          # Filenames are arbitrary bytes; scrub before they meet the UTF-8 frame.
           buf << chunk.force_encoding(Encoding::UTF_8).scrub("·")
           # tar emits newlines, zip rewrites lines with \r.
           while (m = buf.match(/[\r\n]/))
@@ -269,11 +247,7 @@ module Rakpak
       status
     end
 
-    # Never a directory: that is a destination, not something we wrote.
-    #
-    # lstat, not exist?: a symlink whose target is missing does not "exist",
-    # and leaving one here would mean opening the path later and writing
-    # through it to wherever it points. Remove the link itself.
+    # lstat: a dangling symlink is not exist?, and writing through it would escape the folder.
     def clear_path(path)
       return unless path
 
@@ -285,14 +259,11 @@ module Rakpak
       File.unlink(path) unless st.directory?
     end
 
-    # The tool must never open its own output: between clearing the path and
-    # the spawn, anything already sitting there could be a symlink out of the
-    # folder. O_EXCL means we either create the file or refuse to write at
-    # all, and O_NOFOLLOW refuses a link even if one appears first.
+    # O_EXCL|O_NOFOLLOW: never write through a symlink planted after clear_path.
     SINK_FLAGS = File::WRONLY | File::CREAT | File::EXCL |
                  (defined?(File::NOFOLLOW) ? File::NOFOLLOW : 0)
 
-    # 0666 so the result lands on the user's umask, as a shell redirect would.
+    # 0666 so the result respects umask, like a shell redirect.
     def open_sink(path) = File.open(path, SINK_FLAGS, 0o666)
 
     def record(line)

data/lib/rakpak/modal.rb

@@ -4,8 +4,6 @@ require_relative "theme"
 require_relative "text"
 
 module Rakpak
-  # Base class for the centred overlay panels. Subclasses fill the body;
-  # geometry, frame, title and footer are handled here.
   class Modal
     attr_reader :result
 
@@ -15,7 +13,6 @@ module Rakpak
       @result = nil
     end
 
-    # Desired [width, height] given the screen.
     def dims(screen)
       [[screen.w - 6, 72].min, [screen.h - 4, 20].min]
     end
@@ -41,11 +38,9 @@ module Rakpak
 
     def body(screen, x, y, w, h); end
 
-    # :done, :cancel or nil
     def handle(_key) = nil
   end
 
-  # A vertical list of choices, some of which may be unavailable.
   class SelectModal < Modal
     Item = Struct.new(:label, :value, :blurb, :enabled, :why, keyword_init: true)
 
@@ -122,7 +117,6 @@ module Rakpak
     end
   end
 
-  # A form of mixed rows: cycling choices, numeric ranges and toggles.
   class FormModal < Modal
     Row = Struct.new(:kind, :label, :hint, :get, :set, :values, keyword_init: true)
 
@@ -214,7 +208,6 @@ module Rakpak
       end
     end
 
-    # The reason the current settings cannot be run, or nil.
     def unusable
       @rows.each do |row|
         next unless row.kind == :choice
@@ -269,8 +262,6 @@ module Rakpak
     end
   end
 
-  # Single-line text field with the editing keys people expect. `validate`
-  # is given the trimmed text and returns a reason to refuse it, or nil.
   class InputModal < Modal
     def initialize(title:, value: "", hint: "", footer: "enter accept · esc back", validate: nil)
       super(title: title, footer: footer)
@@ -294,11 +285,10 @@ module Rakpak
       field(screen, x, y + (@hint.empty? ? 0 : 2), w, active: true)
     end
 
-    # The text box on its own, for embedding in another panel.
     def field(screen, x, row, w, active: true)
       screen.fill(x, row, w, 1, " ", Theme::SEL_BG)
       width = w - 2
-      # Scroll so the cursor is visible, counting columns, not characters.
+      # Scroll by display columns, not characters.
       off = 0
       off += 1 while off < @cur && Text.width(@buf[off...@cur]) >= width
       shown = +""
@@ -342,7 +332,9 @@ module Rakpak
       when :ctrl_u then @buf.slice!(0, @cur) && (@cur = 0)
       when :ctrl_k then @buf.slice!(@cur..)
       when :ctrl_w
-        left = @buf[0, @cur].sub(/\S*\s*\z/, "")
+        left = @buf[0, @cur].rstrip
+        boundary = left.rindex(/\s/)
+        left = boundary ? left[0..boundary] : ""
         @buf = left + (@buf[@cur..] || "")
         @cur = left.length
       when :space then insert(" ")
@@ -359,8 +351,6 @@ module Rakpak
     end
   end
 
-  # Where the archive goes: two ready-made folders and a field for any
-  # other. Typing anything moves to the field; 1, 2 and 3 pick directly.
   class WhereModal < Modal
     attr_reader :index
 
@@ -417,8 +407,6 @@ module Rakpak
       nil
     end
 
-    # Once the field is active, j, k and digits are text like anything
-    # else; arrows and tab still move between the choices.
     def field_key(key)
       @index = 2
       @field.handle(key)
@@ -444,9 +432,71 @@ module Rakpak
     end
   end
 
-  # Read-only panel: the exact commands, warnings, and a go/no-go. Only
-  # enter runs it: a single letter is too easy to hit while meaning
-  # something else, and b in particular reads as "back".
+  # Result is the typed names, or :tag to go mark exclusions in the file view.
+  class ExcludeModal < Modal
+    def initialize(text:, marked:)
+      super(title: "exclude", footer: "↑↓ pick · enter continue · esc back")
+      @field = InputModal.new(title: "", value: text)
+      @marked = marked
+      @index = 0
+    end
+
+    def text = @field.text
+
+    def dims(screen)
+      [[[screen.w - 6, 84].min, 44].max, [9 + [@marked.size, 1].max, screen.h - 2].min]
+    end
+
+    def body(screen, x, y, w, h)
+      choice(screen, x, y, w, "1. Names", 0)
+      @field.field(screen, x + 12, y, w - 12, active: @index.zero?)
+      screen.put(x + 3, y + 1, Text.fit("commas between; each matches at any depth, with all it holds", w - 3),
+                 Theme::MODAL_BG + Theme::DIM)
+      choice(screen, x, y + 2, w, "2. Tag files and directories", 1)
+      if @marked.empty?
+        screen.put(x, y + 4, "nothing marked", Theme::MODAL_BG + Theme::FAINT)
+        return
+      end
+      screen.put(x, y + 4, "marked", Theme::MODAL_BG + Theme::TITLE)
+      rows = h - 5
+      return if rows < 1
+
+      shown = @marked.size > rows ? @marked.first(rows - 1) : @marked
+      shown.each_with_index do |m, i|
+        screen.put(x + 3, y + 5 + i, Text.fit_left(m, w - 3), Theme::MODAL_BG + Theme::NORMAL)
+      end
+      return if shown.size == @marked.size
+
+      screen.put(x + 3, y + 5 + shown.size, "… #{@marked.size - shown.size} more", Theme::MODAL_BG + Theme::FAINT)
+    end
+
+    def choice(screen, x, y, w, label, i)
+      sel = i == @index
+      bg = sel ? Theme::CUR_BG : Theme::MODAL_BG
+      screen.fill(x - 1, y, w + 2, 1, " ", bg)
+      screen.put(x, y, label, bg + (sel ? "\e[1;38;5;231m" : Theme::NORMAL))
+    end
+
+    def handle(key)
+      case key
+      when :esc then return :cancel
+      when :enter
+        @result = @index.zero? ? text : :tag
+        return :done
+      when :up, :down, :tab then @index = 1 - @index
+      else
+        # On row 2, j/k move; anything else is typing, so it lands in the field.
+        if @index == 1 && %w[j k].include?(key) then @index = 0
+        else
+          @index = 0
+          @field.handle(key)
+        end
+      end
+      nil
+    end
+  end
+
+  # Only enter runs it: a single letter (b reads as "back") is too easy to hit by mistake.
   class ConfirmModal < Modal
     def initialize(title:, lines:, warnings: [], errors: [], footer: nil)
       super(title: title,
@@ -462,8 +512,7 @@ module Rakpak
       [w, [h, screen.h - 2].min]
     end
 
-    # Commands are wrapped rather than clipped: the whole point of this
-    # panel is that you can read exactly what will run.
+    # Wrap, don't clip: the user must see exactly what will run.
     def laid_out(w)
       @lines.flat_map do |style, text|
         if style == :cmd
@@ -514,8 +563,6 @@ module Rakpak
     end
   end
 
-  # Transient notice panel. Scrolls when the content is taller than the
-  # terminal, which the key list usually is on a short screen.
   class MessageModal < Modal
     def initialize(title:, lines:, style: Theme::ERR)
       super(title: title, footer: "any key to dismiss")