rakpak 1.1.0 → 1.2.0

data/lib/rakpak/plan.rb

@@ -4,19 +4,12 @@ require_relative "formats"
 require_relative "text"
 
 module Rakpak
-  # Turns a set of tagged paths plus the wizard's answers into one concrete
-  # command. Nothing here shells out; commands are spawned without a shell,
-  # so spaces and quotes in filenames are never a hazard.
-  #
-  # Three shapes of output, one file each:
-  #   :both   tar, then compress            name.tar.gz, name.tar.zst, ...
-  #   :tar    plain tar, no compression     name.tar
-  #   :zip    compression only              name.zip, or name.txt.gz for one file
+  # :both tar then compress, :tar plain tar, :zip compress only (name.zip, or name.txt.gz for one file)
   class Plan
     TARGETS = %i[both tar zip].freeze
 
-    attr_reader :paths
-    attr_accessor :outdir, :basename, :target
+    attr_reader :paths, :excluded
+    attr_accessor :outdir, :basename, :target, :excludes
     attr_accessor :tar_codec, :tar_level, :tar_flags, :compressor, :comp_level, :zip_flags
 
     def initialize(paths:, outdir:, basename: "archive", target: :both)
@@ -24,7 +17,8 @@ module Rakpak
       @outdir = outdir
       @basename = basename
       @target = target
-      # gzip is the one every system can read; anything else is opt-in.
+      @excludes = []
+      @excluded = []
       @tar_codec = TAR_CODECS.find { |c| c.id == :gzip && c.available? } || tar_codec_fallback
       @tar_level = @tar_codec.default
       @tar_flags = Rakpak.tar_flags
@@ -33,12 +27,8 @@ module Rakpak
       @zip_flags = Rakpak.zip_flags
     end
 
-    # Drop anything already covered by another selection: tagging ~/docs and
-    # then ~/docs/notes would otherwise store notes twice, silently.
     def self.prune(paths)
-      # Sorting by path components puts every descendant right after its
-      # ancestor ("a/b" before "a-x"), so one pass with a stack of accepted
-      # ancestors is enough, however many paths there are.
+      # Sorting by components puts descendants right after their ancestor ("a/b" before "a-x").
       sorted = paths.map { |p| File.expand_path(p) }.uniq.sort_by { |p| p.split("/") }
       kept = []
       stack = []
@@ -56,15 +46,29 @@ module Rakpak
       path.start_with?(dir == "/" ? "/" : "#{dir}/")
     end
 
-    # "none" needs no tool so it is always available; it is the last
-    # resort, not the first pick, when gzip is missing.
+    def self.parse_excludes(text)
+      slash = "/".ord
+      text.split(",").map do |name|
+        name = name.strip
+        finish = name.bytesize
+        finish -= 1 while finish.positive? && name.getbyte(finish - 1) == slash
+        name.byteslice(0, finish)
+      end.reject(&:empty?).uniq
+    end
+
+    # Marked paths are exact, so glob characters in them must not match.
+    def self.literal(path) = path.gsub(/[\\*?\[\]]/) { |c| "\\#{c}" }
+
+    # Only marks strictly inside a packed folder count; a packed item itself is untagged instead.
+    def excluded=(list)
+      @excluded = list.map { |p| File.expand_path(p) }.uniq.sort
+                      .select { |x| @paths.any? { |p| Plan.inside?(x, p) } }
+    end
+
     def tar_codec_fallback
       TAR_CODECS.find { |c| c.bin && c.available? } || Rakpak.tar_codec(:none)
     end
 
-    # One format's knobs behind a uniform face, so the option form does not
-    # need to know whether it is editing tar or compressor settings. Picking
-    # a codec resets the level to that codec's default.
     class Side
       attr_reader :options, :flags
 
@@ -83,7 +87,7 @@ module Rakpak
         @plan.public_send("#{@level_attr}=", v)
       end
 
