minestrone 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6cd69ccb970305b22a5e19099df378e581cb3c15ff188ebdffcf2fef499e6bdd
+  data.tar.gz: 7c01180ad806dd649ad13e5682d815179221c85c120aa60dc411d83fffd413de
+SHA512:
+  metadata.gz: e8ddd3e8f828248e489f7b22bb9476cb962ea1d04e5973b9cb4a2eed0d3558bd91bdaa8e7142a9151649b041148fa9cb60440a97fcd7bd737a4a7db13b304f25
+  data.tar.gz: db1e39316df310daf33fd85aa3c11fecc671ad1ba19f9ccbe4d67e3d47aa370296cb182021e767f16c4b3b841a0cf72110d178c0bec54a69a7869435c044e26a

data/.github/workflows/main.yml

@@ -0,0 +1,32 @@
+name: Ruby
+
+on:
+  push:
+    branches:
+      - master
+
+  pull_request:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    name: Ruby ${{ matrix.ruby }}
+    strategy:
+      matrix:
+        ruby:
+          - '3.0'
+          - '3.1'
+          - '3.2'
+          - '3.3'
+          - '3.4'
+          - '4.0'
+
+    steps:
+    - uses: actions/checkout@v3
+    - name: Set up Ruby
+      uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: ${{ matrix.ruby }}
+        bundler-cache: true
+    - name: Run the default task
+      run: bundle exec rake

data/.gitignore

@@ -0,0 +1,5 @@
+.DS_Store
+.bundle
+coverage
+doc
+Gemfile.lock

data/Gemfile

@@ -0,0 +1,10 @@
+source 'http://rubygems.org'
+
+# Specify your gem's dependencies in minestrone.gemspec
+gemspec
+
+group :development do
+  gem 'mocha', '~> 3.1'
+  gem 'rake', '~> 13.4'
+  gem 'test-unit', '~> 3.7'
+end

data/LICENSE.txt

