rakpak 1.0.0 → 1.2.0

data/lib/rakpak/browser.rb

@@ -2,24 +2,28 @@
 
 require "set"
 require_relative "dir_cache"
+require_relative "plan"
 require_relative "theme"
 require_relative "text"
 
 module Rakpak
-  # The yazi-style three-pane file browser: parent, current, preview.
-  # Owns navigation and the tag set; knows nothing about archiving.
   class Browser
-    attr_reader :cwd, :tags, :filter
+    # Marking exclusions mid-pack: walking stays under root, back is where to return.
+    Scope = Struct.new(:root, :paths, :back)
+
+    attr_reader :cwd, :tags, :excludes, :filter
 
     def initialize(start_dir = Dir.pwd, sizer: nil)
       @dirs = DirCache.new
       @sizer = sizer
       @tags = Set.new
+      @excludes = Set.new
+      @scope = nil
       @cursor = {}
       @show_hidden = false
       @filter = nil
       @filtering = false
-      @show_queue = true # on until someone presses t
+      @show_queue = true
       @pending = nil
       @preview_cache = {}
       @cwd = resolve(start_dir)
@@ -31,10 +35,12 @@ module Rakpak
       d
     end
 
-    # ---------------------------------------------------------------- state
-
     def entries
       list = @dirs.list(@cwd, hidden: @show_hidden) || []
+      # Above the packed items, only they are reachable.
+      if @scope && @cwd == @scope.root && !@scope.paths.include?(@cwd)
+        list = list.select { |e| @scope.paths.include?(e.path) }
+      end
       return list unless @filter && !@filter.empty?
 
       needle = @filter.downcase
@@ -54,18 +60,19 @@ module Rakpak
     def show_queue? = @show_queue
     def filtering? = @filtering
 
+    def scoped? = !@scope.nil?
+
     def tag(path)
       path = File.expand_path(path)
+      @excludes.delete(path)
       return unless @tags.add?(path)
 
-      # A figure may linger from a cursor-only pack of this path; a new tag
-      # must not trust it.
+      # A figure may linger from a cursor-only pack of this path; don't trust it.
       @sizer&.forget(path)
       @sizer&.request(path)
     end
 
-    # Every path out of the tag set goes through here so the sizer drops
-    # its figure; re-tagging later must measure again, not serve a stale one.
+    # All tag removals must pass here so the sizer drops its now-stale figure.
     def untag(path)
       return unless @tags.delete?(path)
 
@@ -78,17 +85,55 @@ module Rakpak
       @tags.include?(entry.path) ? untag(entry.path) : tag(entry.path)
     end
 
+    def exclude(path)
+      path = File.expand_path(path)
+      untag(path)
+      @excludes << path
+    end
+
+    def toggle_exclude(entry = current)
+      return unless entry
+
+      @excludes.delete?(entry.path) || exclude(entry.path)
+    end
+
     def tag_all = entries.each { |e| tag(e.path) }
     def untag_all_here = entries.each { |e| untag(e.path) }
-    def clear_tags = @tags.to_a.each { |p| untag(p) }
+
+    def clear_tags
+      @tags.to_a.each { |p| untag(p) }
+      @excludes.clear
+    end
+
+    # One packed folder opens inside it; several open at their common parent.
+    def scope_to(paths, base)
+      root = paths.size == 1 && File.directory?(paths.first) ? paths.first : base
+      @scope = Scope.new(root, paths, [@cwd, @cursor[@cwd], @filter])
+      @cwd = root
+      @filter = nil
+    end
+
+    def leave_scope
+      @cwd, cursor, @filter = @scope.back
+      @cursor[@cwd] = cursor
+      @scope = nil
+    end
+
+    def mark_in_scope
+      e = current
+      return unless e
+      return :unmarkable unless @scope.paths.any? { |p| Plan.inside?(e.path, p) }
+
+      toggle_exclude(e)
+      move(1)
+      nil
+    end
 
     def replace_tags(list)
       (@tags.to_a - list).each { |p| untag(p) }
       list.each { |p| tag(p) }
     end
 
-    # Selections implied by the current state: explicit tags, else whatever
-    # the cursor is sitting on.
     def selection
       return @tags.to_a.sort if @tags.any?
 
@@ -104,14 +149,10 @@ module Rakpak
       @tags.each { |p| @sizer.request(p) }
     end
 
-    # ----------------------------------------------------------- navigation
-
     def move(delta)
       self.index = index + delta
     end
 
-    # One step at a time wraps: up from the top lands on the last entry,
-    # down from the bottom on the first. Page moves still stop at the ends.
     def step(delta)
       n = entries.size
       return if n.zero?
@@ -130,7 +171,7 @@ module Rakpak
     end
 
     def ascend
-      return if @cwd == "/"
+      return if @cwd == "/" || @cwd == @scope&.root
 
       child = @cwd
       @cwd = File.dirname(@cwd)
@@ -142,13 +183,13 @@ module Rakpak
     def goto(dir)
       d = File.expand_path(dir)
       return false unless File.directory?(d) && File.readable?(d)