-      # [label, id, enabled, why] rows for the form's choice list.
+      # [label, id, enabled, why] rows.
       def choices = @plan.public_send(@choices)
 
       def codec=(id)
@@ -103,13 +107,10 @@ module Rakpak
                      flags: @zip_flags, choices: :compress_choices)
     end
 
-    # "both" means compressed, so "none" is not on offer there.
     def tar_choices
       TAR_CODECS.reject { |c| c.id == :none }.map { |c| [c.label, c.id, c.available?, c.why_not] }
     end
 
-    # Single-file compressors only make sense for exactly one file; zip can
-    # take anything.
     def compress_choices
       COMPRESSORS.map do |c|
         ok = c.available? && (c.container? || single_file?)
@@ -120,13 +121,8 @@ module Rakpak
 
     def single_file? = @paths.size == 1 && File.file?(@paths.first)
 
-    # True when the output is a bare compressed file (notes.txt.gz), where
-    # the original name should be kept whole.
     def single_compress? = @target == :zip && !@compressor.container?
 
-    # Deepest directory containing every tagged path. Members are stored
-    # relative to it, so the archive has a sane shape no matter how far
-    # apart the selections were.
     def base
       @base ||= begin
         dirs = @paths.map { |p| File.dirname(p) }
@@ -142,11 +138,11 @@ module Rakpak
       end
     end
 
-    def members
-      @paths.map do |p|
-        rel = p.delete_prefix(base == "/" ? "/" : "#{base}/")
-        rel.empty? ? File.basename(p) : rel
-      end
+    def members = @paths.map { |p| relative(p) }
+
+    def relative(path)
+      rel = path.delete_prefix(base == "/" ? "/" : "#{base}/")
+      rel.empty? ? File.basename(path) : rel
     end
 
     def ext
@@ -160,21 +156,16 @@ module Rakpak
     def output = File.join(@outdir, ensure_ext(@basename, ext))
     def outputs = [output]
 
-    # Nothing to make ready: the destination folder was checked, not created,
-    # and every step writes straight to its final name.
     def prepare; end
     def commit; end
     def rollback; end
 
-    # What the job view calls this work while it runs.
     def gerund = "archiving"
 
-    # One line for the notice when it finishes.
     def outcome
       outputs.map { |o| "#{File.basename(o)} #{Text.bytes(file_size(o))}" }.join(" · ")
     end
 
-    # What follows the path on the line printed to the shell afterwards.
     def report_note = Text.bytes(file_size(output))
 
     def file_size(path)
@@ -183,28 +174,23 @@ module Rakpak
       nil
     end
 
-    # How many members the job should expect, for the progress bar. The
-    # sizer has been counting the selection since it was tagged.
+    # Excluded files are inside the count, so a total would stall the bar; show the count alone.
     def total_members(sizer)
+      return nil if @excludes.any? || @excluded.any?
+
       files = sizer.total(@paths).files
       files.positive? ? files : nil
     end
 
-    # Every step here writes one archive file, and the confirm screen has
-    # said an existing one goes.
     def clobbers_output? = true
 
-    # Extensions a user might type that we would otherwise double up.
     ARCHIVE_EXTS = (TAR_CODECS.map(&:ext) + TAR_CODECS.map(&:single_ext) + %w[.tgz .tbz2 .txz .zip])
                    .reject(&:empty?).uniq.sort_by { |e| -e.length }.freeze
 
     def ensure_ext(name, ext)
       return name if name.downcase.end_with?(ext)
-      # backup.tar gzipped on its own is backup.tar.gz; the name is the
-      # point, so nothing is stripped from it.
       return "#{name}#{ext}" if single_compress?
 
-      # Strip a competing archive extension the user may have typed.
       typed = ARCHIVE_EXTS.find { |e| name.downcase.end_with?(e) }
       stripped = typed ? name[0...-typed.length] : name
       stripped = name if stripped.empty?
