rakpak 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5bddb74dac931f5f6744b5a1c820c1f5452b3f938e3b3a1e928157926c40ce45
-  data.tar.gz: b4391576a37aa27785f58ddc5ed24237f6f346b67b252d9fb4537f2a1a122406
+  metadata.gz: 98de68901620153b4b19a5ff3ccf6b9757f8e718db3a4bcef3d70b81b75e5a76
+  data.tar.gz: 5b7a9592e10e1b4181d4ba5aceaba0dc8fc70e6b3286f6660e4e10cdc9b4c287
 SHA512:
-  metadata.gz: 93794a7b3228f6b4064880ebdc637a12194c7eac375e27a5daa3b102dedbdf42fefc998ad9e8854fa22f0393e85c0e590757e1ef8ceb562655920ce4a6a721a6
-  data.tar.gz: '049724035061aa5da75235a1424cbc3927bd24e8738c01c85a4ee60810ffff738f9976a307424086eb41a04f7a804ff1bca0d06f79a73bbd9ae71085f30feabe'
+  metadata.gz: 544d49d201309db5d5d90fb692f78e7e103280b06f7373ad872f21cc90374763c650da2f02fb5f006303e7dbd296df8d32f2f6d8eb7924b096d15d3960c5ef8b
+  data.tar.gz: 802d440f759bf5648199f07e6b98b934eda43e94b08133cdb3c07da9bed16b900cb2c0456c436ef9f2932bc4a3bcc26dbdd70b6c13b31722007864ee622c047f

data/README.md

@@ -1,10 +1,20 @@
-# rakpak
+<p align="center">
+  <img src="https://res.cloudinary.com/noqoikpl/image/upload/f_auto,q_auto/rakpak-upper" alt="rakpak" width="520">
+</p>
 
-Tag files and folders anywhere on your filesystem, then archive them all at once.
+<p align="center">
+  <a href="https://github.com/eof0/rakpak/actions/workflows/ci.yml"><img src="https://github.com/eof0/rakpak/actions/workflows/ci.yml/badge.svg" alt="tests"></a>
+  <a href="https://rubygems.org/gems/rakpak"><img src="https://img.shields.io/gem/v/rakpak" alt="gem version"></a>
+  <a href="https://rubygems.org/gems/rakpak"><img src="https://img.shields.io/gem/dt/rakpak" alt="downloads"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/github/license/eof0/rakpak" alt="license"></a>
+</p>
+
+<p align="center">Tag files and folders anywhere on your filesystem, then archive them all at once, or unpack one you already have.</p>
 
 You walk around, press `space` on anything you want, press `p`, answer a few
 questions, and it builds the archive. The progress view can be sent to the
-background while you keep browsing.
+background while you keep browsing. Press `u` on an archive instead and it
+unpacks, wherever you want it.
 
 Needs Ruby 3.0 or newer and nothing else.
 
@@ -30,6 +40,8 @@ rakpak ~/Documents        browse from there instead
 rakpak .                  browse from the current folder
 rakpak -p ~/Documents     pack that folder: opens on the archive prompts
 rakpak -p a.txt b/ c      pack several things at once