+      return false if @scope && d != @scope.root && !Plan.inside?(d, @scope.root)
 
       @cwd = d
       @filter = nil
       true
     end
 
-    # Open the folder holding `path` with the cursor on it.
     def jump_to(path)
       path = File.expand_path(path)
       return false unless goto(File.dirname(path))
@@ -159,7 +200,6 @@ module Rakpak
       !idx.nil?
     end
 
-    # Returns :quit, :archive, :tags, :help, :jobs or nil.
     def handle(key)
       return handle_filter(key) if @filtering
 
@@ -170,8 +210,15 @@ module Rakpak
         when "h" then return goto(Dir.home) && nil
         when "r" then return goto("/") && nil
         end
-        # Anything else was not a chord: treat it as its own keystroke, so
-        # a stray g never swallows q, p or space.
+        # Not a chord: handle it as its own key so a stray g never swallows q, p or space.
+      end
+
+      if @scope
+        case key
+        when :space, "x" then return mark_in_scope
+        when "p", :esc then return :resume
+        when "a", "d", "D", "u", "T", "b" then return nil
+        end
       end
 
       result = case key
@@ -188,6 +235,9 @@ module Rakpak
       when :space
         toggle_tag
         move(1)
+      when "x"
+        toggle_exclude
+        move(1)
       when "a" then tag_all
       when "d" then untag_all_here
       when "D" then clear_tags
@@ -197,12 +247,13 @@ module Rakpak
       when :ctrl_r then refresh!
       when "~" then goto(Dir.home)
       when "p" then :archive
+      when "u" then :unpack
       when "T" then :tags
       when "?" then :help
       when "b" then :jobs
       when "q", :ctrl_c then :quit
       end
-      %i[archive tags help jobs quit].include?(result) ? result : nil
+      %i[archive unpack tags help jobs quit].include?(result) ? result : nil
     end
 
     def toggle_hidden
@@ -237,8 +288,6 @@ module Rakpak
 
     def page = @page_size || 10
 
-    # -------------------------------------------------------------- drawing
-
     def draw(screen, status_line)
       @page_size = screen.h - 5
       draw_header(screen)
@@ -249,8 +298,6 @@ module Rakpak
       draw_footer(screen, screen.h - 1, status_line)
     end
 
-    # Left to right: the queue (when shown), parent, current, preview. The
-    # queue takes its slice first and the usual three share what is left.
     def layout(w)
       panes = []
       x = 0
@@ -280,7 +327,10 @@ module Rakpak
     def draw_header(screen)
       screen.fill(0, 0, screen.w, 1, " ", Theme::HEAD)
       screen.put(1, 0, "rakpak", Theme::HEAD + "\e[1;38;5;39m")
-      right = tag_summary
+      right = if @scope then "marking exclusions"
+              elsif @excludes.any? then "#{tag_summary} · #{@excludes.size} excluded"
+              else tag_summary
+              end
       avail = screen.w - 10 - Text.width(right) - 3
       screen.put(9, 0, Text.fit_left(Text.tilde(@cwd), [avail, 1].max), Theme::HEAD + "\e[38;5;231m")
       screen.put(screen.w - Text.width(right) - 1, 0, right,
@@ -308,9 +358,6 @@ module Rakpak
       end
     end
 
-    # Everything queued for the next pack, wherever on the disk it lives:
-    # the name, then where it is, with the size at the edge and the running
-    # total on top. Stays put while you keep browsing.
     def draw_queue(screen, pane, y, h)
       x = pane[:x]
       w = pane[:w]
@@ -362,12 +409,16 @@ module Rakpak
         row = y + i
         sel = (top + i) == cur
         tagged = @tags.include?(e.path)
+        excluded = @excludes.include?(e.path)
         bg = if sel && active then Theme::CUR_BG
              elsif sel then Theme::SEL_BG
              end
         screen.fill(x, row, w, 1, " ", bg) if bg
-        mark_style = tagged ? (bg.to_s + Theme::TAG) : (bg.to_s + Theme::FAINT)
-        screen.put(x, row, tagged ? " ▌" : "  ", mark_style)
+        mark, mark_style = if tagged then [" ▌", Theme::TAG]
+                           elsif excluded then [" ✗", Theme::ERR]
+                           else ["  ", Theme::FAINT]
+                           end
+        screen.put(x, row, mark, bg.to_s + mark_style)
         name_style = bg ? bg + (sel && active ? "\e[1;38;5;231m" : e.style) : e.style
         avail = w - 3
         avail -= 5 unless pane[:kind] == :parent
@@ -422,8 +473,7 @@ module Rakpak
     end
 
     def file_preview(entry, w, h)
-      # Reading a FIFO or a device blocks until someone writes to it, which
-      # would freeze the UI with the cursor merely resting on the entry.
+      # Reading a FIFO or device blocks and would freeze the UI.
       kind = entry.target_stat
       return [["not a regular file", Theme::FAINT]] unless kind&.file?
 
@@ -443,7 +493,6 @@ module Rakpak
       [[e.class.name.split("::").last, Theme::ERR]]
     end
 
-    # Bytes per row adapts to the pane so the ASCII column always fits.
     def hexdump(bytes, rows, width)
       return [] if rows <= 0
 
@@ -487,7 +536,9 @@ module Rakpak
     end
 
     HINTS = [["space", "tag"], ["←→", "nav"], ["a", "all"], ["t", "queue"], ["/", "find"],
-             [".", "hidden"], ["p", "pack"], ["?", "help"]].freeze
+             [".", "hidden"], ["p", "pack"], ["u", "unpack"], ["?", "help"]].freeze
+    SCOPE_HINTS = [["space", "exclude"], ["←→", "nav"], ["/", "find"], [".", "hidden"],
+                   ["p", "back to pack"], ["?", "help"]].freeze
 
     def draw_footer(screen, y, status_line)
       screen.fill(0, y, screen.w, 1, " ", nil)
