capistrano-mise 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: bc195e84e9c69c1058bfbb7899a7335e8b580ae9504e02c9c5568db1962ceb34
+  data.tar.gz: 8f711f539d0897768e79de6cfe86dae6e9e29968615e11b2b6f29286cefdf1b8
+SHA512:
+  metadata.gz: b0e6bc50bc4480368a5a2d82b848862dcbd722a6ff232726829d27a046eaa6919ff850bf635ec18e5cad9964f3c5cf8993accf4ccba1f16d16720f41ce5694ba
+  data.tar.gz: 45037703949301e25d04a3ab70aa7125b0badbad64f78a3675296e8653044dbeb50d4e4584d810706858c48e6c3748c1f6fc0346073d8552cea25eb7983b111e

data/CHANGELOG.md

@@ -0,0 +1,57 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-09-18
+
+First release.
+
+### Added
+- Wraps the commands Capistrano runs on a host with `mise exec --`, pushed onto the
+  front of SSHKit's per-command prefix list so that a prefix another plugin
+  contributed — `capistrano-bundler`'s `bundle exec` — still applies.
+- `mise:check`, after `deploy:check`, which stops the deploy if mise is not
+  executable where `:mise_path` says it is.
+- `mise:install`, after `deploy:updating`, which runs `mise install` in the new
+  release. It installs the tools mise manages, not mise itself.
+- Settings: `:mise_path` (default `$HOME/.local/bin/mise`), `:mise_map_bins`
+  (default `%w[rake gem bundle ruby rails]`) and `:mise_roles` (default `:all`).
+- `MISE_EXEC_AUTO_INSTALL=0`, so a missing tool surfaces as a failure from
+  `mise:install` rather than as a silent multi-minute build inside an unrelated
+  command.
+- A warning when a release carries an idiomatic version file such as
+  `.ruby-version` but no mise config of its own, since mise does not read those
+  unless you opt in per tool.
+- A clear error when `capistrano/mise` is required before `capistrano/deploy`,
+  in place of rake's "Don't know how to build task 'deploy:check'".
+
+### Design notes
+- There is deliberately no setting naming a version. The mise config that shipped
+  with the revision is the only source of truth; use mise's own per-environment
+  config files to vary it per host.
+- Commands that do not reach the host through Capistrano — a systemd unit's
+  `ExecStart`, a crontab entry — are outside this plugin's reach and need their
+  own arrangement. The README has the shapes that work.
+- `mise exec` rather than shims or shell activation. Capistrano's SSH connection
+  gets a non-interactive, non-login shell, which reads no profile at all, and
+  mise's activation recomputes the environment when a prompt is displayed — which
+  never happens here. `mise exec` with an absolute path needs neither, and unlike
+  shims it does not require writing to a shared `PATH`.
+
+### Internal
+- The shell fragments live in `Capistrano::Mise::Commands`, apart from the rake
+  file, which cannot be loaded outside a Capfile. They are covered by mutation
+  testing at 100%, enforced in CI.
+- Tasks are covered at the seam that matters for a Capistrano plugin: the
+  commands a task sends to a host, recorded through a stub SSHKit backend.
+- Settings are read outside the `on` block. Inside one, `self` is the SSHKit
+  backend, and the Capistrano DSL is reachable there only because
+  `capistrano/setup` includes it into `Object`.
+
+[Unreleased]: https://github.com/7a6163/capistrano-mise/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/7a6163/capistrano-mise/releases/tag/v0.1.0

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zac
+
+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,115 @@
+# capistrano-mise
+
+Runs Capistrano's remote commands through [mise](https://mise.jdx.dev), so they resolve
+their tool versions from the mise config that shipped with the revision being deployed.
+
+```ruby
+# Gemfile
+gem "capistrano-mise", github: "7a6163/capistrano-mise", require: false
+```
+
+```ruby
+# Capfile — after capistrano/deploy, which defines the tasks this hooks
+require "capistrano/deploy"
+require "capistrano/mise"
+```
+
+That is the whole setup. There is no version to configure: `mise.toml` or `.tool-versions`
+in your repository already says which versions to run, and that file is in the release
+directory by the time anything runs. A setting naming the version would be a second
+source of truth that can silently disagree with the repository, so there isn't one.
+
+**mise must already be installed on your hosts.** Installing it is provisioning's job, the
+same way `capistrano-rbenv` does not install rbenv.
+
+## What it does
+
+- Prefixes the mapped commands with `mise exec --`, so `bundle install` becomes
+  `$HOME/.local/bin/mise exec -- bundle install`. The prefix goes in *front* of any prefix
+  another plugin added, so `capistrano-bundler`'s `bundle exec` still applies.
+- Adds `mise:check` after `deploy:check`, which fails the deploy if mise is not executable
+  where it is expected.
+- Adds `mise:install` after `deploy:updating`, which runs `mise install` in the new release
+  so the versions that revision declares are present before anything tries to use them.
+  This installs the *tools* mise manages, not mise itself — same as the CLI command it
+  is named after.
+- Sets `MISE_EXEC_AUTO_INSTALL=0`. Mise installs missing tools on demand by default, which
+  would bury a multi-minute Ruby build inside whichever command happened to run first;
+  `mise:install` owns installation instead, as a step you can see.
+
+## Settings
+
+| Setting | Default | |
+|---|---|---|
+| `:mise_path` | `$HOME/.local/bin/mise` | Absolute path to the mise binary. A host provisioned from a package manager has it at `/usr/bin/mise` or `/usr/local/bin/mise` and must say so. |
+| `:mise_map_bins` | `%w[rake gem bundle ruby rails]` | Which commands to run through mise. |
+| `:mise_roles` | `:all` | Which roles this applies to. |
+
+`:mise_map_bins` is Ruby-only on purpose. Adding `node` here when your repo does not declare
+node means `mise exec -- node` quietly falls back to whatever node is on the host's `PATH` —
+worse than not mapping it. Add a tool here once the repo declares it:
+
+```ruby
+set :mise_map_bins, fetch(:mise_map_bins) + %w[node npm yarn]
+```
+
+## What it does not do
+
+Capistrano can only wrap the commands it runs itself. Anything else on the host that runs your
+application — a systemd unit's `ExecStart`, a crontab entry, a login shell — never passes
+through Capistrano and is unaffected by this plugin. **A deploy can succeed completely while
+every one of those still runs the wrong Ruby.**
+
+Each needs its own arrangement:
+
+```ini
+# systemd: call mise explicitly, with an absolute path
+ExecStart=/home/deploy/.local/bin/mise exec -- bundle exec puma -C /path/to/puma.rb
+```
+
+```sh
+# login shells (which is what `bash -l -c` in a crontab gets): put mise's shims on PATH,
+# in ~/.profile or /etc/profile.d/mise.sh
+export PATH="$HOME/.local/share/mise/shims:$PATH"
+```
+
+Use shims rather than `eval "$(mise activate bash)"` there: activation recomputes the
+environment when a prompt is displayed, and a cron job never displays one.
+
+## Gotcha: `.ruby-version` alone is not enough
+
+Mise does not read `.ruby-version`, `.nvmrc` and friends unless you opt in per tool, so a
+repository carrying only a `.ruby-version` resolves to no version at all. `mise:install` warns
+when it sees this. Either add a `mise.toml` / `.tool-versions`, or opt in on the host:
+
+```sh
+mise settings add idiomatic_version_file_enable_tools ruby
+```
+
+## Migrating from capistrano-rbenv or capistrano-rvm
+
+Swap the `require`, then move the version declaration out of your deploy config and into the
+repository — `set :rvm_ruby_version, "3.3.12"` becomes a line in `mise.toml` or
+`.tool-versions`. This is the only part that is not mechanical, and it is deliberate.
+
+If your systemd unit was generated by `capistrano3-puma`, its `ExecStart` contains whatever
+prefix your old plugin contributed (`/usr/local/rvm/bin/rvm 3.3.12 do …`) baked in at the time
+it was written. Update it by hand, and delete any `Environment="PATH=…"` line pointing into the
+old version manager's directories — `mise exec` sets up the child's `PATH` itself, and those
+directories are about to stop existing.
+
+## Releasing
+
+Bump `lib/capistrano/mise/version.rb`, commit, then tag:
+
+```sh
+git tag v0.1.0 && git push origin v0.1.0
+```
+
+That fires `.github/workflows/release.yml`, which publishes to RubyGems (over OIDC — there
+is no API key stored anywhere), to GitHub Packages, and as a GitHub Release with the `.gem`
+attached.
+
+## License
+
+MIT.

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/lib/capistrano/mise/commands.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Capistrano
+  module Mise
+    # The shell fragments this plugin sends to a host. Kept apart from the rake
+    # file so they can be loaded, read and mutated on their own: requiring the
+    # rake file outside a Capfile is not possible, because it hooks tasks that
+    # only exist once capistrano/deploy has been loaded.
+    module Commands
+      # Every filename mise looks for in a single directory, from mise's
+      # configuration docs. mise also searches parent directories and a global
+      # config, so a release holding none of these can still resolve a version.
+      CONFIG_FILENAMES = %w[
+        mise.toml mise.local.toml .mise.toml .mise.local.toml
+        mise/config.toml .mise/config.toml
+        .config/mise.toml .config/mise/config.toml
+        .tool-versions
+      ].freeze
+
+      # mise reads idiomatic version files only when opted in per tool, so a
+      # release carrying this and nothing else resolves no version at all.
+      IDIOMATIC_VERSION_FILE = ".ruby-version"
+
+      # extend self, not module_function: module_function copies each method onto
+      # the module's singleton, so a mutation to the instance method would leave
+      # the copy that callers actually reach untouched, and mutant would report
+      # coverage this module does not have.
+      extend self
+
+      # Goes in front of a mapped command. `--` ends mise's own arguments, so a
+      # command that starts with a dash is not read as one of them.
+      def exec_prefix(mise_path)
+        "#{mise_path} exec --"
+      end
+
+      def executable(path)
+        "[ -x #{path} ]"
+      end
+
+      def any_exist(paths)
+        "[ #{paths.map { |path| "-e #{path}" }.join(' -o ')} ]"
+      end
+
+      # Spelled out against the release rather than run inside SSHKit's `within`:
+      # SSHKit hands a string command containing whitespace straight to the shell,
+      # with no cd and no env, so a relative probe would silently inspect the SSH
+      # login directory instead.
+      def config_present(release_path)
+        any_exist(CONFIG_FILENAMES.map { |name| File.join(release_path, name) })
+      end
+
+      def idiomatic_version_file_present(release_path)
+        any_exist([File.join(release_path, IDIOMATIC_VERSION_FILE)])
+      end
+
+      def missing_binary(path, host)
+        "mise is not executable at #{path} on #{host}. Install mise, " \
+          "or set :mise_path if it is installed somewhere else on this host."
+      end
+
+      def idiomatic_version_file_warning
+        "this revision has #{IDIOMATIC_VERSION_FILE} but no mise config of its own. mise does " \
+          "not read idiomatic version files unless you opt in, so unless a parent directory or " \
+          "the global config supplies one, no Ruby version resolves here. Add a mise.toml or " \
+          ".tool-versions, or run: mise settings add idiomatic_version_file_enable_tools ruby"
+      end
+    end
+  end
+end

