yobi 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d127920e9ec0a4e254c53ce4b1a835e9ee4d94299fc93f7880debc55a5ec7472
-  data.tar.gz: 80415f3dfde8205cd62e7079c71006a6b6e599b2c3074ca1cc873c091a0c1229
+  metadata.gz: edd02fb1bbb985e22d5e32e8558b37f469809e9b5cdc079c6b4885e5ada5a775
+  data.tar.gz: 4d6a90b324596e6fc375a1338fdba1c70d84a6bf9504b15513614c87458bd7c0
 SHA512:
-  metadata.gz: 11134300c532ef9777e1a9a10e60b4a7d8cca05223e8c9ad9c0917bc4118bb5c609bb44c7037bd2c01615873884bd4a9ca02ad7f6fe44c00e536bcff4a2f7b0d
-  data.tar.gz: c52bc48ba265f031f1d37ddf153decec2ee9e6ab07de1a2501d0f5860ffe9b61a877d8b1c9b8553a5f2c612803b2cf188ced9833be11b8de00e22a043a00d9ca
+  metadata.gz: 9c11e446c74d42a68b7a34c61b4952451f0929d56114a6439ec6462f854019ea40d7844dd730371026a679f744a464600c997ce76b884de538a38ee879348efc
+  data.tar.gz: e3245e59a13c6b9f8712824406f0844106e1495a543ff68cf2ac11210835ef480109755acf2019ca5b10708d46436bc1e58f7e9e122f450ce3dd4f40395695fb

data/CHANGELOG.md

@@ -1,3 +1,19 @@
+## [0.2.0] - 2026-08-03
+
+### Added
+
+- `Repository#init_mirror` sets up a new destination repository, pre-initialized with chunker parameters copied from the source, so a later `#copy` between the two can deduplicate.
+- `Repository#cat_config` aliased as `#config`.
+- `CheckSummary` gained `#suggest_repair_index?` and `#suggest_prune?`.
+- `Restic#version` now tolerates a too-old restic binary that ignores `--json` for the `version` subcommand, falling back to parsing its plain-text output instead of raising a JSON parse error.
+
+### Changed
+
+- **Breaking:** `Repository#initialize`'s `password:` is now required - passing `nil` raises `ArgumentError`. Yobi no longer falls back to an ambient `RESTIC_PASSWORD`/`RESTIC_PASSWORD_COMMAND` env var on its own; pass `:insecure_no_password` explicitly if the repository truly has none. `Repository#init_mirror`'s `password:` is likewise now required.
+- **Breaking:** `#key_add`/`#key_passwd`'s new-password kwargs and `#init`'s `from_password:` collapsed to one polymorphic kwarg each, accepting the same literal/`[:command, ...]`/`[:file, ...]`/callable shapes as `password:`, instead of separate shape-specific kwargs.
+- **Breaking:** reworked how `#backup`/`#restore`/`#check`/`#diff`/`#tag`/`#forget`/`#ls` report results. Outcome objects (`BackupOutcome`, `RestoreOutcome`, `CheckOutcome`, `DiffOutcome`, `TagOutcome`, `LsOutcome`) are now plain classes wrapping a `ResticOutput` rather than `Struct.new(:exit_code, :output)`; per-message classes (`BackupError`, `BackupStatus`, `CheckError`, `DiffChange`, `TagChange`, and friends) are built on the new `Yobi::FancyHash` rather than `SimpleDelegator`; `#summary` (aliased `#report`) now returns a typed summary object (`BackupSummary`, `CheckSummary`, `TagSummary`) instead of a raw Hash; per-item accessors (`#errors`, `#changes`, `#entries`) are now lazy Enumerables instead of eagerly-built Arrays.
+- **Breaking:** renamed `Yobi::LsEntry` to `Yobi::Node`, `Yobi::ForgetReason` to `Yobi::KeepReason`, and `Yobi::Mount` to `Yobi::MountHandle`.
+
 ## [0.1.0] - 2026-07-29
 
 Initial release.

data/README.md