+rakpak -d site.tar.gz     unpack it here and now, into site/
+rakpak -d a.tgz b.zip     unpack several, each into its own folder
 ```
 
 ## Starting up
@@ -44,6 +56,13 @@ it, and the archive prompts appear at once, starting with the kind of archive
 and its compression. The archive is written next to that first path. Press
 `esc` on any prompt and you are back in the browser with the tags still set.
 
+`-d` (or `--depack`) does not open the browser at all. Each archive is
+unpacked straight into the folder you are standing in, the way `tar` would,
+each one into a folder of its own name: `site.tar.gz` gives you `site/`.
+A lone compressed file has nothing to wrap, so `notes.txt.gz` lands
+beside you as `notes.txt`. One bad archive does not stop the rest, and the
+exit status is non-zero if any of them failed.
+
 ## The flow
 
 1. **Browse and tag.** Vim keys or arrows. `space` tags whatever is under the
@@ -67,6 +86,24 @@ and its compression. The archive is written next to that first path. Press
 
 If nothing is tagged, `p` archives whatever the cursor is on.
 
+## Unpacking
+
+`u` on an archive opens three prompts: which folder to unpack into, what to
+call the folder it makes there, and the usual confirm screen showing the
+exact command.
+
+Unlike `p`, this follows the cursor rather than the tag set: one archive, one
+destination. The folder is offered as the archive's own name with the
+extension taken off, so `site.tar.gz` suggests `site/`, which means nothing
+is ever sprayed across the folder you are standing in. Type `.` as
+the name to unpack straight into the folder you picked instead, and the
+folder prompt takes `~`, `$HOME` and any absolute path, so the contents can
+go anywhere. A lone compressed file skips the folder entirely.
+
+If the destination already has files in it, the confirm screen says so before
+anything runs. A failed extraction leaves whatever it managed to write; the
+files that were already there are never touched.
+
 ## Keys
 
 | | |
@@ -86,6 +123,7 @@ If nothing is tagged, `p` archives whatever the cursor is on.
 | `.` | show hidden files |
 | `ctrl-r` | reload |
 | `p` | pack: archive what is tagged |
+| `u` | unpack the archive under the cursor |
 | `b` | watch a running job |
 | `?` | all keys |
 | `q` | quit |
@@ -110,9 +148,16 @@ here too, so `notes.txt` becomes `notes.txt.gz` or `notes.txt.zst` without a
 tarball around it. For a folder those are greyed out with the reason, since
 `gzip` alone cannot take a folder.
 
+Every one of those can be read back: `.tar`, `.tar.gz`, `.tar.zst`, `.tar.xz`,
+`.tar.bz2`, `.tar.lz4`, `.tar.br`, the `.tgz`, `.tzst`, `.txz` and `.tbz2`
+short forms, `.zip` via `unzip`, and `.gz`, `.zst`, `.xz`, `.bz2`, `.lz4` or
+`.br` on their own.
+
 Everything is probed at startup: `PATH` for the compressors, `tar --version` to
 tell GNU tar from bsdtar from busybox, and `zip -v` for its compiled-in methods.
 Anything that will not work on this machine is greyed out with the reason.
+Unpacking a `.zip` wants `unzip`, which is a different program from the `zip`
+used to write one, so it is checked on its own.
 
 ## How the archive is shaped
 
@@ -124,7 +169,10 @@ archive holds `a/b` and `c`.
 
 - Commands are run directly, not in a shell. Filenames containing spaces,
   quotes, `$`, `;` or a leading `-` are safe.
-- Cancelling kills the whole process group, so the compressor goes too.
+- Cancelling kills the whole process group, so the compressor goes too. A
+  cancelled pack removes its half-written archive; a cancelled unpack leaves
+  the files it had already extracted, since deleting a folder is not
+  rakpak's call to make.
 - Folder sizes are counted in the background. A folder too large to finish
   counting in a few seconds shows `≥`, meaning the real size is at least that.
 

data/lib/rakpak/app.rb

@@ -6,6 +6,7 @@ require_relative "browser"
 require_relative "modal"
 require_relative "formats"
 require_relative "plan"
+require_relative "unpack"
 require_relative "job"
 require_relative "sizer"
 
@@ -63,6 +64,7 @@ module Rakpak
   class App
     SPINNER = "⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏"
     WIZARD = %i[target options where output confirm].freeze
+    UNPACK = %i[dest_where dest_name unpack_confirm].freeze
 
     # `pack` is a list of paths to tag before the first frame; when it is
     # non-empty the archive prompts open immediately (rakpak -p).
@@ -81,6 +83,7 @@ module Rakpak
       @notice = nil
       @notice_until = nil
       @plan = nil
+      @wizard = WIZARD
       @wizard_pos = nil
       @quit = false
       return if pack.empty?
@@ -194,24 +197,30 @@ module Rakpak
       @screen.put([(@screen.w - Text.width(want)) / 2, 0].max, (@screen.h / 2) + 1, want, Theme::DIM)
     end
 
+    # Only the running state says which direction the work goes; the rest
+    # read the same either way.
+    def job_title(job, state)
+      case state
+      when :running then job.plan.gerund
+      when :done then "finished"
+      when :failed then "failed"
+      when :cancelled then "cancelled"
+      else "queued"
+      end
+    end
+
     def draw_job(job)
       s = @screen
       s.fill(0, 0, s.w, 1, " ", Theme::HEAD)
-      title = case job.state
-              when :running then "archiving"
-              when :done then "finished"
-              when :failed then "failed"
-              when :cancelled then "cancelled"
-              else "queued"
-              end
       s.put(1, 0, "rakpak", Theme::HEAD + "\e[1;38;5;39m")
-      s.put(9, 0, title, Theme::HEAD + "\e[38;5;231m")
+      s.put(9, 0, job_title(job, job.state), Theme::HEAD + "\e[38;5;231m")
       s.put(s.w - 20, 0, Text.duration(job.elapsed), Theme::HEAD + Theme::DIM)
 
       y = 2
       job.plan.outputs.each do |out|
+        # A folder being extracted into has no size worth showing.
         size = begin
-          File.size(out)
+          File.directory?(out) ? nil : File.size(out)
         rescue StandardError
           nil
         end
@@ -287,6 +296,7 @@ module Rakpak
       case @browser.handle(key)
       when :quit then request_quit
       when :archive then start_wizard
+      when :unpack then start_unpack
       when :tags then open_tags
       when :help then open_help
       when :jobs then open_jobs
@@ -351,6 +361,32 @@ module Rakpak
       @name_edited = false
       @where = 0
       @where_text = ""
+      @wizard = WIZARD
+      @wizard_pos = 0
+      open_wizard_step
+    end
+
+    # Unpacking follows the cursor rather than the tag set: an archive is one
+    # thing with one destination, not a pile to gather up.
+    def start_unpack
+      e = @browser.current
+      unless e && File.file?(e.path) && Unpack.archive?(e.path)
+        @modal = MessageModal.new(
+          title: "not an archive",
+          lines: ["rakpak unpacks tarballs, zips and single",
+                  "compressed files: .tar, .tar.gz, .tar.zst,",
+                  ".tar.xz, .tar.bz2, .tar.lz4, .tar.br, .zip,",
+                  "and .gz, .zst, .xz, .bz2, .lz4, .br on their own."],
+          style: Theme::WARN
+        )
+        return
+      end
+      @plan = Unpack.new(archive: e.path, dest: @browser.cwd)
+      @dest_parent = @browser.cwd
+      @dest_name = Unpack.default_subdir(e.path) || "."
+      @where = 0
+      @where_text = ""
+      @wizard = UNPACK
       @wizard_pos = 0
       open_wizard_step
     end
@@ -369,7 +405,7 @@ module Rakpak
 
     def open_wizard_step
       loop do
-        step = WIZARD[@wizard_pos]
+        step = @wizard[@wizard_pos]
         return finish_wizard if step.nil?
 
         modal = build_step(step)
@@ -383,7 +419,7 @@ module Rakpak
     end
 
     def wizard_forward(modal)
-      apply_step(WIZARD[@wizard_pos], modal)
+      apply_step(@wizard[@wizard_pos], modal)
       return if @wizard_pos.nil? # a step may have ended the wizard itself
 
       @wizard_pos += 1
@@ -398,7 +434,7 @@ module Rakpak
           @plan = nil
           return
         end
-        modal = build_step(WIZARD[@wizard_pos])
+        modal = build_step(@wizard[@wizard_pos])
         next if modal.nil?
 
         @modal = modal
@@ -413,6 +449,9 @@ module Rakpak
       when :where then where_modal
       when :output then output_modal
       when :confirm then confirm_modal
+      when :dest_where then dest_where_modal
+      when :dest_name then dest_name_modal
+      when :unpack_confirm then unpack_confirm_modal
       end
     end
 
@@ -429,6 +468,15 @@ module Rakpak
         @name_edited = true
         @plan.basename = modal.result
       when :confirm then launch
+      when :dest_where
+        @where = modal.index
+        @where_text = modal.text
+        @dest_parent = @where == 2 ? Rakpak.expand_dir(modal.result) : modal.result
+        sync_dest
+      when :dest_name
+        @dest_name = modal.result
+        sync_dest
+      when :unpack_confirm then launch
       end
     end
 
@@ -494,14 +542,57 @@ module Rakpak
 
     def where_modal
       WhereModal.new(here: @browser.cwd, home: Dir.home, index: @where, text: @where_text,
-                     validate: lambda { |text|
-                       d = Rakpak.expand_dir(text)
-                       if !File.directory?(d) then "not a folder: #{d}"
-                       elsif !File.writable?(d) then "not writable: #{d}"
+                     validate: method(:writable_folder))
+    end
+
+    def writable_folder(text)
+      d = Rakpak.expand_dir(text)
+      if !File.directory?(d) then "not a folder: #{d}"
+      elsif !File.writable?(d) then "not writable: #{d}"
+      end
+    end
+
+    def dest_where_modal
+      WhereModal.new(here: @browser.cwd, home: Dir.home, index: @where, text: @where_text,
+                     validate: method(:writable_folder), title: "unpack it where?")
+    end
+
+    # nil when there is no folder to name, which open_wizard_step skips over.
+    def dest_name_modal
+      return nil if @plan.single?
+
+      InputModal.new(title: "unpack into",
+                     value: @dest_name,
+                     hint: "a new folder in #{Text.tilde(@dest_parent)}  ·  . unpacks straight in",
+                     validate: lambda { |name|
+                       # The folder was chosen on the previous screen, so this
+                       # is a bare name and can never reach outside it.
+                       if name.include?("/") then "just a name, no slashes; the folder was picked already"
+                       elsif name.include?("\0") || name == ".." then "not a valid name"
                        end
                      })
     end
 
+    # "." is how you say "no subfolder, straight into the folder I picked",
+    # and a lone compressed file never has one to begin with.
+    def sync_dest
+      @plan.dest = @dest_name == "." ? @dest_parent : File.join(@dest_parent, @dest_name)
+    end
+
+    def unpack_confirm_modal
+      lines = [[:head, "unpacks #{Text.tilde(@plan.archive)}"],
+               [:key, ""],
+               [:head, "into #{Text.tilde(@plan.dest)}"],
+               [:key, ""]]
+      @plan.preview.each do |label, cmd|
+        lines << [:head, "#{label}:"]
+        lines << [:cmd, "   #{cmd}"]
+      end
+      lines << [:key, ""]
+      ConfirmModal.new(title: "ready", lines: lines,
+                       warnings: @plan.warnings, errors: @plan.problems)
+    end
+
     def output_modal
       @plan.basename = default_basename(@plan.paths) unless @name_edited
       InputModal.new(title: "output name",
@@ -540,8 +631,7 @@ module Rakpak
 
     # Always opens the job view; b from there sends it to the background.
     def launch
-      total = @sizer.total(@plan.paths)
-      job = Job.new(@plan, total_files: total.files.positive? ? total.files : nil).start
+      job = Job.new(@plan, total_files: @plan.total_members(@sizer)).start
       @jobs << job
       @focus_job = job
       @wizard_pos = nil
@@ -557,9 +647,7 @@ module Rakpak
         next if @mode == :job && @focus_job == j
 
         case j.state
-        when :done
-          sizes = j.summary.map { |n, sz| "#{n} #{Text.bytes(sz)}" }.join(" · ")
-          notify("✓ #{sizes}", Theme::OK, 8)
+        when :done then notify("✓ #{j.plan.outcome}", Theme::OK, 8)
         when :failed then notify("✗ #{j.error}", Theme::ERR, 10)
         when :cancelled then notify("cancelled", Theme::WARN)
         end
@@ -597,6 +685,7 @@ module Rakpak
         ["/", "filter this folder"], [".", "show hidden"],
         ["ctrl-r", "reload"],
         ["p", "pack: archive the tagged items"],
+        ["u", "unpack the archive under the cursor"],
         ["b", "watch running jobs"], ["q", "quit"]
       ]
       w = keys.map { |k, _| Text.width(k) }.max
@@ -627,7 +716,7 @@ module Rakpak
       done.each do |j|
         # Printed after the TUI has gone, straight to the shell, so a folder
         # or file name carrying an escape sequence must be defanged.
-        j.summary.each { |name, size| puts "#{Text.plain(File.join(j.plan.outdir, name))}  #{Text.bytes(size)}" }
+        puts "#{Text.plain(j.plan.outputs.first)}  #{Text.plain(j.plan.report_note)}"
       end
     end
   end

data/lib/rakpak/browser.rb

@@ -159,7 +159,7 @@ module Rakpak
       !idx.nil?
     end
 
-    # Returns :quit, :archive, :tags, :help, :jobs or nil.
+    # Returns :quit, :archive, :unpack, :tags, :help, :jobs or nil.
     def handle(key)
       return handle_filter(key) if @filtering
 
@@ -197,12 +197,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
@@ -487,7 +488,7 @@ module Rakpak
     end
 
     HINTS = [["space", "tag"], ["←→", "nav"], ["a", "all"], ["t", "queue"], ["/", "find"],
-             [".", "hidden"], ["p", "pack"], ["?", "help"]].freeze
+             [".", "hidden"], ["p", "pack"], ["u", "unpack"], ["?", "help"]].freeze
 
     def draw_footer(screen, y, status_line)
       screen.fill(0, y, screen.w, 1, " ", nil)

data/lib/rakpak/job.rb

@@ -67,16 +67,24 @@ 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.
+    # 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.
     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
 
+    # 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]
+    end
+
     def summary
       @plan.outputs.map do |o|
         size = begin
@@ -132,6 +140,7 @@ module Rakpak
     end
 
     def run_all
+      @plan.prepare
       @steps.each_with_index do |(label, argv, verbose, stdout), idx|
         @step_index = idx
         @file_count = 0
@@ -149,6 +158,7 @@ module Rakpak
         end
         @spawned = nil
       end
+      @plan.commit
       finish(:done)
     rescue StandardError => e
       @error = "#{e.class}: #{e.message}"
@@ -169,7 +179,10 @@ 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
@@ -178,7 +191,13 @@ module Rakpak
     # 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.
     def cleanup_incomplete
+      return unless @plan.clobbers_output?
+
       path = @spawned
       return unless path && File.exist?(path)
 
@@ -191,25 +210,31 @@ module Rakpak
     # `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]