@@ -217,10 +203,36 @@ module Rakpak
         argv += ["--use-compress-program", filter]
       end
       @tar_flags.each { |f| argv.concat(f.args) if f.on }
+      argv += tar_exclude_args
       argv += ["-f", output, "-C", base, "--"]
       argv + members
     end
 
+    # Names match at any depth. Marks are anchored: GNU tar takes --anchored, bsdtar a leading ^,
+    # busybox has neither (warnings says so).
+    def tar_exclude_args
+      args = @excludes.map { |n| "--exclude=#{n}" }
+      marked = @excluded.map { |p| Plan.literal(relative(p)) }
+      return args if marked.empty?
+
+      case Tools.tar_flavor
+      when *GNU then args + ["--anchored"] + marked.map { |m| "--exclude=#{m}" }
+      when :bsd then args + marked.map { |m| "--exclude=^#{m}" }
+      else args + marked.map { |m| "--exclude=#{m}" }
+      end
+    end
+
+    # zip matches -x against whole member paths, so a name needs each depth spelled out.
+    def zip_exclude_args
+      names = @excludes.map { |n| zipsafe(n) }.flat_map { |n| [n, "#{n}/*", "*/#{n}", "*/#{n}/*"] }
+      marks = @excluded.map { |p| zipsafe(Plan.literal(relative(p))) }.flat_map { |m| [m, "#{m}/*"] }
+      pats = names + marks
+      pats.empty? ? [] : ["-x", *pats]
+    end
+
+    # zip would read a leading dash as an option; [-] matches the same name.
+    def zipsafe(pat) = pat.start_with?("-") ? "[-]#{pat[1..]}" : pat
+
     def zip_argv
       argv = ["zip", "-r"]
       argv << (zip_verbose? ? "-v" : "-q")
@@ -233,11 +245,9 @@ module Rakpak
         argv.concat(f.args) if f.on
       end
       argv << output
-      argv + members.map { |m| dashsafe(m) }
+      argv + members.map { |m| dashsafe(m) } + zip_exclude_args
     end
 
-    # gzip and friends read one file and write to stdout; the job redirects
-    # that into the output path.
     def single_argv
       @compressor.argv(@comp_level) + [dashsafe(members.first)]
     end
@@ -265,8 +275,7 @@ module Rakpak
       end
     end
 
-    # Display form of the command. Execution never goes through a shell, so
-    # this is for the reader's benefit; quote only what needs it.
+    # Display only; execution never goes through a shell.
     def self.show_arg(arg)
       arg.match?(%r{\A[\w@%+=:,./-]+\z}) ? arg : "'#{arg.gsub("'", %q('"'"'))}'"
     end
@@ -280,7 +289,6 @@ module Rakpak
       steps.map { |(label, argv, _, stdout)| [label, Plan.show_cmd(argv, stdout)] }
     end
 
-    # Problems worth blocking on, checked right before the run.
     def problems
       errs = []
       errs << "nothing selected" if @paths.empty?
@@ -302,7 +310,6 @@ module Rakpak
       errs.compact.uniq
     end
 
-    # Non-blocking things the confirm screen should say out loud.
     def warnings
       warn = []
       o = output
@@ -310,6 +317,14 @@ module Rakpak
       if @paths.any? { |p| Plan.inside?(o, p) }
         warn << "output sits inside a selected folder, so it may archive itself"
       end
+      @paths.each do |p|
+        name = File.basename(p)
+        hit = @excludes.find { |pat| File.fnmatch?(pat, name, File::FNM_DOTMATCH) }
+        warn << "#{name} matches #{hit}, so it is left out entirely" if hit
+      end
+      if @excluded.any? && @target != :zip && Tools.tar_flavor == :busybox
+        warn << "busybox tar cannot pin a mark to one spot; same-named paths deeper in go too"
+      end
       warn
     end
   end

data/lib/rakpak/screen.rb