data/lib/capistrano/mise/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Capistrano
+  module Mise
+    VERSION = "0.1.0".freeze
+  end
+end

data/lib/capistrano/mise.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require "capistrano/mise/version"
+
+load File.expand_path("../tasks/mise.rake", __FILE__)

data/lib/capistrano/tasks/mise.rake

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require "capistrano/mise/commands"
+
+commands = Capistrano::Mise::Commands
+
+namespace :mise do
+  desc "Check that mise is usable on the target hosts"
+  task :check do
+    # Read outside the `on` block: inside it, self is the SSHKit backend, and the
+    # Capistrano DSL is only reachable there because capistrano/setup includes it
+    # into Object. These are settings, not per-host values.
+    path = fetch(:mise_path)
+
+    on release_roles(fetch(:mise_roles)) do |host|
+      next if test commands.executable(path)
+
+      error commands.missing_binary(path, host)
+      exit 1
+    end
+  end
+
+  desc "Install the tool versions this revision declares"
+  task :install do
+    release = release_path
+
+    on release_roles(fetch(:mise_roles)) do
+      unless test commands.config_present(release)
+        warn commands.idiomatic_version_file_warning if test commands.idiomatic_version_file_present(release)
+      end
+
+      within release do
+        execute :mise, :install
+      end
+    end
+  end
+
+  # Runs after the stage task so that stage-level `set` calls have been applied.
+  task :map_bins do
+    # mise installs missing tools on demand by default, which would bury a Ruby
+    # build inside whichever command happened to run first. mise:install owns that.
+    SSHKit.config.default_env["MISE_EXEC_AUTO_INSTALL"] = "0"
+
+    SSHKit.config.command_map[:mise] = fetch(:mise_path)
+
+    # unshift, so a command already carrying a prefix (capistrano-bundler's
+    # `bundle exec`) keeps it and gains mise in front rather than losing it.
+    prefix = commands.exec_prefix(fetch(:mise_path))
+    fetch(:mise_map_bins).uniq.each do |command|
+      SSHKit.config.command_map.prefix[command.to_sym].unshift(prefix)
+    end
+  end
+end
+
+Capistrano::DSL.stages.each do |stage|
+  after stage, "mise:map_bins"
+end
+
+# These hooks need their tasks to exist, so this must be required after
+# capistrano/deploy. Without the guard the failure is "Don't know how to build
+# task 'deploy:check'", which names nothing you would think to look at.
+unless Rake::Task.task_defined?("deploy:check")
+  raise "capistrano/mise must be required after capistrano/deploy in your Capfile."
+end
+
+after "deploy:check", "mise:check"
+
+# deploy:updating, not deploy:updated: capistrano-bundler hooks `before
+# deploy:updated`, and hooks on the same task fire in registration order, which
+# depends on Capfile require order. Hooking the earlier task wins regardless.
+# The release is already populated by then, because git:create_release runs off
+# deploy:new_release_path, a prerequisite of deploy:updating.
+after "deploy:updating", "mise:install"
+
+namespace :load do
+  task :defaults do
+    set :mise_path, "$HOME/.local/bin/mise"
+    set :mise_roles, fetch(:mise_roles, :all)
+    set :mise_map_bins, %w[rake gem bundle ruby rails]
+  end
+end

metadata

@@ -0,0 +1,95 @@
+--- !ruby/object:Gem::Specification
+name: capistrano-mise
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Zac
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: capistrano
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+description: Wraps the commands Capistrano runs on a host with `mise exec`, so they
+  resolve their tool versions from the mise config that shipped with the revision.
+email:
+- 579103+7a6163@users.noreply.github.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/capistrano/mise.rb
+- lib/capistrano/mise/commands.rb
+- lib/capistrano/mise/version.rb
+- lib/capistrano/tasks/mise.rake
+homepage: https://github.com/7a6163/capistrano-mise
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/7a6163/capistrano-mise
+  source_code_uri: https://github.com/7a6163/capistrano-mise
+  changelog_uri: https://github.com/7a6163/capistrano-mise/blob/main/CHANGELOG.md
+  github_repo: ssh://github.com/7a6163/capistrano-mise
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.20
+specification_version: 4
+summary: Run Capistrano's remote commands through mise
+test_files: []