+      # 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.
+      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
@@ -244,6 +269,32 @@ 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.
+    def clear_path(path)
+      return unless path
+
+      st = begin
+        File.lstat(path)
+      rescue StandardError
+        return
+      end
+      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.
+    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.
+    def open_sink(path) = File.open(path, SINK_FLAGS, 0o666)
+
     def record(line)
       return if line.empty?
 

data/lib/rakpak/modal.rb

@@ -364,8 +364,8 @@ module Rakpak
   class WhereModal < Modal
     attr_reader :index
 
-    def initialize(here:, home:, index: 0, text: "", validate: nil)
-      super(title: "save it where?", footer: "1-3 or ↑↓ pick · enter choose · esc back")
+    def initialize(here:, home:, index: 0, text: "", validate: nil, title: "save it where?")
+      super(title: title, footer: "1-3 or ↑↓ pick · enter choose · esc back")
       @choices = [["This directory", here], ["Home directory", home], ["Specify", nil]]
       @index = index
       @field = InputModal.new(title: "", value: text, validate: validate)

data/lib/rakpak/plan.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "formats"
+require_relative "text"
 
 module Rakpak
   # Turns a set of tagged paths plus the wizard's answers into one concrete
@@ -159,6 +160,40 @@ 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)
+      File.size(path)
+    rescue StandardError
+      nil
+    end
+
+    # How many members the job should expect, for the progress bar. The
+    # sizer has been counting the selection since it was tagged.
+    def total_members(sizer)
+      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