@@ -496,7 +547,7 @@ module Rakpak
         return
       end
       x = 1
-      HINTS.each do |k, label|
+      (@scope ? SCOPE_HINTS : HINTS).each do |k, label|
         break if x + Text.width(k) + Text.width(label) + 3 > screen.w
 
         x = screen.put(x, y, k, Theme::KEY)

data/lib/rakpak/dir_cache.rb

@@ -3,8 +3,6 @@
 require_relative "entry"
 
 module Rakpak
-  # Directory listings, memoised per (path, show_hidden). Cheap enough that
-  # the parent/preview panes can ask on every keystroke.
   class DirCache
     MAX_ENTRIES = 20_000
 
@@ -31,7 +29,7 @@ module Rakpak
       names.reject! { |n| n.start_with?(".") } unless hidden
       names = names.first(MAX_ENTRIES)
       names.map { |n| Entry.new(File.join(path, n), n) }.sort_by(&:sort_key)
-    rescue StandardError # EACCES, ENOENT, ENOTDIR, ELOOP and the rest
+    rescue StandardError
       nil
     end
   end

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,16 +63,21 @@ 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 directory's own size means nothing mid-extraction.
     def output_size
-      out = @plan.outputs[[@step_index, @plan.outputs.size - 1].min]
-      return nil unless out
+      out = writing_now
+      return nil if out.nil? || File.directory?(out)
 
       File.size(out)
     rescue StandardError
       nil
     end
 
+    def writing_now
+      i = [@step_index, @steps.size - 1].min
+      @steps[i]&.[](3) || @plan.outputs[[i, @plan.outputs.size - 1].min]
+    end
+
     def summary
       @plan.outputs.map do |o|
         size = begin
@@ -93,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
@@ -105,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
@@ -132,11 +132,12 @@ module Rakpak
     end
 
     def run_all
+      @plan.prepare
       @steps.each_with_index do |(label, argv, verbose, stdout), idx|
         @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)}")
@@ -149,6 +150,7 @@ module Rakpak
         end
         @spawned = nil
       end
+      @plan.commit
       finish(:done)
     rescue StandardError => e
       @error = "#{e.class}: #{e.message}"
@@ -156,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?
@@ -169,16 +170,19 @@ module Rakpak
     end
 
     def finish(state)
-      cleanup_incomplete if %i[failed cancelled].include?(state)
+      if %i[failed cancelled].include?(state)
+        cleanup_incomplete
+        @plan.rollback
+      end
       @state = state
       @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.
+    # 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?
+
       path = @spawned
       return unless path && File.exist?(path)
 
@@ -188,28 +192,28 @@ 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 = @plan.outputs[@step_index]
-      # Every tool here is asked to create the archive, 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.
-      File.unlink(out) if out && File.exist?(out)
+      out = stdout || @plan.outputs[@step_index]
+      # zip would otherwise update an existing archive in place, keeping stale members.
+      clear_path(out) if @plan.clobbers_output?
       @spawned = out
 
       rd, wr = IO.pipe
+      sink = nil
       begin
-        pid = Process.spawn(*argv, out: stdout ? [stdout, "wb"] : wr, err: wr, in: File::NULL,
+        sink = open_sink(stdout) if stdout
+        pid = Process.spawn(*argv, out: sink || wr, err: wr, in: File::NULL,
                                    pgroup: true, chdir: @plan.base)
       rescue StandardError => e
         # Nothing was spawned, so nothing will close these for us.
         rd.close
         wr.close
+        sink&.close
         @error = e.message
         return nil
       end
       wr.close
+      sink&.close
       @pid = pid
       # A cancel that raced the spawn saw no pid to signal; do it now.
       kill_current if @cancel
@@ -225,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]/))
@@ -244,6 +247,25 @@ module Rakpak
       status
     end
 
+    # lstat: a dangling symlink is not exist?, and writing through it would escape the folder.
+    def clear_path(path)
+      return unless path
+
+      st = begin
+        File.lstat(path)
+      rescue StandardError
+        return
+      end
+      File.unlink(path) unless st.directory?
+    end
+
+    # 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 respects umask, like a shell redirect.
+    def open_sink(path) = File.open(path, SINK_FLAGS, 0o666)
+
     def record(line)
       return if line.empty?