@@ -4,8 +4,6 @@ require_relative "text"
 require_relative "theme"
 
 module Rakpak
-  # A character grid. Everything draws into cells, so modals overlay the
-  # browser cleanly and the whole frame ships in one write.
   class Screen
     attr_reader :w, :h
 
@@ -25,7 +23,6 @@ module Rakpak
       @st.fill(style)
     end
 
-    # Writes `text` at (x, y). Returns the column just past the text.
     def put(x, y, text, style = nil)
       return x if y.negative? || y >= @h
 
@@ -50,17 +47,14 @@ module Rakpak
       cx
     end
 
-    # A double-width glyph owns two cells: itself and an empty marker after
-    # it. Writing over either half must blank the other, or the row renders
-    # one column too wide and the terminal wraps it.
+    # A wide glyph owns two cells; overwriting either half must blank the other or the row wraps.
     def clear_halves(idx)
       col = idx % @w
       @ch[idx - 1] = " " if @ch[idx] == "" && col.positive? && Text.gw(@ch[idx - 1]) == 2
       @ch[idx + 1] = " " if col < @w - 1 && @ch[idx + 1] == "" && Text.gw(@ch[idx]) == 2
     end
 
-    # Last line of defence: a single binary byte reaching @ch would make the
-    # whole frame fail to concatenate and take the app down mid-render.
+    # One binary byte in @ch would break frame concatenation mid-render.
     def printable(text)
       str = text.to_s
       str = str.dup.force_encoding(Encoding::UTF_8) unless str.encoding == Encoding::UTF_8
@@ -104,8 +98,6 @@ module Rakpak
       end
     end
 
-    # Flatten everything to a faint monochrome so a modal reads as the
-    # foreground layer.
     def veil(style = Theme::FAINT)
       @st.fill(style)
     end

data/lib/rakpak/sizer.rb

@@ -1,12 +1,10 @@
 # frozen_string_literal: true
 
 module Rakpak
-  # Walks tagged directories on a worker thread so the UI can show a real
-  # byte total and file count without ever blocking on a huge tree.
   class Sizer
     Result = Struct.new(:bytes, :files, :partial)
 
-    BUDGET = 4.0 # seconds per path before we report a partial figure
+    BUDGET = 4.0 # seconds per path before reporting a partial figure
 
     def initialize
       @cache = {}
@@ -40,7 +38,6 @@ module Rakpak
       Result.new(bytes, files, known.any?(&:nil?) || known.compact.any?(&:partial))
     end
 
-    # Drops the figure, and any measurement in flight for it.
     def forget(path)
       @lock.synchronize do
         @cache.delete(path)
@@ -60,8 +57,7 @@ module Rakpak
     def work(path, token)
       res = measure(path)
       @lock.synchronize do
-        # Forgotten, invalidated, or re-requested while we were walking:
-        # only the walk that the current request started may answer it.
+        # Only the walk the current request started may answer it.
         next unless @pending[path].equal?(token)
 
         @pending.delete(path)

data/lib/rakpak/term.rb

@@ -3,7 +3,6 @@
 require "io/console"
 
 module Rakpak
-  # Raw-mode terminal control and key decoding.
   module Term
     ARROWS = { "A" => :up, "B" => :down, "C" => :right, "D" => :left,
                "H" => :home, "F" => :end }.freeze
@@ -52,8 +51,7 @@ module Rakpak
       $stdout.flush
     end
 
-    # Blocks up to `timeout` seconds. Returns a key symbol, a printable
-    # String, or nil on timeout.
+    # Returns a key symbol, a printable String, or nil on timeout.
     def wait_key(timeout = nil)
       return nil unless IO.select([$stdin], nil, nil, timeout)
 
@@ -78,10 +76,7 @@ module Rakpak
       end
     end
 