data/lib/rakpak/unpack.rb

@@ -0,0 +1,238 @@
+# frozen_string_literal: true
+
+require "fileutils"
+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.
+    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
+
+    # Longest extension first, so notes.tar.gz never reads as a bare .gz.
+    SHAPES = [
+      Shape.new(ext: ".tar",     kind: :tar),
+      Shape.new(ext: ".tar.gz",  kind: :tar, codec: :gzip),
+      Shape.new(ext: ".tar.zst", kind: :tar, codec: :zstd),
+      Shape.new(ext: ".tar.xz",  kind: :tar, codec: :xz),
+      Shape.new(ext: ".tar.bz2", kind: :tar, codec: :bzip2),
+      Shape.new(ext: ".tar.lz4", kind: :tar, codec: :lz4),
+      Shape.new(ext: ".tar.br",  kind: :tar, codec: :brotli),
+      Shape.new(ext: ".tgz",     kind: :tar, codec: :gzip),
+      Shape.new(ext: ".tzst",    kind: :tar, codec: :zstd),
+      Shape.new(ext: ".txz",     kind: :tar, codec: :xz),
+      Shape.new(ext: ".tbz2",    kind: :tar, codec: :bzip2),
+      Shape.new(ext: ".tbz",     kind: :tar, codec: :bzip2),
+      Shape.new(ext: ".zip",     kind: :zip),
+      Shape.new(ext: ".gz",      kind: :single, codec: :gzip),
+      Shape.new(ext: ".zst",     kind: :single, codec: :zstd),
+      Shape.new(ext: ".xz",      kind: :single, codec: :xz),
+      Shape.new(ext: ".bz2",     kind: :single, codec: :bzip2),
+      Shape.new(ext: ".lz4",     kind: :single, codec: :lz4),
+      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 }
+    end
+
+    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.
+    def self.strip_ext(path)
+      name = File.basename(path.to_s)
+      shape = format(path)
+      stripped = shape ? name[0...-shape.ext.length] : name
+      ["", ".", ".."].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
+    attr_accessor :dest
+
+    def initialize(archive:, dest:)
+      @archive = File.expand_path(archive)
+      @dest = File.expand_path(dest)
+      @shape = Unpack.format(@archive)
+    end
+
+    def kind = @shape&.kind
+    def single? = kind == :single
+
+    # Job chdirs here, so it has to exist by the time 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.
+    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 == "/"
+        @made << dir
+        dir = File.dirname(dir)
+      end
+      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.
+    def rollback
+      (@made || []).each do |dir|
+        Dir.rmdir(dir) if File.directory?(dir) && Dir.empty?(dir)
+      rescue StandardError
+        nil
+      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.
+    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?
+
+      "unpacked into #{File.basename(@dest)}/"
+    end
+
+    def report_note = single? ? Text.bytes(file_size(output)) : "unpacked"
+
+    def file_size(path)
+      File.size(path)
+    rescue StandardError
+      nil
+    end
+
+    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
+      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]
+    def steps
+      case kind
+      when :tar then [["tar", tar_argv, true, nil]]
+      when :zip then [["unzip", zip_argv, true, nil]]
+      when :single then [[@shape.bin, single_argv, false, scratch]]
+      else []
+      end
+    end
+
+    def preview
+      steps.map { |(label, argv, _, stdout)| [label, Plan.show_cmd(argv, stdout)] }
+    end
+
+    def missing?(bin) = !Tools.available?(bin)
+
+    # 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
+      return ["not an archive rakpak knows how to open: #{File.basename(@archive)}"] if @shape.nil?
+
+      errs = []
+      if !File.exist?(@archive) then errs << "no such file: #{@archive}"
+      elsif !File.file?(@archive) then errs << "not a file: #{@archive}"
+      elsif !File.readable?(@archive) then errs << "not readable: #{@archive}"
+      end
+      tools.each { |bin| errs << "#{bin} not installed" if missing?(bin) }
+      if kind == :tar && @shape.bin && !tar_pipes?
+        errs << "this tar cannot pipe through #{@shape.bin}"
+      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.
+      if File.directory?(@dest) && !File.readable?(@dest)
+        errs << "destination is not readable: #{@dest}"
+      end
+      parent = existing_parent(@dest)
+      errs << "destination is not writable: #{parent}" unless File.writable?(parent)
+      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
+    end
+
+    def warnings
+      warn = []
+      if single?
+        warn << "#{Unpack.member_name(@archive)} already exists and will be replaced" if File.exist?(output)
+      elsif File.directory?(@dest) && !empty_dir?(@dest)
+        warn << "#{File.basename(@dest)} already has files in it; matching names will be replaced"
+      end
+      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.
+    def empty_dir?(dir)
+      Dir.children(dir).empty?
+    rescue StandardError
+      true
+    end
+  end
+end