@@ -0,0 +1,22 @@
+MIT License (MIT)
+
+Copyright (c) 2012-2020 Tom Clements, Lee Hambley
+Copyright (c) 2005-2007 Jamis Buck <jamis@37signals.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,35 @@
+# Minestrone 🍲
+
+Minestrone is a simplified fork of old [Capistrano](https://github.com/minestrone/minestrone) 2.x. A kind of… mini-capistrano.
+
+
+## Project description
+
+Minestrone is a tool for deploying Ruby applications to a server, based on the code of the classic deploy tool Capistrano, the older 2.x version, but simplified and cleaned up, with various features removed that I decided I'm never going to need myself. The focus is on deploying Ruby apps to a single host from Git over SSH. It keeps the core deploy DSL with compatibility maintained where possible, the git remote cache and copy strategies, release rotation with rollbacks, and the logging/formatting code.
+
+
+### What is removed
+
+* server roles, multiple servers and "primary" server designation – you only define a single server hostname and everything happens there
+* support for any parallel execution
+* multiple stages
+* SSH gateways
+* password authentication for SSH and Git
+* Windows support
+* REPL shell
+* legacy SCMs – only `:git` and `:none` are left
+* most deploy strategies – only `:remote_cache` and `:copy` are left
+* any legacy/deprecated code from Capistrano 1.x era or for ancient versions of Ruby
+
+
+### Other API changes
+
+* default deploy path is `/var/www/#{application}`
+* `server` method in the DSL only accepts a single string + options
+* Ruby 3.0+ is required
+
+
+### Project status
+
+> [!WARNING]
+> This project is an early, untested alpha version. Most of the work stripping out various parts from the old codebase was done using Codex AI coding agent (with manual code reviews to some degree). Use with caution.

data/Rakefile

@@ -0,0 +1,10 @@
+require 'bundler'
+Bundler::GemHelper.install_tasks
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/*_test.rb'
+end
+
+task :default => :test

data/bin/capify

@@ -0,0 +1,89 @@
+#!/usr/bin/env ruby
+
+require 'optparse'
+require 'fileutils'
+
+OptionParser.new do |opts|
+  opts.banner = "Usage: #{File.basename($0)} [path]"
+
+  opts.on("-h", "--help", "Displays this help info") do
+    puts opts
+    exit 0
+  end
+
+  begin
+    opts.parse!(ARGV)
+  rescue OptionParser::ParseError => e
+    warn e.message
+    puts opts
+    exit 1
+  end
+end
+
+if ARGV.empty?
+  abort "Please specify the directory to capify, e.g. `#{File.basename($0)} .'"
+elsif !File.exist?(ARGV.first)
+  abort "`#{ARGV.first}' does not exist."
+elsif !File.directory?(ARGV.first)
+  abort "`#{ARGV.first}' is not a directory."
+elsif ARGV.length > 1
+  abort "Too many arguments; please specify only the directory to capify."
+end
+
+def unindent(string)
+  indentation = string[/\A\s*/]
+  string.strip.gsub(/^#{indentation}/, "")
+end
+
+files = {
+  "Capfile" => unindent(<<-FILE),
+
+    load 'deploy'
+    load 'deploy/bundler'
+
+    # Uncomment if you are using Rails' asset pipeline
+    # load 'deploy/assets'
+
+    load 'config/deploy'
+  FILE
+
+  "config/deploy.rb" => 'set :application, "set your application name here"
+set :repository,  "set your repository location here"
+
+# set :scm, :git # :git is the default, or set :none to disable
+
+server "host.example.com"
+
+# if you want to clean up old releases on each deploy uncomment this:
+# after "deploy:restart", "deploy:cleanup"
+
+# If you are using Passenger, uncomment this:
+# namespace :deploy do
+#   task :start do ; end
+#   task :stop do ; end
+#   task :restart do
+#     run "#{try_sudo} touch #{File.join(current_path,\'tmp\',\'restart.txt\')}"
+#   end
+# end'}
+
+base = ARGV.shift
+
+files.each do |file, content|
+  file = File.join(base, file)
+
+  if File.exist?(file)
+    warn "[skip] '#{file}' already exists"
+  elsif File.exist?(file.downcase)
+    warn "[skip] '#{file.downcase}' exists, which could conflict with `#{file}'"
+  else
+    unless File.exist?(File.dirname(file))
+      puts "[add] making directory '#{File.dirname(file)}'"
+      FileUtils.mkdir(File.dirname(file))
+    end
+
+    puts "[add] writing '#{file}'"
+    File.open(file, "w") { |f| f.write(content) }
+  end
+end
+
+puts "[done] capified!"

data/bin/min

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+
+require 'minestrone/cli'
+
+Minestrone::CLI.execute

data/docs/lib-codebase-map.md

@@ -0,0 +1,162 @@
+# Minestrone `lib` Codebase Map
+
+This document maps the files under `lib/`, the classes/modules they define, what they are for, and the main internal dependencies between them.
+
+## High-Level Shape
+
+Minestrone is centered on `Minestrone::Configuration`. The root file loads the configuration DSL, extension/plugin support, and a small `String` helper. `Configuration` mixes in modules for variables, task namespaces, callbacks, single-server selection, recipe loading, SSH connection management, command execution, file transfer, and inspection helpers.
+
+Built-in recipes live under `lib/minestrone/recipes`. The deploy recipe composes two plugin families:
+
+- `Minestrone::Deploy::SCM`: source control adapters that return shell commands. This tree currently keeps only Git and the no-SCM local-copy adapter.
+- `Minestrone::Deploy::Strategy`: deployment strategies that execute SCM commands locally or remotely.
+
+## File Inventory
+
+| File | Classes/modules defined | Purpose | Main internal dependencies |
+| --- | --- | --- | --- |
+| `lib/minestrone.rb` | none directly | Main library entry point. Loads the configuration DSL, plugin extension system, and string helper. | `configuration`, `extensions`, `ext/string` |
+| `lib/minestrone/callback.rb` | `Minestrone::Callback`, `ProcCallback`, `TaskCallback` | Represents callbacks registered around task lifecycle events. `ProcCallback` calls a block, `TaskCallback` executes another Minestrone task and prevents direct self-recursion. | Used by `configuration/callbacks` |
+| `lib/minestrone/cli.rb` | `Minestrone::CLI` | Command-line facade that stores raw args, exposes UI prompts, turns parsed options into a `Configuration`, loads recipes, fires lifecycle hooks, executes requested actions, and handles top-level errors. | `minestrone`, `cli/help`, `cli/options`, `configuration`, `highline` |
+| `lib/minestrone/cli/help.rb` | `Minestrone::CLI::Help` | Overrides CLI action execution for `-T` task listing and `-e` task explanation. Formats long help text. | Mixed into `CLI`; uses `TaskDefinition` data through `Configuration#task_list` and `#find_task` |
+| `lib/minestrone/cli/help.txt` | none | ERB-like help text used by `CLI::Help#long_help`. | Read by `cli/help` |
+| `lib/minestrone/cli/options.rb` | `Minestrone::CLI::Options` | Defines `OptionParser` switches, default config discovery, environment variable extraction, and simple value coercion for `-s` and `-S`. | Mixed into `CLI`; requires `optparse`; uses `Logger`, `Version`, `CLI.password_prompt` |
+| `lib/minestrone/command.rb` | `Minestrone::Command` | Single-session remote command runner. Opens one SSH command channel, handles stdout/stderr callbacks, optional pty, environment injection, placeholder replacement, and remote command errors. | `errors`, `processable`, `Configuration.default_io_proc`, SSH session from `connections` |
+| `lib/minestrone/configuration.rb` | `Minestrone::Configuration` | Central DSL object. Owns logger/debug/dry-run state, explicitly calls each included module's initialization hook, mixes in all configuration and action modules, and unblocks namespace method shadowing. | `logger`; all `configuration/*`; `configuration/actions/*` |
+| `lib/minestrone/configuration/actions/file_transfer.rb` | `Minestrone::Configuration::Actions::FileTransfer` | Adds `put`, `get`, `upload`, `download`, and `transfer` DSL actions. Delegates actual work to `Minestrone::Transfer`. | `transfer`, `Connections#execute_on_server`, `Connections#session`, `run` |
+| `lib/minestrone/configuration/actions/inspect.rb` | `Minestrone::Configuration::Actions::Inspect` | Adds `stream` and `capture` actions for running commands and consuming streamed or captured single-server output. | `errors`, `Invocation#invoke_command`, `sudo` |
+| `lib/minestrone/configuration/actions/invocation.rb` | `Minestrone::Configuration::Actions::Invocation` | Adds `run`, `invoke_command`, `sudo`, command defaults, sudo prompt handling, and debug prompting. Converts DSL command calls into sequential `Command` execution. | `command`, `Servers#active_server`, `Connections#execute_on_server`, `CLI.debug_prompt`, `Variables` |
+| `lib/minestrone/configuration/alias_task.rb` | `Minestrone::Configuration::AliasTask` | Adds `alias_task`, duplicating an existing task under a new name. | `Namespaces#find_task`, `#define_task`, `NoSuchTaskError` |
+| `lib/minestrone/configuration/callbacks.rb` | `Minestrone::Configuration::Callbacks` | Adds task lifecycle hooks: `before`, `after`, `on`, `trigger`. Wraps task invocation so callbacks fire around every direct task call. | `callback`, `Execution#invoke_task_directly`, `Execution#find_and_execute_task` |
+| `lib/minestrone/configuration/connections.rb` | `Minestrone::Configuration::Connections` | Manages the single SSH session, connection failure state, single-server connection establishment/teardown, and continuing after remote errors where requested. | `ssh`, `errors`, `Servers#active_server`, `Execution#current_task` |
+| `lib/minestrone/configuration/execution.rb` | `Minestrone::Configuration::Execution`, `TaskCallFrame` | Runs tasks, tracks the current task stack, implements transactions and `on_rollback`, and locates/executes tasks by name. | `errors`, `Namespaces`, `Callbacks` |
+| `lib/minestrone/configuration/loading.rb` | `Minestrone::Configuration::Loading`, `Loading::ClassMethods` | Loads recipes from files, strings, or procs. Provides a Minestrone-aware `require` that lets multiple configuration instances reload recipe DSL effects. | Used by `CLI`, recipes, extensions |
+| `lib/minestrone/configuration/log_formatters.rb` | `Minestrone::Configuration::LogFormatters` | DSL for adding logger formatters and disabling formatting. | `logger` |
+| `lib/minestrone/configuration/namespaces.rb` | `Minestrone::Configuration::Namespaces`, `Namespaces::Namespace`, `Kernel.method_added` hook | Implements `namespace`, `task`, `desc`, task lookup, namespace lookup, default tasks, and nested namespace forwarding to parent configuration. | `task_definition`, `alias_task`, `execution` |
+| `lib/minestrone/configuration/servers.rb` | `Minestrone::Configuration::Servers` | Adds the single-host `server` DSL and resolves the configured server, with `HOST` as a one-host environment override. | `ServerDefinition`, `errors` |
+| `lib/minestrone/configuration/variables.rb` | `Minestrone::Configuration::Variables` | Configuration variables with lazy proc evaluation, reset/unset, `fetch`, `[]`, and variable-backed `method_missing`. | Used by nearly every DSL and recipe file |
+| `lib/minestrone/errors.rb` | `Minestrone::Error`, `CaptureError`, `NoSuchTaskError`, `NoMatchingServersError`, `RemoteError`, `ConnectionError`, `TransferError`, `CommandError`, `LocalArgumentError` | Shared exception hierarchy. Remote errors carry affected hosts. | Used by command, transfer, connections, execution, recipes, deploy adapters |
+| `lib/minestrone/ext/string.rb` | reopens `String` | Adds `String#compact`, collapsing whitespace. Used to make heredoc shell commands one line. | Used by deploy assets and recipe command heredocs |
+| `lib/minestrone/extensions.rb` | `Minestrone::ExtensionProxy`, `Minestrone::EXTENSIONS`, plugin methods | Plugin registration system. Adds proxy methods to `Configuration` instances and delegates unknown plugin method calls back to the configuration. | `Configuration`, `Error` |
+| `lib/minestrone/logger.rb` | `Minestrone::Logger` | Level-based logger with TTY color/style formatters, timestamp/prepend/append/replace support, and default formatter registration. | Used by `Configuration`, CLI options, command/transfer/strategy/scm code |
+| `lib/minestrone/processable.rb` | `Minestrone::Processable`, `Processable::SessionAssociation` | Shared single-session Net::SSH event loop helper. Preprocesses/postprocesses the session with `IO.select` and associates raised errors with that session. | Included by `Command`, `Transfer` |
+| `lib/minestrone/recipes/deploy.rb` | recipe methods and tasks only | Primary deployment recipe. Defines deploy variables, helpers (`scm_default`, `depend`, `with_env`, `run_locally`, `try_sudo`, `try_runner`), and tasks for setup, update, update_code, symlinks, upload, rollback, migrations, cleanup, checks, cold deploy, start/stop, pending diff/log, and web maintenance mode. Defaults to Git when `.git` exists and `none` otherwise. | `deploy/scm`, `deploy/strategy`, `dependencies`, `Command`/`Transfer` through configuration actions |
+| `lib/minestrone/recipes/deploy/assets.rb` | recipe methods and tasks only | Rails asset-pipeline extension. Hooks into deploy lifecycle to symlink shared assets, precompile, maintain manifest mtimes, clean expired assets, clean all assets, and roll back manifests. | Loads `deploy`; `json`, `yaml` via deploy, `Set` via deploy, `String#compact`, callbacks/tasks/actions |
+| `lib/minestrone/recipes/deploy/dependencies.rb` | `Minestrone::Deploy::Dependencies` | Aggregates local and remote dependency checks and reports pass/fail. | `local_dependency`, `remote_dependency` |
+| `lib/minestrone/recipes/deploy/local_dependency.rb` | `Minestrone::Deploy::LocalDependency` | Checks local command availability in `PATH`. | Used by `Dependencies`, `Strategy::Copy#check!` |
+| `lib/minestrone/recipes/deploy/remote_dependency.rb` | `Minestrone::Deploy::RemoteDependency` | Checks remote directories, files, writability, commands, gems, deb/rpm packages, and expected command output. | `errors`, `Configuration#invoke_command`, `CommandError` |
+| `lib/minestrone/recipes/deploy/scm.rb` | `Minestrone::Deploy::SCM` | Factory module for dynamic SCM adapter loading by name. | Dynamic requires `deploy/scm/<name>`; raises `Minestrone::Error` |
+| `lib/minestrone/recipes/deploy/scm/base.rb` | `Minestrone::Deploy::SCM::Base`, `Base::LocalProxy` | Abstract SCM adapter API. Provides local-mode variable lookup, command construction, default command handling, logging, and abstract checkout/sync/diff/log/query hooks. | `Configuration` variables and logger; subclassed by all SCM adapters |
+| `lib/minestrone/recipes/deploy/scm/git.rb` | `Minestrone::Deploy::SCM::Git` | Git adapter. Supports clone/export/sync, branches/remotes, shallow clones, submodules, diff/log, SHA resolution, and prompt responses for passwords, passphrases, host keys, and certs. | `scm/base`, `CLI.password_prompt` |
+| `lib/minestrone/recipes/deploy/scm/none.rb` | `Minestrone::Deploy::SCM::None` | Non-SCM adapter for copying a local directory. Intended for `deploy_via :copy`; no real history support. | `scm/base` |
+| `lib/minestrone/recipes/deploy/strategy.rb` | `Minestrone::Deploy::Strategy` | Factory module for dynamic deploy strategy loading by name. | Dynamic requires `deploy/strategy/<name>`; raises `Minestrone::Error` |
+| `lib/minestrone/recipes/deploy/strategy/base.rb` | `Minestrone::Deploy::Strategy::Base` | Abstract deployment strategy API. Provides deploy check defaults, configuration method delegation, local `system` logging, and real revision access. | `deploy/dependencies`, `logger`, `Configuration` DSL |
+| `lib/minestrone/recipes/deploy/strategy/copy.rb` | `Minestrone::Deploy::Strategy::Copy`, `Copy::Compression` | Local-copy strategy. Checks out/export locally or refreshes a local cache, optionally builds, excludes files, archives, uploads, extracts remotely, and cleans staging artifacts. | `strategy/base`, `fileutils`, `tempfile`, `LocalDependency`, `FileTransfer#upload`, SCM local proxy |
+| `lib/minestrone/recipes/deploy/strategy/remote_cache.rb` | `Minestrone::Deploy::Strategy::RemoteCache` | Remote strategy maintaining a shared cached checkout under `shared_path`, then copying/rsyncing it to each release. Handles SCM prompt filtering and writes `REVISION`. | `strategy/base`, SCM `sync`/`checkout`/`handle_data`, remote `rsync` when exclusions exist |
+| `lib/minestrone/recipes/standard.rb` | recipe tasks only | Standard recipe loaded by CLI. Defines `invoke` for one-off remote commands. | `configuration/actions/invocation` |
+| `lib/minestrone/recipes/templates/maintenance.rhtml` | none | ERB/XHTML maintenance-page template used by `deploy:web:disable`. | Read by `recipes/deploy.rb` |
+| `lib/minestrone/server_definition.rb` | `Minestrone::ServerDefinition` | Parses and stores `user@host:port` plus server options. Provides comparison, equality/hash, default user, and string rendering. | Used by `Servers`, `SSH`, `Connections` |
+| `lib/minestrone/ssh.rb` | `Minestrone::SSH`, `SSH::Server` | SSH connection helper. Applies the originating `ServerDefinition` to the Net::SSH session and builds public-key-only connection options. | `net/ssh`, `ServerDefinition` |
+| `lib/minestrone/task_definition.rb` | `Minestrone::TaskDefinition` | Stores task metadata: name, namespace, options, body, description, and rollback behavior. Formats descriptions and computes fully qualified names. | `server_definition`; used by `configuration/namespaces` and `execution` |
+| `lib/minestrone/transfer.rb` | `Minestrone::Transfer`, `Transfer::SFTPTransferWrapper` | Single-session upload/download engine over SFTP or SCP. Normalizes host placeholders and IOs, tracks transfer failure, delegates event processing to `Processable`, and raises `TransferError`. | `net/scp`, `net/sftp`, `processable`, `errors`, SSH session |
+| `lib/minestrone/version.rb` | `Minestrone::Version`, `Minestrone::VERSION` | Version constants and string rendering for Minestrone 2.15.11. | Used by CLI `--version` |
+
+## Dependency Graph
+
+This graph shows the main internal runtime clusters rather than every standard-library require.
+
+Saved image: [docs/lib-dependency-graph.svg](lib-dependency-graph.svg)
+
+```mermaid
+flowchart TD
+  root["lib/minestrone.rb"] --> config["Minestrone::Configuration"]
+  root --> extensions["Minestrone.plugin / ExtensionProxy"]
+  root --> string_ext["String#compact"]
+
+  cli["Minestrone::CLI"] --> config
+  cli --> cli_options["CLI::Options"]
+  cli --> cli_help["CLI::Help"]
+
+  config --> variables["Configuration::Variables"]
+  config --> namespaces["Configuration::Namespaces"]
+  config --> execution["Configuration::Execution"]
+  config --> callbacks["Configuration::Callbacks"]
+  config --> servers_mod["Configuration::Servers"]
+  config --> loading["Configuration::Loading"]
+  config --> connections["Configuration::Connections"]
+  config --> invocation["Actions::Invocation"]
+  config --> transfer_actions["Actions::FileTransfer"]
+  config --> inspect_actions["Actions::Inspect"]
+  config --> log_formatters["Configuration::LogFormatters"]
+
+  namespaces --> task_definition["TaskDefinition"]
+  servers_mod --> server_definition["ServerDefinition"]
+  connections --> ssh["SSH"]
+  connections --> errors["Errors"]
+  invocation --> command["Command"]
+  transfer_actions --> transfer["Transfer"]
+  command --> processable["Processable"]
+  transfer --> processable
+  callbacks --> callback_classes["Callback / ProcCallback / TaskCallback"]
+  execution --> callbacks
+  execution --> namespaces
+
+  deploy_recipe["recipes/deploy.rb"] --> scm_factory["Deploy::SCM factory"]
+  deploy_recipe --> strategy_factory["Deploy::Strategy factory"]
+  deploy_recipe --> config
+  assets_recipe["recipes/deploy/assets.rb"] --> deploy_recipe
+
+  scm_factory --> scm_base["SCM::Base"]
+  scm_base --> scm_adapters["Git, None"]
+  strategy_factory --> strategy_base["Strategy::Base"]
+  strategy_base --> dependencies["Deploy::Dependencies"]
+  dependencies --> local_dep["LocalDependency"]
+  dependencies --> remote_dep["RemoteDependency"]
+  strategy_base --> strategies["Copy, RemoteCache"]
+  strategies --> scm_adapters
+  strategies --> config
+```
+
+## Static/Internal Require And Load Dependencies
+
+These are the code-level edges visible from `require` and `load`, excluding Ruby standard-library and gem dependencies unless they are important to the file's role.
+
+| File | Internal files loaded directly |
+| --- | --- |
+| `lib/minestrone.rb` | `minestrone/configuration`, `minestrone/extensions`, `minestrone/ext/string` |
+| `lib/minestrone/cli.rb` | `minestrone`, `minestrone/cli/help`, `minestrone/cli/options`, `minestrone/configuration` |
+| `lib/minestrone/cli/options.rb` | dynamically `minestrone/version` for `--version` |
+| `lib/minestrone/command.rb` | `minestrone/errors`, `minestrone/processable` |
+| `lib/minestrone/configuration.rb` | `minestrone/logger`; all `minestrone/configuration/*`; all `minestrone/configuration/actions/*` |
+| `lib/minestrone/configuration/actions/file_transfer.rb` | `minestrone/transfer` |
+| `lib/minestrone/configuration/actions/inspect.rb` | `minestrone/errors` |
+| `lib/minestrone/configuration/actions/invocation.rb` | `minestrone/command` |
+| `lib/minestrone/configuration/callbacks.rb` | `minestrone/callback` |
+| `lib/minestrone/configuration/connections.rb` | `minestrone/ssh`, `minestrone/errors` |
+| `lib/minestrone/configuration/execution.rb` | `minestrone/errors` |
+| `lib/minestrone/configuration/namespaces.rb` | `minestrone/configuration/alias_task`, `minestrone/task_definition` |
+| `lib/minestrone/configuration/servers.rb` | `minestrone/server_definition`, `minestrone/errors` |
+| `lib/minestrone/recipes/deploy.rb` | `minestrone/recipes/deploy/scm`, `minestrone/recipes/deploy/strategy` |
+| `lib/minestrone/recipes/deploy/assets.rb` | `load 'deploy'` unless `_cset` already exists |
+| `lib/minestrone/recipes/deploy/dependencies.rb` | `minestrone/recipes/deploy/local_dependency`, `minestrone/recipes/deploy/remote_dependency` |
+| `lib/minestrone/recipes/deploy/remote_dependency.rb` | `minestrone/errors` |
+| `lib/minestrone/recipes/deploy/scm.rb` | dynamically `minestrone/recipes/deploy/scm/<name>` |
+| `lib/minestrone/recipes/deploy/scm/git.rb` | `minestrone/recipes/deploy/scm/base` |
+| `lib/minestrone/recipes/deploy/scm/none.rb` | `minestrone/recipes/deploy/scm/base` |
+| `lib/minestrone/recipes/deploy/strategy.rb` | dynamically `minestrone/recipes/deploy/strategy/<name>` |
+| `lib/minestrone/recipes/deploy/strategy/base.rb` | `minestrone/recipes/deploy/dependencies` |
+| `lib/minestrone/recipes/deploy/strategy/remote_cache.rb` | `minestrone/recipes/deploy/strategy/base` |
+| `lib/minestrone/recipes/deploy/strategy/copy.rb` | `minestrone/recipes/deploy/strategy/base` |
+| `lib/minestrone/task_definition.rb` | `minestrone/server_definition` |
+| `lib/minestrone/transfer.rb` | `minestrone/processable` |
+
+## Runtime Usage Notes
+
+- `Configuration` is the central dependency hub. Most recipe and strategy code calls into it through DSL methods mixed in from its modules.
+- `Command` and `Transfer` depend on `Processable` because they share the same single-session Net::SSH event-loop pattern.
+- `ServerDefinition` is the single configured server identity object. It carries host/user/port/options into the `HOST` override path, SSH connection setup, command placeholders, transfer logging, and error reporting.
+- `Callbacks` wraps `Execution#invoke_task_directly`; task lifecycle hooks therefore apply to all direct task execution paths, including CLI actions and recipe-invoked task aliases.
+- `Deploy::SCM` and `Deploy::Strategy` are factories. They load adapter files by name and instantiate classes from generated constant names.
+- SCM adapters generally do not execute commands. They return shell command strings and prompt handlers. Strategies decide whether those commands run locally, remotely, through caches, or through uploaded archives.
+- `Strategy::Copy` is the main bridge from local SCM commands to remote deployment: it uses the SCM's local proxy, local filesystem staging, compression utilities, `upload`, and remote decompression.
+- `recipes/deploy/assets.rb` is not a class extension. It is a recipe that mutates the current configuration by setting defaults, registering callbacks, adding helper methods, and defining `deploy:assets:*` tasks.

data/docs/lib-dependency-graph.svg

@@ -0,0 +1,129 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg xmlns="http://www.w3.org/2000/svg" width="1400" height="960" viewBox="0 0 1400 960" role="img" aria-labelledby="title desc">
+<title id="title">Minestrone lib dependency graph</title>
+<desc id="desc">Dependency graph generated from docs/lib-codebase-map.md Mermaid chart.</desc>
+<defs>
+  <marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
+    <path d="M 0 0 L 10 5 L 0 10 z" fill="#516071"/>
+  </marker>
+  <filter id="shadow" x="-10%" y="-10%" width="120%" height="130%">
+    <feDropShadow dx="0" dy="2" stdDeviation="2" flood-color="#0f172a" flood-opacity="0.12"/>
+  </filter>
+</defs>
+<rect width="100%" height="100%" fill="#f8fafc"/>
+<text x="32" y="34" font-family="-apple-system, BlinkMacSystemFont, Segoe UI, sans-serif" font-size="22" font-weight="700" fill="#0f172a">Minestrone lib dependency graph</text>
+<text x="32" y="58" font-family="-apple-system, BlinkMacSystemFont, Segoe UI, sans-serif" font-size="13" fill="#64748b">Generated from docs/lib-codebase-map.md</text>
+<g fill="none" stroke="#516071" stroke-width="1.35" stroke-opacity="0.72" marker-end="url(#arrow)">
+  <path d="M 260 170 C 300 170, 300 170, 340 170"/>
+  <path d="M 260 170 C 300 170, 300 85, 340 85"/>
+  <path d="M 260 170 C 300 170, 300 255, 340 255"/>
+  <path d="M 260 340 C 300 340, 300 170, 340 170"/>
+  <path d="M 260 340 C 300 340, 300 340, 340 340"/>
+  <path d="M 260 340 C 300 340, 300 425, 340 425"/>
+  <path d="M 260 340 C 300 340, 300 510, 340 510"/>
+  <path d="M 600 170 C 640 170, 640 85, 680 85"/>
+  <path d="M 600 170 C 640 170, 640 145, 680 145"/>
+  <path d="M 600 170 C 640 170, 640 205, 680 205"/>
+  <path d="M 600 170 C 640 170, 640 265, 680 265"/>
+  <path d="M 600 170 C 640 170, 640 325, 680 325"/>
+  <path d="M 600 170 C 640 170, 640 385, 680 385"/>
+  <path d="M 600 170 C 640 170, 640 445, 680 445"/>
+  <path d="M 600 170 C 640 170, 640 505, 680 505"/>
+  <path d="M 600 170 C 640 170, 640 565, 680 565"/>
+  <path d="M 600 170 C 640 170, 640 625, 680 625"/>
+  <path d="M 940 145 C 980 145, 980 145, 1020 145"/>
+  <path d="M 940 325 C 980 325, 980 265, 1020 265"/>
+  <path d="M 940 385 C 980 385, 980 325, 1020 325"/>
+  <path d="M 940 385 C 980 385, 980 385, 1020 385"/>
+  <path d="M 940 445 C 980 445, 980 445, 1020 445"/>
+  <path d="M 940 505 C 980 505, 980 505, 1020 505"/>
+  <path d="M 1280 505 C 1300 505, 1300 565, 1020 565"/>
+  <path d="M 600 510 C 640 510, 640 565, 1020 565"/>
+  <path d="M 600 510 C 640 510, 640 445, 1020 445"/>
+  <path d="M 940 265 C 980 265, 980 625, 1020 625"/>
+  <path d="M 940 205 C 960 205, 960 265, 680 265"/>
+  <path d="M 260 595 C 300 595, 300 680, 340 680"/>
+  <path d="M 260 595 C 300 595, 300 765, 340 765"/>
+  <path d="M 260 595 C 300 595, 300 170, 340 170"/>
+  <path d="M 260 680 C 300 680, 300 595, 20 595"/>
+  <path d="M 260 765 C 300 765, 300 510, 340 510"/>
+  <path d="M 600 680 C 640 680, 640 680, 680 680"/>
+  <path d="M 940 680 C 980 680, 980 740, 1020 740"/>
+  <path d="M 600 765 C 640 765, 640 800, 680 800"/>
+  <path d="M 940 800 C 980 800, 980 800, 1020 800"/>
+  <path d="M 1280 800 C 1320 800, 1320 680, 1020 680"/>
+  <path d="M 1280 800 C 1320 800, 1320 170, 340 170"/>
+</g>
+<g font-family="-apple-system, BlinkMacSystemFont, Segoe UI, sans-serif">
+  <rect x="20" y="141" width="240" height="58" rx="7" fill="#dcfce7" stroke="#16a34a" stroke-width="1.2" filter="url(#shadow)"/>
+  <text x="140" y="170" text-anchor="middle" dominant-baseline="middle" font-size="13" font-weight="650" fill="#0f172a">lib/minestrone.rb</text>
+  <rect x="340" y="141" width="260" height="58" rx="7" fill="#e0f2fe" stroke="#0284c7" stroke-width="1.2" filter="url(#shadow)"/>
+  <text x="470" y="170" text-anchor="middle" dominant-baseline="middle" font-size="13" font-weight="650" fill="#0f172a">Minestrone::Configuration</text>
+  <rect x="340" y="56" width="260" height="58" rx="7" fill="#ffffff" stroke="#cbd5e1" stroke-width="1.2" filter="url(#shadow)"/>
+  <text x="470" y="85" text-anchor="middle" dominant-baseline="middle" font-size="13" fill="#0f172a">Minestrone.plugin / ExtensionProxy</text>
+  <rect x="340" y="226" width="260" height="58" rx="7" fill="#ffffff" stroke="#cbd5e1" stroke-width="1.2" filter="url(#shadow)"/>
+  <text x="470" y="255" text-anchor="middle" dominant-baseline="middle" font-size="13" fill="#0f172a">String#compact</text>
+  <rect x="20" y="311" width="240" height="58" rx="7" fill="#ffffff" stroke="#cbd5e1" stroke-width="1.2" filter="url(#shadow)"/>
+  <text x="140" y="340" text-anchor="middle" dominant-baseline="middle" font-size="13" fill="#0f172a">Minestrone::CLI</text>
+  <rect x="340" y="311" width="260" height="58" rx="7" fill="#ffffff" stroke="#cbd5e1" stroke-width="1.2" filter="url(#shadow)"/>
+  <text x="470" y="340" text-anchor="middle" dominant-baseline="middle" font-size="13" fill="#0f172a">CLI::Execute</text>
+  <rect x="340" y="396" width="260" height="58" rx="7" fill="#ffffff" stroke="#cbd5e1" stroke-width="1.2" filter="url(#shadow)"/>
+  <text x="470" y="425" text-anchor="middle" dominant-baseline="middle" font-size="13" fill="#0f172a">CLI::Options</text>
+  <rect x="340" y="481" width="260" height="58" rx="7" fill="#ffffff" stroke="#cbd5e1" stroke-width="1.2" filter="url(#shadow)"/>
+  <text x="470" y="510" text-anchor="middle" dominant-baseline="middle" font-size="13" fill="#0f172a">CLI::Help / CLI::UI</text>
+  <rect x="680" y="56" width="260" height="58" rx="7" fill="#ffffff" stroke="#cbd5e1" stroke-width="1.2" filter="url(#shadow)"/>
+  <text x="810" y="85" text-anchor="middle" dominant-baseline="middle" font-size="13" fill="#0f172a">Configuration::Variables</text>
+  <rect x="680" y="116" width="260" height="58" rx="7" fill="#ffffff" stroke="#cbd5e1" stroke-width="1.2" filter="url(#shadow)"/>
+  <text x="810" y="145" text-anchor="middle" dominant-baseline="middle" font-size="13" fill="#0f172a">Configuration::Namespaces</text>
+  <rect x="680" y="176" width="260" height="58" rx="7" fill="#ffffff" stroke="#cbd5e1" stroke-width="1.2" filter="url(#shadow)"/>
+  <text x="810" y="205" text-anchor="middle" dominant-baseline="middle" font-size="13" fill="#0f172a">Configuration::Execution</text>
+  <rect x="680" y="236" width="260" height="58" rx="7" fill="#ffffff" stroke="#cbd5e1" stroke-width="1.2" filter="url(#shadow)"/>
+  <text x="810" y="265" text-anchor="middle" dominant-baseline="middle" font-size="13" fill="#0f172a">Configuration::Callbacks</text>
+  <rect x="680" y="296" width="260" height="58" rx="7" fill="#ffffff" stroke="#cbd5e1" stroke-width="1.2" filter="url(#shadow)"/>
+  <text x="810" y="325" text-anchor="middle" dominant-baseline="middle" font-size="13" fill="#0f172a">Configuration::Servers</text>
+  <rect x="680" y="356" width="260" height="58" rx="7" fill="#ffffff" stroke="#cbd5e1" stroke-width="1.2" filter="url(#shadow)"/>
+  <text x="810" y="385" text-anchor="middle" dominant-baseline="middle" font-size="13" fill="#0f172a">Configuration::Connections</text>
+  <rect x="680" y="416" width="260" height="58" rx="7" fill="#ffffff" stroke="#cbd5e1" stroke-width="1.2" filter="url(#shadow)"/>
+  <text x="810" y="445" text-anchor="middle" dominant-baseline="middle" font-size="13" fill="#0f172a">Actions::Invocation</text>
+  <rect x="680" y="476" width="260" height="58" rx="7" fill="#ffffff" stroke="#cbd5e1" stroke-width="1.2" filter="url(#shadow)"/>
+  <text x="810" y="505" text-anchor="middle" dominant-baseline="middle" font-size="13" fill="#0f172a">Actions::FileTransfer</text>
+  <rect x="680" y="536" width="260" height="58" rx="7" fill="#ffffff" stroke="#cbd5e1" stroke-width="1.2" filter="url(#shadow)"/>
+  <text x="810" y="565" text-anchor="middle" dominant-baseline="middle" font-size="13" fill="#0f172a">Actions::Inspect</text>
+  <rect x="680" y="596" width="260" height="58" rx="7" fill="#ffffff" stroke="#cbd5e1" stroke-width="1.2" filter="url(#shadow)"/>
+  <text x="810" y="625" text-anchor="middle" dominant-baseline="middle" font-size="13" fill="#0f172a">Configuration::Loading / LogFormatters</text>
+  <rect x="1020" y="116" width="260" height="58" rx="7" fill="#ffffff" stroke="#cbd5e1" stroke-width="1.2" filter="url(#shadow)"/>
+  <text x="1150" y="145" text-anchor="middle" dominant-baseline="middle" font-size="13" fill="#0f172a">TaskDefinition</text>
+  <rect x="1020" y="236" width="260" height="58" rx="7" fill="#ffffff" stroke="#cbd5e1" stroke-width="1.2" filter="url(#shadow)"/>
+  <text x="1150" y="265" text-anchor="middle" dominant-baseline="middle" font-size="13" fill="#0f172a">Callback / ProcCallback / TaskCallback</text>
+  <rect x="1020" y="296" width="260" height="58" rx="7" fill="#ffffff" stroke="#cbd5e1" stroke-width="1.2" filter="url(#shadow)"/>
+  <text x="1150" y="325" text-anchor="middle" dominant-baseline="middle" font-size="13" fill="#0f172a">ServerDefinition</text>
+  <rect x="1020" y="356" width="260" height="58" rx="7" fill="#ffffff" stroke="#cbd5e1" stroke-width="1.2" filter="url(#shadow)"/>
+  <text x="1150" y="385" text-anchor="middle" dominant-baseline="middle" font-size="13" fill="#0f172a">SSH / Errors</text>
+  <rect x="1020" y="416" width="260" height="58" rx="7" fill="#ffffff" stroke="#cbd5e1" stroke-width="1.2" filter="url(#shadow)"/>
+  <text x="1150" y="445" text-anchor="middle" dominant-baseline="middle" font-size="13" fill="#0f172a">Command</text>
+  <rect x="1020" y="476" width="260" height="58" rx="7" fill="#ffffff" stroke="#cbd5e1" stroke-width="1.2" filter="url(#shadow)"/>
+  <text x="1150" y="505" text-anchor="middle" dominant-baseline="middle" font-size="13" fill="#0f172a">Transfer</text>
+  <rect x="1020" y="536" width="260" height="58" rx="7" fill="#ffffff" stroke="#cbd5e1" stroke-width="1.2" filter="url(#shadow)"/>
+  <text x="1150" y="565" text-anchor="middle" dominant-baseline="middle" font-size="13" fill="#0f172a">Processable</text>
+  <rect x="20" y="566" width="240" height="58" rx="7" fill="#e0f2fe" stroke="#0284c7" stroke-width="1.2" filter="url(#shadow)"/>
+  <text x="140" y="595" text-anchor="middle" dominant-baseline="middle" font-size="13" font-weight="650" fill="#0f172a">recipes/deploy.rb</text>
+  <rect x="340" y="651" width="260" height="58" rx="7" fill="#ffffff" stroke="#cbd5e1" stroke-width="1.2" filter="url(#shadow)"/>
+  <text x="470" y="680" text-anchor="middle" dominant-baseline="middle" font-size="13" fill="#0f172a">Deploy::SCM factory</text>
+  <rect x="340" y="736" width="260" height="58" rx="7" fill="#ffffff" stroke="#cbd5e1" stroke-width="1.2" filter="url(#shadow)"/>
+  <text x="470" y="765" text-anchor="middle" dominant-baseline="middle" font-size="13" fill="#0f172a">Deploy::Strategy factory</text>
+  <rect x="20" y="651" width="240" height="58" rx="7" fill="#ffffff" stroke="#cbd5e1" stroke-width="1.2" filter="url(#shadow)"/>
+  <text x="140" y="680" text-anchor="middle" dominant-baseline="middle" font-size="13" fill="#0f172a">recipes/deploy/assets.rb</text>
+  <rect x="20" y="736" width="240" height="58" rx="7" fill="#ffffff" stroke="#cbd5e1" stroke-width="1.2" filter="url(#shadow)"/>
+  <text x="140" y="765" text-anchor="middle" dominant-baseline="middle" font-size="13" fill="#0f172a">recipes/standard.rb</text>
+  <rect x="680" y="651" width="260" height="58" rx="7" fill="#e0f2fe" stroke="#0284c7" stroke-width="1.2" filter="url(#shadow)"/>
+  <text x="810" y="680" text-anchor="middle" dominant-baseline="middle" font-size="13" font-weight="650" fill="#0f172a">SCM::Base</text>
+  <rect x="1020" y="711" width="260" height="58" rx="7" fill="#ffffff" stroke="#cbd5e1" stroke-width="1.2" filter="url(#shadow)"/>
+  <text x="1150" y="740" text-anchor="middle" dominant-baseline="middle" font-size="13" fill="#0f172a">Git, None</text>
+  <rect x="680" y="771" width="260" height="58" rx="7" fill="#e0f2fe" stroke="#0284c7" stroke-width="1.2" filter="url(#shadow)"/>
+  <text x="810" y="800" text-anchor="middle" dominant-baseline="middle" font-size="13" font-weight="650" fill="#0f172a">Strategy::Base</text>
+  <rect x="1020" y="651" width="260" height="58" rx="7" fill="#ffffff" stroke="#cbd5e1" stroke-width="1.2" filter="url(#shadow)"/>
+  <text x="1150" y="680" text-anchor="middle" dominant-baseline="middle" font-size="13" fill="#0f172a">Deploy::Dependencies</text>
+  <rect x="1020" y="771" width="260" height="58" rx="7" fill="#ffffff" stroke="#cbd5e1" stroke-width="1.2" filter="url(#shadow)"/>
+  <text x="1150" y="800" text-anchor="middle" dominant-baseline="middle" font-size="13" fill="#0f172a">Copy, RemoteCache</text>
+</g>
+</svg>

data/lib/minestrone/callback.rb

@@ -0,0 +1,45 @@
+module Minestrone
+  class Callback
+    attr_reader :source, :options, :only, :except
+
+    def initialize(source, options = {})
+      @source = source
+      @options = options
+      @only = Array(options[:only]).map { |v| v.to_s }
+      @except = Array(options[:except]).map { |v| v.to_s }
+    end
+
+    def applies_to?(task)
+      if task && only.any?
+        return only.include?(task.fully_qualified_name)
+      elsif task && except.any?
+        return !except.include?(task.fully_qualified_name)
+      else
+        return true
+      end
+    end
+  end
+
+  class ProcCallback < Callback
+    def call
+      source.call
+    end
+  end
+
+  class TaskCallback < Callback
+    attr_reader :config
+
+    def initialize(config, source, options = {})
+      super(source, options)
+      @config = config
+    end
+
+    def call
+      config.find_and_execute_task(source)
+    end
+
+    def applies_to?(task)
+      super && (task.nil? || task.fully_qualified_name != source.to_s)
+    end
+  end
+end