-    # Under a C locale getc yields one byte at a time, and under UTF-8 a
-    # stray byte arrives as a one-byte invalid string. Gather the rest of
-    # the sequence when there is one; if the result is still not valid
-    # text, the key is dropped rather than raised on later.
+    # C locale getc yields single bytes; gather the sequence and drop it if still invalid.
     def complete_utf8(c)
       s = c.dup.force_encoding(Encoding::UTF_8)
       return s if s.valid_encoding?
@@ -109,9 +104,7 @@ module Rakpak
       nil
     end
 
-    # An arrow key arrives as several bytes. Over a slow link they can be
-    # split across reads, so allow a generous window before concluding the
-    # user pressed a bare Esc. The delay is only ever paid on a real Esc.
+    # Escape sequences can split across reads on slow links; only a real Esc pays this wait.
     ESC_WINDOW = 0.05
 
     def read_escape
@@ -139,7 +132,6 @@ module Rakpak
           :esc
         end
       else
-        # Alt-<char>: the whole sequence is the character.
         :"alt_#{seq}"
       end
     end

data/lib/rakpak/text.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 module Rakpak
-  # Grapheme-aware width math. Just enough Unicode to keep columns honest.
   module Text
     WIDE = [
       0x1100..0x115F, 0x2E80..0x303E, 0x3041..0x33FF, 0x3400..0x4DBF,
@@ -14,12 +13,10 @@ module Rakpak
 
     module_function
 
-    # Display width of a single grapheme cluster.
     def gw(cluster)
       cp = cluster.ord
-      return 1 if cp >= 0x20 && cp < 0x7F # the common case, checked first
-      # C0, DEL and the C1 controls: a UTF-8 terminal executes U+009B as
-      # CSI, so these must never reach the frame.
+      return 1 if cp >= 0x20 && cp < 0x7F
+      # C0, DEL and C1: a UTF-8 terminal executes U+009B as CSI.
       return 0 if cp < 0x20 || cp == 0x7F || (cp >= 0x80 && cp <= 0x9F)
       return 0 if ZERO.any? { |r| r.cover?(cp) }
       return 2 if WIDE.any? { |r| r.cover?(cp) }
@@ -35,7 +32,6 @@ module Rakpak
       w
     end
 
-    # Truncate to `max` columns, appending an ellipsis when something was cut.
     def fit(str, max)
       return "" if max <= 0
       return str if width(str) <= max
@@ -52,7 +48,6 @@ module Rakpak
       out << "…"
     end
 
-    # Keep the tail of a path visible instead of the head.
     def fit_left(str, max)
       return "" if max <= 0
       return str if width(str) <= max
@@ -75,7 +70,6 @@ module Rakpak
       w >= max ? str : str + (" " * (max - w))
     end
 
-    # Greedy wrap on spaces, with a hanging indent for continuations.
     def wrap(str, max, indent = 0)
       return [str] if max <= indent + 4 || width(str) <= max
 
@@ -84,7 +78,6 @@ module Rakpak
       out = []
       line = +""
       words = str[lead.length..].to_s.split(" ").flat_map do |word|
-        # A path with no spaces can still be wider than the panel; break it.
         limit = max - indent
         next word if width(word) <= limit || limit < 8
 
@@ -103,7 +96,6 @@ module Rakpak
       out
     end
 
-    # /home/me/x → ~/x. Only a real prefix counts: /home/me2 is left alone.
     def tilde(path)
       home = Dir.home
       return path if home.nil? || home.empty? || home == "/"
@@ -112,8 +104,7 @@ module Rakpak
       path.start_with?("#{home}/") ? "~#{path[home.length..]}" : path
     end
 
-    # For text that goes to the terminal without passing through Screen:
-    # control and C1 bytes could otherwise be executed as escape sequences.
+    # Control and C1 bytes could be executed as escape sequences.
     def plain(str)
       str.to_s.dup.force_encoding(Encoding::UTF_8).scrub("?").gsub(/[\u0000-\u001f\u007f-\u009f]/, "?")
     end

data/lib/rakpak/theme.rb

@@ -1,8 +1,7 @@
 # frozen_string_literal: true
 
 module Rakpak
-  # SGR fragments. Every style is emitted after a reset, so they compose by
-  # concatenation without needing to be self-contained.
+  # Every style is emitted after a reset, so fragments needn't be self-contained.
   module Theme
     RESET     = "\e[0m"
 

data/lib/rakpak/unpack.rb

@@ -5,22 +5,11 @@ require_relative "formats"
 require_relative "plan"
 
 module Rakpak
-  # Turns one archive plus a destination into a command that unpacks it.
-  # Wears the same face as Plan, so Job runs it without knowing which way
-  # round the work goes.
-  #
-  # Three shapes, mirroring the ones Plan writes:
-  #   :tar     tar, decompressing through the codec if there is one
-  #   :zip     unzip
-  #   :single  one compressed file back to one plain file
   class Unpack
-    # An archive shape recognised by extension. `codec` names the TAR_CODECS
-    # entry doing the compression, so the binary probing already done for
-    # packing decides whether this can be read back.
+    # `codec` is a TAR_CODECS id, so packing's binary probing decides readability.
     Shape = Struct.new(:ext, :kind, :codec, keyword_init: true) do
       def tool = kind == :zip ? "unzip" : "tar"
 
-      # The compressor's binary, when one is involved.
       def bin = codec && Rakpak.tar_codec(codec)&.bin
     end
 
@@ -47,7 +36,6 @@ module Rakpak
       Shape.new(ext: ".br",      kind: :single, codec: :brotli)
     ].sort_by { |s| -s.ext.length }.freeze
 