data/lib/rakpak/version.rb

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

data/lib/rakpak.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "rakpak/version"
+require_relative "rakpak/unpack"
 require_relative "rakpak/app"
 
 module Rakpak
@@ -9,20 +10,23 @@ module Rakpak
 
     usage: rakpak [folder]
            rakpak -p path [path ...]
+           rakpak -d archive [archive ...]
 
       folder         start browsing there (default: your home folder)
       -p, --pack     tag the given files or folders and go straight to the
                      archive prompts, starting with the kind of compression
+      -d, --depack   unpack the archives here and now, no browsing: each one
+                     into a folder of its own name in the current folder
       -h, --help     this text
       -v, --version  print the version
 
       space      tag / untag       p    pack what is tagged
-      h l ← →   navigate           /    filter      .  hidden
-      enter      enter folder       T    review tags
-      ?          all keys           q    quit
+      h l ← →   navigate           u    unpack what the cursor is on
+      enter      enter folder       /    filter      .  hidden
+      ?          all keys           T    review tags       q  quit
   USAGE
 
-  Options = Struct.new(:dir, :pack, :action, keyword_init: true)
+  Options = Struct.new(:dir, :pack, :unpack, :action, keyword_init: true)
 
   # A folder as a person would type it: ~, ~/x, $HOME/x, ${HOME}/x, or an
   # absolute or relative path.