@@ -4,7 +4,7 @@ Yobi is a Ruby interface for the [Restic](https://restic.net/) backup program.
 
 ## Installation
 
-Install the gem:
+### Install the gem
 
 ```bash
 bundle add yobi
@@ -16,25 +16,11 @@ or, without Bundler:
 gem install yobi
 ```
 
-### Installing Restic
+### Install Restic
 
 Yobi shells out to a real `restic` binary; it doesn't install or bundle one. You need `restic` on `PATH` (or point Yobi at it explicitly, see below) before any of this works.
 
-Install it however you'd install any other system tool:
-
-```bash
-# macOS
-brew install restic
-
-# Debian/Ubuntu
-apt install restic
-
-# Arch
-pacman -S restic
-
-# or download a binary directly
-# https://github.com/restic/restic/releases
-```
+See [Restic's installation guide](https://restic.readthedocs.io/en/stable/020_installation.html) for how to install it on your platform.
 
 Confirm it's reachable:
 
@@ -103,9 +89,9 @@ outcome = repo.backup(
   excludes: ["*.tmp", "node_modules"],
   tags: ["documents", "daily"]
 )
-outcome.success? # => true
-outcome.report["snapshot_id"]
-outcome.report["data_added"]
+outcome.errors.none? # => true
+outcome.summary["snapshot_id"]
+outcome.summary["data_added"]
 
 repo.snapshots.each do |snapshot|
   puts "#{snapshot.short_id}  #{snapshot.time}  #{snapshot.paths.join(", ")}"
@@ -114,7 +100,7 @@ end
 repo.restore(snapshot_id: "latest", target: "/tmp/restore")
 ```
 
-Every verb method returns something typed rather than a raw Hash. `#backup` returns a `BackupOutcome` (`#success?`, `#report`, `#errors`), `#snapshots` returns an Enumerable of `Snapshot` objects, and so on throughout the API.
+Most verb methods return something typed rather than a raw Hash. `#backup` returns a `BackupOutcome` (`#summary`, `#errors`), `#snapshots` returns an Enumerable of `Snapshot` objects, and so on throughout the API - the low-level `cat_*` introspection commands are the exception, returning Restic's own raw JSON directly (see ["Low-level (`cat`) and object listing"](#low-level-cat-and-object-listing) below).
 
 ## Constructing a `Repository`
 
@@ -136,7 +122,7 @@ See [Restic's documentation](https://restic.readthedocs.io/en/stable/030_prepari
 
 ### `password:`
 
-Identifies the repository's encryption password. Five shapes:
+Identifies the repository's encryption password. Required - pass one of five shapes:
 
 ```ruby
 # A literal password
@@ -159,8 +145,6 @@ password = :insecure_no_password
 Yobi::Repository.new(url: "...", password: password)
 ```
 
-If `password:` is left unspecified, Yobi adds nothing extra to the environment: Restic falls back to `RESTIC_PASSWORD`/`RESTIC_PASSWORD_COMMAND` if either happens to already be set in the calling process's own environment (a container, systemd unit, or parent shell outside Yobi's control). If nothing is set anywhere, Restic refuses a truly empty password (unless `--insecure-no-password` is given) and fails loudly and safely on its own.
-
 ### `backend_credentials:`
 
 Separate from `password:`: this is whatever the storage *backend* needs to authenticate, unrelated to whether the repository's contents can be decrypted. A Hash of env vars, or a callable returning one, resolved fresh on every call the same way a callable `password:` is:
@@ -243,17 +227,17 @@ Creates the repository at `url`.
 
 ```ruby
 repo.init
-# => {"message_type"=>"initialized", "id"=>"...", "repository"=>"..."}
+# => #<Yobi::Initialized id="..." repository="...">
 ```
 
-`copy_chunker_params:`/`from_repo:`/`from_repository_file:`/`from_key_hint:`/`from_password_command:`/`from_password_file:`/`from_insecure_no_password:` copy chunker parameters from a secondary repository. Useful when you plan to `#copy` between the two later, since chunker params have to match for deduplication to work across repositories. `repository_version:` picks a specific repository format version instead of Restic's current default.
+`copy_chunker_params:` copies chunker parameters from another repository (`from_repo:`/`from_password:`/etc.), so a later `#copy` between the two can deduplicate - see `#init_mirror` under ["Across repositories"](#across-repositories) for a shortcut that sets this up in one call. See the [YARD docs](https://rubydoc.info/gems/yobi/Yobi/Repository#init-instance_method) for the full list of options. Returns an `Initialized` (`#id`/`#repository`).
 
-### `#config`
+### `#cat_config`
 
-The repository's own config document (`cat config`), as a Hash. A cheap way to confirm a repository exists and the password is correct without doing anything else.
+The repository's own config document (`cat config`), as a Hash. A cheap way to confirm a repository exists and the password is correct without doing anything else. Aliased `#config`.
 
 ```ruby
-repo.config
+repo.cat_config
 # => {"version"=>2, "id"=>"...", "chunker_polynomial"=>"..."}
 ```
 
@@ -269,43 +253,22 @@ outcome = repo.backup(
   excludes: ["*.tmp", "node_modules"],
   tags: ["documents", "daily"]
 )
-outcome.success?          # => true
-outcome.report["snapshot_id"]
-outcome.report["files_new"]
-outcome.report["data_added"]
+outcome.errors.none?      # => true
+outcome.summary["snapshot_id"]
+outcome.summary["files_new"]
+outcome.summary["data_added"]
 ```
 
 `source:` is either a path String, or a `[:stdin_from_command, command]`/`[:stdin_from_command, command, filename]` tuple: Restic spawns and executes `command` itself, capturing its stdout as the backup content (see ["Database dumps via `stdin_from_command`"](#database-dumps-via-stdin_from_command) below for a `pg_dump` example). `command` can be a String (tokenized with `Shellwords.split`, so quoted arguments survive) or an Array of already-discrete arguments (used as-is; needed when an argument itself contains a literal space, which `Shellwords` would otherwise split incorrectly).
 
-**Filtering:**
-
-- `excludes:`/`exclude_files:`/`iexcludes:`/`iexclude_files:` (case-insensitive): exclude by glob pattern or pattern file
-- `exclude_if_present:`: skip a directory containing a named marker file
-- `exclude_larger_than:`: skip by size
-- `exclude_caches:`/`exclude_cloud_files:`: skip CACHEDIR.TAG-marked dirs and cloud-placeholder files respectively
-- `files_from:`/`files_from_raw:`/`files_from_verbatim:`: read the backup list from a file instead of (or alongside) `source:`
-
-**Behavior:**
+`host:` records a hostname on the *new* snapshot - a single value, since this is metadata being written, not a filter, unlike every `hosts:` elsewhere in this API. See the [YARD docs](https://rubydoc.info/gems/yobi/Yobi/Repository#backup-instance_method) for the full list of options (filtering, retention, timing, and more).
 
-- `dry_run:`: report what would happen without doing it
-- `force:`: back up unchanged files anyway
-- `one_file_system:`: don't cross filesystem boundaries
-- `ignore_ctime:`/`ignore_inode:`: relax change detection
-- `no_scan:`: skip the pre-backup scan, disabling percentage progress
-- `skip_if_unchanged:`: don't create a snapshot if nothing changed
-- `parent:`: pick a specific parent snapshot instead of the latest one
-- `group_by:`: grouping used to find the parent snapshot instead, e.g. `"host,paths"`, when `parent:` isn't given
-- `read_concurrency:`: number of concurrent file reads
-- `time:`: record a specific timestamp instead of now
-- `with_atime:`: also store files' access times
-- `host:`: hostname recorded on the *new* snapshot (a single value: this is metadata being written, not a filter, unlike every `hosts:` elsewhere in this API)
+Returns a `BackupOutcome`: `#summary` (aliased `#report`; a `BackupSummary`, Restic's own summary fields plus `#backup_start`/`#backup_end` parsed into `Time`), `#errors` (lazy Enumerable of `BackupError` - empty unless some files were skipped, e.g. permission errors; a full failure raises before an outcome exists at all, see ["Error handling"](#error-handling) below), `#command_output` (the `source: [:stdin_from_command, ...]` subprocess's own stderr, de-prefixed, if any).
 
-Returns a `BackupOutcome`: `#success?`/`#partial?` (exit code 3, some files were skipped, e.g. permission errors), `#report` (the summary Hash, with `"backup_start"`/`"backup_end"` parsed into `Time`), `#errors` (lazy Enumerable of `BackupError`), `#command_output` (the `source: [:stdin_from_command, ...]` subprocess's own stderr, de-prefixed, if any).
-
-Also accepts a block, to receive typed progress objects as the backup runs instead of only getting the final `BackupOutcome`:
+Also accepts a block, to receive typed progress objects as the backup runs, on top of (not instead of) the final `BackupOutcome` once it returns. The block also receives a `Yobi::BackupSummary`, the same object `outcome.summary` returns, once the run finishes:
 
 ```ruby
-repo.backup(source: "/Users/zia/Documents") do |message|
+outcome = repo.backup(source: "/Users/zia/Documents") do |message|
   case message
   when Yobi::BackupStatus
     puts "#{((message.percent_done || 0) * 100).round}% (#{message.files_done}/#{message.total_files})"
@@ -313,8 +276,11 @@ repo.backup(source: "/Users/zia/Documents") do |message|
     warn "#{message.item}: #{message.message}"
   when Yobi::BackupVerboseStatus
     puts "#{message.action} #{message.item}"
+  when Yobi::BackupSummary
+    puts "done: #{message["data_added"]} bytes added"
   end
 end
+outcome.summary["snapshot_id"]
 ```
 
 `Yobi::BackupVerboseStatus` (one message per file) only streams when `verbose: true` is passed; it's not emitted by default, since a large backup can otherwise produce hundreds of MB of these. Behavior without a block is identical, just without the live callbacks; the returned `BackupOutcome` is the same either way.
@@ -325,19 +291,9 @@ end
 repo.restore(snapshot_id: "latest", target: "/tmp/restore")
 ```
 
-`snapshot_id:` accepts `"latest"` or a real ID; `target:` is the destination directory.
-
-- `excludes:`/`includes:` (and their `i`-prefixed case-insensitive/`_file` file-based variants): filter what gets restored. `includes:` has no backup-time equivalent, since restoring is the one direction where "only these" makes sense as well as "all but these."
-- `exclude_xattrs:`/`include_xattrs:`: filter extended attributes specifically
-- `dry_run:`: report what would happen without doing it
-- `delete:`: removes files in `target:` not present in the snapshot
-- `overwrite:` (`"always"`/`"if-changed"`/`"if-newer"`): controls what happens to files that already exist there
-- `sparse:`: writes sparse files
-- `ownership_by_name:`: maps ownership by user/group name instead of numeric ID
-- `verify:`: re-reads restored content against the repository to confirm it matches
-- `hosts:`/`paths:`/`tags:`: only matter when `snapshot_id:` is `"latest"`, same filters as everywhere else, used to resolve which snapshot "latest" means
+`snapshot_id:` accepts `"latest"` or a real ID; `target:` is the destination directory. `delete:` removes files in `target:` not present in the snapshot - worth knowing about since it's the one option here that can destroy data outside the snapshot itself. See the [YARD docs](https://rubydoc.info/gems/yobi/Yobi/Repository#restore-instance_method) for the full list of options (filtering, `overwrite:` behavior, and more).
 
-Returns a `RestoreOutcome` (`#report`, no `#success?`/`#partial?`: restore has no exit code 3, any item-level failure is a hard error that raises before an outcome exists).
+Returns a `RestoreOutcome`: `#summary` (aliased `#report`; Restic's own summary fields as a plain `Hash`) - restore has no exit code 3, so any item-level failure is a hard error that raises before an outcome exists.
 
 Accepts a block the same way `#backup` does, yielding `Yobi::RestoreStatus`/`Yobi::RestoreVerboseStatus` (the latter only when `verbose: true`) instead of `Yobi::BackupStatus`/`Yobi::BackupVerboseStatus`.
 
@@ -359,7 +315,7 @@ repo.dump(snapshot_id: "latest", file: "/var/www", target: "/tmp/www.tar")
 repo.dump(snapshot_id: "latest", file: "/var/www", target: "/tmp/www.zip", archive: "zip")
 ```
 
-Give at most one of `target:` or a block. Without either, returns a `Yobi::IOHandle` instead:
+Give at most one of `target:` or a block. Without either, returns a `Yobi::IOHandle` instead. `hosts:`/`paths:`/`tags:` filters are also available when `snapshot_id:` is `"latest"` - see the [YARD docs](https://rubydoc.info/gems/yobi/Yobi/Repository#dump-instance_method) for the full list of options.
 
 ```ruby
 handle = repo.dump(snapshot_id: "latest", file: "/var/www")
@@ -375,11 +331,13 @@ end
 
 ```ruby
 outcome = repo.diff(from: older_snapshot.id, to: newer_snapshot.id)
-outcome.report["changed_files"]
+outcome.statistics.changed_files
 outcome.changes.each { |change| puts "#{change.modifier} #{change.path}" }
 ```
 
-`metadata: true` also reports metadata-only changes (permissions, timestamps) alongside content changes. `change.modifier` is Restic's own single-character code: `+` added, `-` removed, `U` metadata updated, `M` content modified, `T` type changed, `?` bitrot detected.
+`metadata: true` also reports metadata-only changes (permissions, timestamps) alongside content changes. `change.modifier` is Restic's own concatenation of single-character codes: `+` added, `-` removed, `U` metadata updated, `M` content modified, `T` type changed, `?` bitrot detected. See the [YARD docs](https://rubydoc.info/gems/yobi/Yobi/Repository#diff-instance_method) for the full list of options.
+
+Returns a `DiffOutcome`: `#statistics` (aliased `#report`; a `DiffStatistics` with `#changed_files` plus `#added`/`#removed` `DiffStat` breakdowns) and lazy `#changes` (Enumerable of `DiffChange`, with predicates like `#modified?`/`#added?` alongside the raw `#modifier`).
 
 ## Snapshot management
 
@@ -391,7 +349,7 @@ repo.snapshots(tags: ["daily"], hosts: "web-1").each do |snapshot|
 end
 ```
 
-Returns an Enumerable of `Snapshot` (`#id`, `#short_id`, `#time`, `#host`, `#tags`, `#paths`, `#parent_id`). `compact:` compacts the underlying Restic output; `group_by:`/`latest:` group and limit results, e.g. `latest: 1` per group for "the most recent backup of each host."
+Returns an Enumerable of `Snapshot` (`#id`, `#short_id`, `#time`, `#host`, `#tags`, `#paths`, `#parent_id`, `#summary` - a `SnapshotSummary` with the same stats fields `#backup`'s own summary has). `group_by:`/`latest:` group and limit results, e.g. `latest: 1` per group for "the most recent backup of each host." See the [YARD docs](https://rubydoc.info/gems/yobi/Yobi/Repository#snapshots-instance_method) for the full list of options.
 
 ### `#tag`
 
@@ -399,7 +357,9 @@ Returns an Enumerable of `Snapshot` (`#id`, `#short_id`, `#time`, `#host`, `#tag
 repo.tag(snapshot_ids: snapshot.id, add: "verified")
 ```
 
-`add:`/`remove:`/`set:` (mutually exclusive with `add:`/`remove:` in Restic itself) modify tags on snapshots matched by `snapshot_ids:` (or by `hosts:`/`paths:`/`tags:` filters when no explicit IDs are given). Since tags are part of a snapshot's content-addressed identity, tagging produces a *new* snapshot ID for every snapshot touched. `TagOutcome#changes` gives you the old-ID/new-ID pairs.
+`add:`/`remove:`/`set:` (mutually exclusive with `add:`/`remove:` in Restic itself) modify tags on snapshots matched by `snapshot_ids:` (or by `hosts:`/`paths:`/`tags:` filters when no explicit IDs are given). Since tags are part of a snapshot's content-addressed identity, tagging produces a *new* snapshot ID for every snapshot touched. See the [YARD docs](https://rubydoc.info/gems/yobi/Yobi/Repository#tag-instance_method) for the full list of options.
+
+Returns a `TagOutcome`: `#summary` (aliased `#report`; a `TagSummary` - just `#changed_snapshots`) and lazy `#changes` (Enumerable of `TagChange`, the old-ID/new-ID pairs).
 
 ### `#forget`
 
@@ -407,30 +367,34 @@ repo.tag(snapshot_ids: snapshot.id, add: "verified")
 repo.forget(keep_daily: 7, keep_weekly: 4, keep_monthly: 12, prune: true)
 ```
 
-Applies a retention policy, removing snapshots that don't match any `keep_*` rule: `keep_last:`/`keep_hourly:`/`keep_daily:`/`keep_weekly:`/`keep_monthly:`/`keep_yearly:` (counts) and `keep_within:`/`keep_within_hourly:`/etc. (durations, e.g. `"30d"`). `keep_tags:` always keeps snapshots carrying any of the given tags regardless of the numeric rules. `prune: true` also reclaims the disk space the forgotten snapshots held (equivalent to a separate `#prune` call afterward); the `max_unused:`/`max_repack_size:`/`repack_*:` kwargs tune that implied prune step exactly like `#prune`'s own. `dry_run:` reports what would be removed without doing it. `unsafe_allow_remove_all:` is required if a policy would remove every snapshot.
+Applies a retention policy, removing snapshots that don't match any `keep_*` rule (counts like `keep_daily:`, or durations like `keep_within:`). `prune: true` also reclaims the disk space the forgotten snapshots held (equivalent to a separate `#prune` call afterward). See the [YARD docs](https://rubydoc.info/gems/yobi/Yobi/Repository#forget-instance_method) for the full list of options.
 
-Returns an Enumerable of `ForgetGroup` (Restic evaluates the policy per group, by default grouped by host+paths). Each exposes `#keep`/`#remove` (Arrays of `Snapshot`) and `#reasons` (an Array of `ForgetReason` explaining which rule kept each surviving snapshot, e.g. `"daily snapshot"`).
+Returns an Enumerable of `ForgetGroup` (Restic evaluates the policy per group, by default grouped by host+paths). Each exposes `#keep`/`#remove` (Arrays of `Snapshot`) and `#reasons` (an Array of `KeepReason` explaining which rule kept each surviving snapshot, e.g. `"daily snapshot"`).
 
 ### `#find`
 
 ```ruby
 repo.find(patterns: "*.pem").each do |matches|
-  puts "in #{matches.snapshot["short_id"]}: #{matches.hits} hits"
+  puts "in #{matches.snapshot_id}: #{matches.hits} hits"
   matches.matches.each { |m| puts "  #{m.path}" }
 end
 ```
 
-Searches for files/directories by name pattern across snapshots. `blob:`/`pack:`/`tree:` switch to matching object IDs instead, for low-level troubleshooting. Returns an Enumerable of `MatchesPerSnapshot` (Restic's own docs describe find's output as "organized by snapshot," not a flat list). Each has `#hits` and `#matches` (an Array of `FindMatch`, with the usual file metadata: `#path`, `#size`, `#mtime`, etc.).
+Searches for files/directories by name pattern across snapshots. `blob:`/`pack:`/`tree:` switch to matching object IDs instead, for low-level troubleshooting. See the [YARD docs](https://rubydoc.info/gems/yobi/Yobi/Repository#find-instance_method) for the full list of options.
+
+Returns an Enumerable of `MatchesPerSnapshot` (Restic's own docs describe find's output as "organized by snapshot," not a flat list). Each has `#snapshot`/`#snapshot_id` (just the matched snapshot's ID as a String - unlike elsewhere in this API, Restic's own `find` output doesn't include the full record), `#hits`, and `#matches` (an Array of `FindMatch`, with the usual file metadata: `#path`, `#size`, `#mtime`, etc.).
 
 ### `#ls`
 
 ```ruby
 outcome = repo.ls(snapshot_id: "latest", dirs: "/var/www")
 outcome.snapshot.short_id
-outcome.entries.each { |entry| puts entry.path }
+outcome.nodes.each { |node| puts node.path }
 ```
 
-Lists a snapshot's files/directories. `recursive:` descends into subdirectories; `dirs:` restricts to specific paths within the snapshot. Returns an `LsOutcome`: `#snapshot` (the resolved `Snapshot`, useful to see what `"latest"` actually resolved to) and lazy `#entries` (Enumerable of `LsEntry`).
+Lists a snapshot's files/directories. `recursive:` descends into subdirectories. See the [YARD docs](https://rubydoc.info/gems/yobi/Yobi/Repository#ls-instance_method) for the full list of options.
+
+Returns an `LsOutcome`: `#snapshot` (the resolved `Snapshot`, useful to see what `"latest"` actually resolved to) and lazy `#nodes` (aliased `#entries`; Enumerable of `Node` - Restic's own term for a file/directory entry).
 
 ## Maintenance and health
 
@@ -438,11 +402,13 @@ Lists a snapshot's files/directories. `recursive:` descends into subdirectories;
 
 ```ruby
 outcome = repo.check(read_data_subset: "5%")
-outcome.report["num_errors"]
+outcome.summary.num_errors
 outcome.errors.each { |error| puts error.message }
 ```
 
-Verifies repository integrity. `read_data:` also reads and verifies every pack file's actual contents, not just structure (slow, thorough); `read_data_subset:` does a partial version of the same (e.g. `"5%"`, or `"1/20"` for a fifth each day in rotation); `with_cache:` uses the local cache instead of bypassing it. Returns a `CheckOutcome` (no `#success?`/`#partial?`: check has no exit code 3; check `report["num_errors"]` instead).
+Verifies repository integrity. `read_data:` also reads and verifies every pack file's actual contents, not just structure (slow, thorough); `read_data_subset:` does a partial version of the same (e.g. `"5%"`, or `"1/20"` for a fifth each day in rotation). See the [YARD docs](https://rubydoc.info/gems/yobi/Yobi/Repository#check-instance_method) for the full list of options.
+
+Returns a `CheckOutcome`: `#summary` (aliased `#report`; a `CheckSummary` covering the error count and what to run next - repair or prune) and `#errors` (lazy Enumerable of `CheckError`) for problems found.
 
 ### `#prune`
 
@@ -450,7 +416,7 @@ Verifies repository integrity. `read_data:` also reads and verifies every pack f
 repo.prune(max_unused: "5%")
 ```
 
-Removes data no longer referenced by any snapshot. `dry_run:` reports what would happen without doing it. `max_unused:` targets a maximum acceptable unused-space ratio after pruning; `max_repack_size:` bounds how much gets repacked in one run (for spreading a large prune across multiple scheduled invocations); `repack_cacheable_only:`/`repack_uncompressed:`/`repack_smaller_than:` tune which packs get rewritten. `unsafe_recover_no_free_space:` proceeds even without enough free space, at the given risk acknowledgement string. Returns `true`.
+Removes data no longer referenced by any snapshot. `dry_run:` reports what would happen without doing it; `max_unused:` targets a maximum acceptable unused-space ratio after pruning. See the [YARD docs](https://rubydoc.info/gems/yobi/Yobi/Repository#prune-instance_method) for the full list of options. Returns `true`.
 
 ### `#repair_index`, `#repair_packs`, `#repair_snapshots`
 
@@ -460,7 +426,7 @@ repo.repair_packs(ids: damaged_pack_ids)
 repo.repair_snapshots(snapshot_ids: affected_ids, forget: true)
 ```
 
-`#repair_index` rebuilds the index from the pack files present (the modern successor to Restic's now-deprecated `rebuild-index`). `#repair_packs` extracts intact blobs from damaged pack files and drops the rest. Restic also writes a backup copy of each given pack (named `pack-<id>`) into the *calling process's own current working directory* first, with no flag to disable this; be aware of where your process runs from before calling it. `#repair_snapshots` regenerates snapshots with damaged content removed. This is real data loss for whatever gets removed, so prefer a fresh `#backup` where the source data is still available, and run `#repair_index` first since this depends on a correct index.
+`#repair_index` rebuilds the index from the pack files present (the modern successor to Restic's now-deprecated `rebuild-index`). `#repair_packs` extracts intact blobs from damaged pack files and drops the rest. Restic also writes a backup copy of each given pack (named `pack-<id>`) into the *calling process's own current working directory* first, with no flag to disable this; be aware of where your process runs from before calling it. `#repair_snapshots` regenerates snapshots with damaged content removed. This is real data loss for whatever gets removed, so prefer a fresh `#backup` where the source data is still available, and run `#repair_index` first since this depends on a correct index. See the [YARD docs](https://rubydoc.info/gems/yobi/Yobi/Repository#repair_snapshots-instance_method) for the full list of options.
 
 ### `#recover`
 
@@ -476,7 +442,7 @@ Builds a new snapshot from any data present in the repository but not referenced
 repo.rewrite(snapshot_ids: old.id, excludes: "*.log", new_time: Time.now.iso8601)
 ```
 
-Creates new snapshots from existing ones with filters applied or metadata changed. With no `snapshot_ids:`/`hosts:`/`tags:`/`paths:` given, rewrites every snapshot in the repository. Restic's own default, not something Yobi adds. `excludes:`/`exclude_files:`/`includes:`/`include_files:` (and their `i`-prefixed case-insensitive variants) filter file content the same way as `#backup`/`#restore`. `dry_run:` reports what would happen without doing it. `new_host:`/`new_time:` change the recorded hostname/timestamp; `snapshot_summary:` regenerates the snapshot summary. `forget: false` (the default) tags the new snapshots `"rewrite"` and keeps the originals; `forget: true` removes the originals instead (their data isn't reclaimed until a later `#prune`).
+Creates new snapshots from existing ones with filters applied or metadata changed. With no `snapshot_ids:`/`hosts:`/`tags:`/`paths:` given, rewrites every snapshot in the repository - Restic's own default, not something Yobi adds. `dry_run:` reports what would happen without doing it. `forget: false` (the default) tags the new snapshots `"rewrite"` and keeps the originals; `forget: true` removes the originals instead (their data isn't reclaimed until a later `#prune`). See the [YARD docs](https://rubydoc.info/gems/yobi/Yobi/Repository#rewrite-instance_method) for the full list of options.
 
 ### `#migrate`
 
@@ -498,23 +464,30 @@ Removes stale locks left by other Restic processes. `remove_all: true` removes e
 
 ```ruby
 repo.stats(mode: "raw-data")
-# => {"total_size"=>..., "total_file_count"=>..., "snapshots_count"=>...}
+# => #<Yobi::RepositoryStats total_size=... total_file_count=... snapshots_count=...>
 ```
 
-Repository size/file-count statistics. `mode:` picks the counting strategy, as a String or Symbol: `"restore-size"`/`:restore_size` (default), `"files-by-contents"`/`:files_by_contents`, `"blobs-per-file"`/`:blobs_per_file`, `"raw-data"`/`:raw_data` (actual on-disk size, accounting for deduplication). Anything else raises `ArgumentError`.
+Repository size/file-count statistics. `mode:` picks the counting strategy, as a String or Symbol: `"restore-size"`/`:restore_size` (default), `"files-by-contents"`/`:files_by_contents`, `"blobs-per-file"`/`:blobs_per_file`, `"raw-data"`/`:raw_data` (actual on-disk size, accounting for deduplication). Anything else raises `ArgumentError`. See the [YARD docs](https://rubydoc.info/gems/yobi/Yobi/Repository#stats-instance_method) for more. Returns a `RepositoryStats` covering size, file/blob counts, and (for a repository using compression) how much space it's saving.
 
 ## Key management
 
 ```ruby
-repo.key_add(user: "ci-runner")
+repo.key_add(user: "ci-runner", new_password: [:file, "/etc/restic/ci-runner-password"])
 repo.key_list.each { |key| puts "#{key.id} #{key.user_name}@#{key.host_name} current=#{key.current?}" }
-repo.key_passwd(new_password_file: "/etc/restic/new-password")
+repo.key_passwd(new_password: [:file, "/etc/restic/new-password"])
 repo.key_remove(id: old_key.id)
 ```
 
-`#key_add`/`#key_list`/`#key_passwd`/`#key_remove` (aliased `#add_key`/`#keys`/`#change_password`/`#remove_key`) manage passwords. Every key here is a different way to unlock the same underlying master key, not a separate encryption key of its own (see ["Low-level (`cat`) and object listing"](#low-level-cat-and-object-listing)'s note on `#cat_masterkey_and_game_over_if_this_leaks` below). `#key_passwd` doesn't mutate the `Repository` you called it on; build a new one with the rotated password to keep talking to the repository afterward.
+`#key_add`/`#key_list`/`#key_passwd`/`#key_remove` (aliased `#add_key`/`#keys`/`#change_password`/`#remove_key`) manage passwords. Every key here is a different way to unlock the same underlying master key, not a separate encryption key of its own (see ["Low-level (`cat`) and object listing"](#low-level-cat-and-object-listing) below's note on `#cat_masterkey_and_game_over_if_this_leaks`).
 
-`#key_add`/`#key_passwd` share the same kwargs: `host:`/`user:` record a hostname/username on the new key (defaults to the OS's own, same as Restic itself); `new_insecure_no_password:` sets the new key's password to empty; `new_password_file:` reads the new password from a file instead of prompting interactively.
+`#key_add`/`#key_passwd` share the same kwargs: `new_password:` is required, accepting the same shapes as `#initialize`'s `password:` minus `[:command, ...]`: a literal String; a `[:file, "..."]` tuple, resolved natively by Restic; `:insecure_no_password`; or anything responding to `#call`. Restic itself only accepts a new password by file, unlike the repository's own `password:`, so a literal String or callable is written to a briefly-lived, 0600-permissioned tempfile by Yobi first. See the [YARD docs](https://rubydoc.info/gems/yobi/Yobi/Repository#key_add-instance_method) for the full list of options.
+
+`#key_passwd` rotates the *password*, not the underlying master key itself (see the note on `#cat_masterkey_and_game_over_if_this_leaks` below if that distinction matters for your threat model). On success, it also updates this same `Repository` instance's own `password:` to match, so it keeps working against the repository right afterward:
+
+```ruby
+repo.key_passwd(new_password: "new-password-value")
+repo.snapshots # already using the new password - no need to rebuild `repo`
+```
 
 Restic refuses to `#key_remove` the key currently in use.
 
@@ -534,13 +507,21 @@ repo.list(:packs)                     # => Array of pack IDs
 
 ## Across repositories
 
+### `#init_mirror`
+
+```ruby
+mirror_repo = primary_repo.init_mirror(url: "b2:my-bucket:/", password: "...")
+```
+
+A shortcut for setting up a `#copy` destination: constructs a new `Repository` and initializes it with chunker parameters copied from `primary_repo`, so `#copy` between the two can deduplicate (skipped this way, Restic picks each repository's chunker polynomial independently at `#init` time, so nothing between them would ever dedupe). A one-time setup call, not an ongoing sync - pair it with repeated `#copy` calls below to actually move snapshots across.
+
 ### `#copy`
 
 ```ruby
-repo.copy(from_repo: source_repo, hosts: "web-1")
+mirror_repo.copy(from_repo: primary_repo, tags: "nightly")
 ```
 
-Replicates snapshots from another repository into this one. `from_repo:` accepts a plain URL String or a `Repository` instance. Given the latter, its own `#url`/`#password` are used automatically unless `from_password:` is given explicitly. `from_key_hint:`/`from_repository_file:` are passed straight through to Restic (a key ID hint for the source repository, and reading the source URL from a file, respectively). Already-copied snapshots are skipped automatically on a repeat run. Returns `true`.
+Replicates snapshots from another repository into this one. `from_repo:` accepts a plain URL String or a `Repository` instance. Given the latter, its own `#url`/`#password` are used automatically unless `from_password:` is given explicitly. Already-copied snapshots are skipped automatically on a repeat run. See the [YARD docs](https://rubydoc.info/gems/yobi/Yobi/Repository#copy-instance_method) for the full list of options. Returns `true`.
 
 ## Mounting
 
@@ -552,7 +533,7 @@ repo.mount(mountpoint: "/mnt/restic") do |mount|
 end
 ```
 
-Serves the repository as a read-only FUSE filesystem at `mountpoint` (which must already exist). With a block, yields a `Yobi::Mount` and stops it automatically afterward. Without one, returns the `Mount` for you to `#stop` yourself:
+Serves the repository as a read-only FUSE filesystem at `mountpoint` (which must already exist). With a block, yields a `Yobi::MountHandle` and stops it automatically afterward. Without one, returns the `MountHandle` for you to `#stop` yourself:
 
 ```ruby
 mount = repo.mount(mountpoint: "/mnt/restic")
@@ -563,17 +544,17 @@ ensure
 end
 ```
 
-`#stop` is safe to call more than once, and `Mount#pid`/`Mount#stop` are safe even if something *else* already triggered the unmount externally (`kill -INT <pid>`, or the OS's own `umount`/`fusermount` directly). `hosts:`/`paths:`/`tags:` restrict which snapshots appear under the mount's own `snapshots/` directory; `path_templates:`/`time_template:` control the directory naming scheme Restic generates there. `allow_other:`/`no_default_permissions:`/`owner_root:` are FUSE-level access options (allow other users to access the mount, skip permission checks, mount files as owned by root, respectively). `ready_timeout:` (default 10 seconds) bounds how long `#mount` waits for Restic's own readiness message before raising `Yobi::MountTimeout`.
+`#stop` is safe to call more than once, and `MountHandle#pid`/`MountHandle#stop` are safe even if something *else* already triggered the unmount externally (`kill -INT <pid>`, or the OS's own `umount`/`fusermount` directly). `hosts:`/`paths:`/`tags:` restrict which snapshots appear under the mount's own `snapshots/` directory. `ready_timeout:` (default 10 seconds) bounds how long `#mount` waits for Restic's own readiness message before raising `Yobi::MountTimeout`. See the [YARD docs](https://rubydoc.info/gems/yobi/Yobi/Repository#mount-instance_method) for the full list of options.
 
 ## Restic-level (not scoped to a repository)
 
 ```ruby
 restic = Yobi::Restic.new
-restic.version # => {"version"=>"0.19.1", "go_version"=>"...", ...}
+restic.version.version # => "0.19.1"
 restic.cache(cleanup: true)
 ```
 
-`#version` and `#cache` are the two Restic subcommands that don't touch a repository at all, so they live on `Yobi::Restic` rather than `Repository`. `#cache` lists (or, with `cleanup: true`, cleans) local cache directories, returning `true`. `max_age:` limits cleanup to caches older than the given duration; `no_size:` skips computing directory sizes, for a faster listing.
+`#version` and `#cache` are the two Restic subcommands that don't touch a repository at all, so they live on `Yobi::Restic` rather than `Repository`. `#version` returns a `Yobi::ResticVersion` (`#version`, `#go_version`, `#go_os`, `#go_arch`); if the installed binary is old enough to ignore `--json` for this command entirely, Yobi falls back to parsing its plain-text output for the version number instead of raising a JSON parse error. `#cache` lists (or, with `cleanup: true`, cleans) local cache directories, returning `true`. See the [YARD docs](https://rubydoc.info/gems/yobi/Yobi/Restic#cache-instance_method) for its remaining options.
 
 ## Global `Restic` settings
 
@@ -589,8 +570,10 @@ restic = Yobi::Restic.new(
 
 Two genuinely different kinds, both exposed as plain `attr_accessor`s:
 
-- **Env-var-backed**: `cache_dir:`, `compression:`, `pack_size:`, `read_concurrency:`, `host:`, `progress_fps:`, `cacert:`, `tls_client_cert:`, `key_hint:`. `Restic#env` computes the corresponding `RESTIC_*` vars fresh from the current accessor values on every call. Mutating one after construction is picked up by the very next command.
-- **CLI-flag-only, no env var equivalent**: `limit_download:`, `limit_upload:`, `retry_lock:`, `no_lock:`, `no_cache:`, `cleanup_cache:`, `no_extra_verify:`, `stuck_request_timeout:`, `options:` (Restic's own `--option`/`-o`, an escape hatch for backend-specific tuning like `s3.connections=10`), `http_user_agent:`, `quiet:`.
+- **Env-var-backed** (e.g. `cache_dir:`, `compression:`, `pack_size:`): `Restic#env` computes the corresponding `RESTIC_*` vars fresh from the current accessor values on every call. Mutating one after construction is picked up by the very next command.
+- **CLI-flag-only, no env var equivalent** (e.g. `limit_upload:`, `no_lock:`, `options:` - Restic's own `--option`/`-o`, an escape hatch for backend-specific tuning like `s3.connections=10`).
+
+See the [YARD docs](https://rubydoc.info/gems/yobi/Yobi/Restic) for the full list of settings.
 
 "Picked up by the very next command" assumes calls happen one at a time. If you mutate one of these accessors on a `Restic` shared across threads while another thread has a command already in flight on it, which value that in-flight command actually uses is a race with no ordering guarantee, though not a crash: each accessor read/write is still atomic, so you won't get a corrupted argv, just an unpredictable choice between the old and new value.
 
@@ -642,9 +625,7 @@ outcome = repo.backup(
   exclude_caches: true
 )
 
-unless outcome.success?
-  outcome.errors.each { |e| log_error("backup: #{e.item}: #{e.message}") }
-end
+outcome.errors.each { |e| log_error("backup: #{e.item}: #{e.message}") }
 
 repo.forget(
   keep_daily: 7,
@@ -655,7 +636,7 @@ repo.forget(
 )
 ```
 
-`outcome.partial?` (exit code 3) means some files were skipped but the snapshot was still created (often fine to continue past, e.g. permission-denied on a handful of files); a full failure raises before `outcome` even exists via the usual `Yobi::ResticCommandFailed`/`Yobi::RepositoryLocked`/etc. hierarchy, so wrap the whole thing in the usual `rescue` if you want to alert on that separately (see ["Graceful lock-contention handling"](#graceful-lock-contention-handling) below).
+A non-empty `outcome.errors` (exit code 3) means some files were skipped but the snapshot was still created (often fine to continue past, e.g. permission-denied on a handful of files); a full failure raises before `outcome` even exists via the usual `Yobi::ResticCommandFailed`/`Yobi::RepositoryLocked`/etc. hierarchy, so wrap the whole thing in the usual `rescue` if you want to alert on that separately (see ["Graceful lock-contention handling"](#graceful-lock-contention-handling) below).
 
 ### Restore workflows
 
@@ -683,8 +664,8 @@ end
 or list without mounting anything:
 
 ```ruby
-repo.ls(snapshot_id: "latest", dirs: "/var/myapp/uploads").entries.each do |entry|
-  puts "#{entry.type}  #{entry.size}  #{entry.path}"
+repo.ls(snapshot_id: "latest", dirs: "/var/myapp/uploads").nodes.each do |node|
+  puts "#{node.type}  #{node.size}  #{node.path}"
 end
 ```
 
@@ -812,11 +793,11 @@ end
 workers.each(&:join)
 ```
 
-**Copying between repositories** (e.g. replicating to a second, offsite backend for a 3-2-1 strategy):
+**Copying between repositories** (e.g. replicating to a second, offsite backend for a 3-2-1 strategy), see `#init_mirror`/`#copy` under ["Across repositories"](#across-repositories):
 
 ```ruby
-offsite = Yobi::Repository.new(url: "b2:my-bucket:/", password: "...")
-offsite.copy(from_repo: primary_repo, tags: "nightly")
+mirror_repo = primary_repo.init_mirror(url: "b2:my-bucket:/", password: "...") # once, before the first #copy
+mirror_repo.copy(from_repo: primary_repo, tags: "nightly") # run nightly, e.g. from cron
 ```
 
 ### Repository maintenance and health checks
@@ -825,7 +806,7 @@ A separate, less-frequent job (weekly, say) than the nightly backup itself:
 
 ```ruby
 check = repo.check(read_data_subset: "10%")
-if check.report["num_errors"].to_i.positive?
+if check.summary.num_errors.positive?
   check.errors.each { |e| AlertService.notify("Restic check: #{e.message}") }
 end
 
@@ -834,20 +815,6 @@ repo.prune(max_unused: "5%")
 
 `read_data_subset:` rotates through the repository over time (e.g. `"1/20"` today, `"2/20"` tomorrow) rather than reading everything in one run, so a full verification eventually happens without one job spending hours reading the entire dataset.
 
-### Key rotation
-
-```ruby
-repo.key_passwd(new_password_file: "/etc/restic/new-password")
-
-# repo itself still holds the OLD password - rebuild before continuing
-rotated_repo = Yobi::Repository.new(
-  url: repo.url,
-  password: [:file, "/etc/restic/new-password"]
-)
-```
-
-This rotates the *password*, not the underlying encryption key itself (see ["Key management"](#key-management) above for why `repo` still needs rebuilding afterward). See ["Low-level (`cat`) and object listing"](#low-level-cat-and-object-listing)'s note on `#cat_masterkey_and_game_over_if_this_leaks` if that distinction matters for your threat model.
-
 ### Graceful lock-contention handling
 
 Two processes touching the same repository at once (a backup job and a prune job overlapping, say): retry instead of failing the whole run:
@@ -895,3 +862,5 @@ See `MAINTAINERS.md` for what to keep in sync as the API changes, and the releas
 ## License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+☂️☔️☂️☔️☂️

data/lib/yobi/argv_builder.rb

@@ -24,6 +24,11 @@ module Yobi
       @argv
     end
 
+    # @return [String]
+    def inspect
+      "#<#{self.class} #{@argv.inspect}>"
+    end
+
     # Appends one or more bare positional values. `nil` is dropped; an
     # Enumerable is flattened in; everything else is converted with `#to_s`.
     #

data/lib/yobi/errors.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 require "json"
-require "delegate"
 
 module Yobi
   # Base class for all errors raised by Yobi.
@@ -9,8 +8,8 @@ module Yobi
 
   # The `exit_error` message from a fatal Restic run, if one was printed.
   # https://restic.readthedocs.io/en/stable/075_scripting.html#exit-errors
-  class ExitError < SimpleDelegator
-    # Matches a JSON line with `"message_type": "exit_error"`.
+  class ExitError < Yobi::FancyHash
+    # @private
     LINE_PATTERN = /"message_type"\s*:\s*"exit_error"/
 
     # @param output [Yobi::ResticOutput]
@@ -37,8 +36,7 @@ module Yobi
     # @return [String]
     attr_reader :installed_version, :minimum_version
 
-    # @param installed_version [String]
-    # @param minimum_version [String]
+    # @private
     def initialize(installed_version:, minimum_version:)
       @installed_version = installed_version
       @minimum_version = minimum_version
@@ -53,8 +51,7 @@ module Yobi
     # @return [Array<String>]
     attr_reader :argv
 
-    # @param restic_path [String]
-    # @param argv [Array<String>]
+    # @private
     def initialize(restic_path:, argv:)
       @restic_path = restic_path
       @argv = argv
@@ -70,7 +67,7 @@ module Yobi
     # @return [Yobi::ExitError, nil]
     attr_reader :exit_error
 
-    # @param execution [Hash]
+    # @private
     def initialize(execution)
       @execution = execution
       @exit_error = Yobi::ExitError.from_output(execution[:output])
@@ -98,8 +95,7 @@ module Yobi
     # @return [Numeric]
     attr_reader :timeout
 
-    # @param argv [Array<String>]
-    # @param timeout [Numeric]
+    # @private
     def initialize(argv:, timeout:)
       @argv = argv
       @timeout = timeout