-    # nil when the name carries no extension we know how to open.
     def self.format(path)
       name = File.basename(path.to_s).downcase
       SHAPES.find { |s| name.end_with?(s.ext) && name.length > s.ext.length }
@@ -55,9 +43,7 @@ module Rakpak
 
     def self.archive?(path) = !format(path).nil?
 
-    # "notes.tar.gz" -> "notes"; the whole archive extension goes. A name that
-    # leaves nothing, "." or ".." behind would resolve to the destination's
-    # parent once joined, so those keep the whole basename instead.
+    # A name reducing to "", "." or ".." would resolve to the parent, so keep the whole basename.
     def self.strip_ext(path)
       name = File.basename(path.to_s)
       shape = format(path)
@@ -65,13 +51,10 @@ module Rakpak
       ["", ".", ".."].include?(stripped) ? name : stripped
     end
 
-    # The folder to make for the contents, or nil when the archive holds a
-    # single file that should land beside you.
     def self.default_subdir(path)
       format(path)&.kind == :single ? nil : strip_ext(path)
     end
 
-    # What a lone compressed file decompresses back into.
     def self.member_name(path) = strip_ext(path)
 
     attr_reader :archive, :shape
@@ -86,22 +69,17 @@ module Rakpak
     def kind = @shape&.kind
     def single? = kind == :single
 
-    # Job chdirs here, so it has to exist by the time the first step runs.
+    # Job chdirs here, so it must exist before the first step runs.
     def base = @dest
 
-    # A tarball or zip pours its members into the folder; a lone compressed
-    # file has one real output, and Job may replace that.
     def outputs = [single? ? File.join(@dest, Unpack.member_name(@archive)) : @dest]
     def output = outputs.first
     def clobbers_output? = single?
 
-    # The decompressor's output is opened for writing before it has read a
-    # single byte of the archive, so it cannot be aimed at the file it is
-    # meant to replace. It writes here and is renamed over the top on success.
+    # Output is opened before the archive is read, so write here and rename over on success.
     def scratch = File.join(@dest, ".#{Unpack.member_name(@archive)}.part")
 
     def prepare
-      # Remember what we make, so a failure can leave the tree as it was.
       @made = []
       dir = @dest
       until File.directory?(dir) || dir == "/"