@@ -35,10 +39,11 @@ module Rakpak
     text # ~nosuchuser and the like; the caller reports it is not a folder
   end
 
-  # Returns Options. `action` is :browse, :help or :version. Raises
+  # Returns Options. `action` is :browse, :unpack, :help or :version. Raises
   # ArgumentError on anything it does not understand.
   def self.parse(argv)
     pack_mode = false
+    depack_mode = false
     positional = []
     rest = argv.dup
     until rest.empty?
@@ -47,12 +52,28 @@ module Rakpak
       when "-h", "--help" then return Options.new(action: :help)
       when "-v", "--version" then return Options.new(action: :version)
       when "-p", "--pack" then pack_mode = true
+      when "-d", "--depack", "--unpack" then depack_mode = true
       when "--" then positional.concat(rest) && rest.clear
       when /\A-./ then raise ArgumentError, "unknown option: #{arg}"
       else positional << arg
       end
     end
 
+    raise ArgumentError, "-p and -d do different things; pick one" if pack_mode && depack_mode
+
+    if depack_mode
+      raise ArgumentError, "-d needs at least one archive" if positional.empty?
+
+      paths = positional.map { |p| File.expand_path(p) }
+      paths.each do |p|
+        raise ArgumentError, "no such file: #{p}" unless File.exist?(p)
+        unless File.file?(p) && Unpack.archive?(p)
+          raise ArgumentError, "not an archive rakpak knows how to open: #{File.basename(p)}"
+        end
+      end
+      return Options.new(action: :unpack, unpack: paths, pack: [])
+    end
+
     if pack_mode
       raise ArgumentError, "-p needs at least one path" if positional.empty?
 
@@ -62,15 +83,78 @@ module Rakpak
       end
       # Open the browser on the folder holding the first target, with that
       # target under the cursor, so the archive lands next to it.
-      Options.new(action: :browse, dir: File.dirname(paths.first), pack: paths)
+      Options.new(action: :browse, dir: File.dirname(paths.first), pack: paths, unpack: [])
     else
       raise ArgumentError, "expected one folder, got #{positional.size}" if positional.size > 1
 
       dir = File.expand_path(positional.first || Dir.home)
       raise ArgumentError, "not a folder: #{dir}" unless File.directory?(dir)
 
-      Options.new(action: :browse, dir: dir, pack: [])
+      Options.new(action: :browse, dir: dir, pack: [], unpack: [])
+    end
+  end
+
+  # Unpacks each archive into the folder you are standing in, the way tar
+  # would, each into a folder of its own name. A lone compressed file has
+  # nothing to wrap, so it lands beside you. Returns an exit status;
+  # one bad archive does not stop the rest.
+  def self.unpack_all(archives, dir: Dir.pwd, out: $stdout)
+    status = 0
+    archives.each do |archive|
+      sub = Unpack.default_subdir(archive)
+      plan = Unpack.new(archive: archive, dest: sub ? File.join(dir, sub) : dir)
+      problems = plan.problems
+      if problems.any?
+        problems.each { |m| warn "rakpak: #{m}" }
+        status = 1
+        next
+      end
+      out.puts "#{Text.plain(File.basename(archive))} → #{Text.plain(Text.tilde(plan.dest))}"
+      plan.warnings.each { |w| out.puts "  #{w}" }
+      # Anything the job says goes to stderr; keep the two streams in order.
+      out.flush
+      status = 1 unless run_headless(plan, out)
+    end
+    status
+  rescue Interrupt
+    130
+  end
+
+  # True when it worked. On a terminal the count is rewritten in place; down
+  # a pipe only the closing line is written, so logs stay readable.
+  #
+  # The extractor runs in its own process group so a cancel can take its whole
+  # pipeline, which also means the terminal's ctrl-c never reaches it. Catching
+  # the interrupt here is what stops tar carrying on without us.
+  def self.run_headless(plan, out)
+    job = Job.new(plan).start
+    live = out.respond_to?(:tty?) && out.tty?
+    begin
+      while job.running?
+        job.wait(0.1)
+        next unless live
+
+        out.print "\r  #{job.file_count} entries · #{Text.duration(job.elapsed)}\e[K"
+        out.flush
+      end
+    rescue Interrupt
+      out.print "\r\e[K" if live
+      job.cancel
+      job.wait(5)
+      warn "rakpak: cancelled"
+      raise
+    end
+    out.print "\r\e[K" if live
+    unless job.ok?
+      warn "rakpak: #{job.error}"
+      # The exit status says a tool failed; its own last words say why.
+      # Member names come from inside the archive, so they reach the shell
+      # defanged, the way the finished-job report does.
+      job.tail(4).each { |line| warn "  #{Text.plain(line)}" unless line.start_with?("▸") }
+      return false
     end