@@ -111,13 +89,11 @@ module Rakpak
       FileUtils.mkdir_p(@dest)
     end
 
-    # Every step succeeded, so the recovered file may take its real name.
     def commit
       File.rename(scratch, output) if single? && File.exist?(scratch)
     end
 
-    # Folders we created and never filled are ours to take back; anything that
-    # was already on disk, or anything the run managed to write, stays.
+    # Remove only folders we created that stayed empty.
     def rollback
       (@made || []).each do |dir|
         Dir.rmdir(dir) if File.directory?(dir) && Dir.empty?(dir)
@@ -126,14 +102,11 @@ module Rakpak
       end
     end
 
-    # Counting an archive's members means decompressing the whole thing
-    # first, which is most of the work. The job counts up as it goes instead.
+    # Counting members would mean decompressing the whole archive first.
     def total_members(_sizer) = nil
 
     def gerund = "unpacking"
 
-    # A recovered lone file can be weighed. A folder of members has no useful
-    # size of its own, so it reports what happened instead.
     def outcome
       return "#{File.basename(output)} #{Text.bytes(file_size(output))}" if single?
 
@@ -150,17 +123,13 @@ module Rakpak
 
     def tar_argv
       argv = ["tar", "-x", "-v"]
-      # Reading an archive, tar runs the program with -d appended, so this is
-      # the bare binary. Adding our own -d makes brotli refuse the command as
-      # already set; the other five ignore the repeat.
-      argv += ["--use-compress-program", @shape.bin] if @shape.bin
+      # GNU tar appends -d when reading (brotli refuses a repeated -d); bsdtar runs the string as given.
+      argv += ["--use-compress-program", Tools.tar_flavor == :bsd ? "#{@shape.bin} -d" : @shape.bin] if @shape.bin
       argv + ["-f", @archive, "-C", @dest]
     end
 
     def zip_argv = ["unzip", "-o", @archive, "-d", @dest]
 
-    # The compressor reading the archive and writing the plain file to
-    # stdout, which Job points at the output path.
     def single_argv = [@shape.bin, "-dc", @archive]
 
     # [label, argv, expects_verbose_output, stdout_path]
@@ -182,8 +151,6 @@ module Rakpak
     # GNU tar and bsdtar can hand the stream to a compressor; busybox cannot.
     def tar_pipes? = Tools.tar_pipes?
 
-    # Every tool this run needs, so a half-installed machine is caught on
-    # the confirm screen rather than partway through the extraction.
     def tools = [@shape&.kind == :single ? nil : @shape&.tool, @shape&.bin].compact
 
     def problems
@@ -200,8 +167,7 @@ module Rakpak
       end
       # mkdir_p would raise EEXIST partway through the run; say it up front.
       errs << "not a folder: #{@dest}" if File.exist?(@dest) && !File.directory?(@dest)
-      # A folder can be writable and still refuse to be listed, which tar
-      # needs to do to avoid clobbering, and which warnings needs to read.
+      # tar needs to list the folder to avoid clobbering.
       if File.directory?(@dest) && !File.readable?(@dest)
         errs << "destination is not readable: #{@dest}"
       end
@@ -210,8 +176,6 @@ module Rakpak
       errs.uniq
     end
 
-    # Nothing is created until the job runs, so writability is a question
-    # about the nearest folder that already exists.
     def existing_parent(dir)
       dir = File.dirname(dir) until File.directory?(dir) || dir == "/"
       dir
@@ -227,8 +191,7 @@ module Rakpak
       warn
     end
 
-    # An unlistable folder is reported by problems; there is nothing to warn
-    # about and this must not raise, since the confirm screen draws it.
+    # Must not raise: the confirm screen calls this while drawing.
     def empty_dir?(dir)
       Dir.children(dir).empty?
     rescue StandardError

data/lib/rakpak/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Rakpak
-  VERSION = "1.1.0"
+  VERSION = "1.2.0"
 end