+    out.puts "  #{job.file_count} entries · #{Text.duration(job.elapsed)} · #{plan.report_note}"
+    true
   end
 
   # Exit status.
@@ -89,6 +173,9 @@ module Rakpak
     when :version
       puts "rakpak #{VERSION}"
       return 0
+    when :unpack
+      # Nothing to browse and nothing to ask, so this works down a pipe.
+      return unpack_all(opts.unpack)
     end
     unless $stdout.tty? && $stdin.tty?
       warn "rakpak: needs an interactive terminal"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rakpak
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Ryan Wilson
@@ -11,7 +11,8 @@ date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
 description: A terminal file browser for building archives. Walk around, tag files
   and folders wherever they live, then pack them into one compressed tarball, plain
-  tarball or zip. No dependencies beyond Ruby and the archive tools on your machine.
+  tarball or zip. Unpacks them again too, from the browser or straight from the command
+  line. No dependencies beyond Ruby and the archive tools on your machine.
 email:
 - ryan@ryanwilson.io
 executables:
@@ -36,14 +37,15 @@ files:
 - lib/rakpak/term.rb
 - lib/rakpak/text.rb
 - lib/rakpak/theme.rb
+- lib/rakpak/unpack.rb
 - lib/rakpak/version.rb
-homepage: https://github.com/rywils/rakpak
+homepage: https://github.com/eof0/rakpak
 licenses:
 - MIT
 metadata:
-  homepage_uri: https://github.com/rywils/rakpak
-  source_code_uri: https://github.com/rywils/rakpak
-  bug_tracker_uri: https://github.com/rywils/rakpak/issues
+  homepage_uri: https://github.com/eof0/rakpak
+  source_code_uri: https://github.com/eof0/rakpak
+  bug_tracker_uri: https://github.com/eof0/rakpak/issues
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
@@ -61,6 +63,6 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 3.6.9
 specification_version: 4
-summary: Tag files anywhere on your filesystem and archive them all at once from the
-  terminal.
+summary: Tag files anywhere on your filesystem, archive them all at once, and unpack
+  again, from the terminal.
 test_files: []