lux-hammer 0.3.10 → 0.3.13

data/recipes/lib/deploy/context.rb

@@ -0,0 +1,149 @@
+module LuxDeploy
+  # Bag of resolved state for a single command invocation.
+  class Context
+    # A deployable unit. systemd.service is the web service (caddy-fronted);
+    # any other config/deploy/<name>.service becomes <prefix>-<app>-<name>.
+    Service ||= Struct.new(:name, :template, :artifact, :unit, :web)
+
+    attr_reader :host, :ssh, :branch, :app, :app_dir, :config_dir,
+                :env_template_name, :config, :templates_dir
+    attr_accessor :ports, :domain, :rendered
+
+    # Primary web port. Convenience for the manifest / done line; the full
+    # set (PORT, PORT_*) lives in #ports.
+    def port
+      ports && ports[:PORT]
+    end
+
+    def ruby_path
+      @ruby_path ||= detect_ruby_path
+    end
+
+    # All template-substitution vars come from two places: git-derived and
+    # yaml. Engine-dynamic vars (PORT, DIR, RUBY, RUBY_DIR) layer on top in
+    # render_artifacts since they are only known after server probe. The
+    # rendered .env never feeds back into this namespace - .env is a
+    # runtime-only file the app reads at boot.
+    def base_vars
+      Template.git_vars.merge(config.template_vars).merge(
+        APP: @app,
+        APP_UNDERSCORE: @app.gsub(/[^A-Za-z0-9]+/, '_'),
+        HASH: domain_hash,
+        TAG: domain_tag
+      )
+    end
+
+    def domain_hash
+      require 'digest'
+      "h#{Digest::SHA256.hexdigest(@domain.to_s)[0, 6]}"
+    end
+
+    def domain_tag
+      require 'digest'
+      "s#{Digest::SHA256.hexdigest(@domain.to_s)[0, 5]}"
+    end
+
+    def self.read_host(opts)
+      override = opts[:server]
+      return override.to_s.strip if override && !override.to_s.strip.empty?
+      Config.load.server.tap do |host|
+        raise Error.new("config/deploy/.yaml: 'server:' is empty") if host.empty?
+      end
+    end
+
+    def self.build(opts, render: true)
+      ctx = new
+      ctx.send(:resolve!, opts)
+      ctx
+    end
+
+    # Raw template body, or nil when the file exists in neither the app's
+    # config/deploy nor the plugin templates_dir. Non-raising twin of
+    # read_template - used for cheap scans (port keys, {{RUBY}} presence).
+    def template_source(name)
+      local = File.join(@config_dir, name)
+      return File.read(local) if File.exist?(local)
+      if templates_dir
+        shipped = File.join(templates_dir, name)
+        return File.read(shipped) if File.exist?(shipped)
+      end
+      nil
+    end
+
+    # Look up a template by name. Apps override individual files by dropping
+    # them in ./config/deploy/<name>; if missing, fall back to the host-
+    # supplied templates_dir (set via Hammer.register), if any.
+    def read_template(name)
+      template_source(name) or
+        raise Error.new("template not found: #{name} (looked in #{@config_dir}" \
+                        "#{templates_dir ? " and #{templates_dir}" : ''})")
+    end
+
+    # Services discovered from config/deploy/*.service. systemd.service is
+    # always present (web, caddy front); every other file is an extra unit.
+    # A leading "!" disables a file (e.g. !job.service) - lux-deploy ignores
+    # it everywhere (not a service, not rsync'd). Pure filesystem lookup -
+    # no ssh - so it works in render:false (destroy).
+    def services
+      @services ||= begin
+        prefix = config.service_prefix
+        list = [Service.new('web', 'systemd.service', 'systemd.service',
+                            "#{prefix}-#{app}", true)]
+        Dir.children(@config_dir).select { |f| f.end_with?('.service') && !f.start_with?('!') }.sort.each do |f|
+          next if f == 'systemd.service'
+          name = f.sub(/\.service\z/, '')
+          list << Service.new(name, f, "systemd.#{name}.service",
+                              "#{prefix}-#{app}-#{name}", false)
+        end
+        list
+      end
+    end
+
+    # True when any rendered template references {{RUBY}}/{{RUBY_DIR}}. Gates
+    # the (ssh) ruby probe so a Go/Python app whose unit runs a built binary
+    # deploys without a ruby on the box.
+    def ruby_used?
+      return @ruby_used unless @ruby_used.nil?
+      names = (['caddy.conf', env_template_name] + services.map(&:template)).uniq
+      @ruby_used = names.any? { |n| (s = template_source(n)) && s.include?('{{RUBY') }
+    end
+
+    private
+
+    def resolve!(opts)
+      @config_dir = './config/deploy'
+      raise Error.new("missing #{@config_dir}/ directory") unless Dir.exist?(@config_dir)
+
+      @config = Config.load
+      @templates_dir = opts[:templates_dir]
+
+      @host = (opts[:server].to_s.strip.empty? ? @config.server : opts[:server]).to_s.strip
+      raise Error.new("no server set (.yaml 'server:' or --server)") if @host.empty?
+
+      @ssh    = SSH.new(@host, service_user: @config.service_user, dry_run: opts[:dry_run] || false)
+      @branch = Template.git_vars[:GIT_BRANCH]
+      @env_template_name = LuxDeploy::MAIN_BRANCHES.include?(@branch) ? '.env' : '.env.staging'
+
+      # App slug comes from yaml `domain:` only. Multi-host strings like
+      # "foo.com, *.foo" are allowed; the slug is the first comma-split
+      # segment with any leading "*." stripped.
+      raw = @config.domain.to_s
+      raise Error.new("config/deploy/.yaml: 'domain:' is empty") if raw.strip.empty?
+      domain = raw.split(',').first.to_s.strip.sub(/^\*\./, '')
+      raise Error.new('domain resolved to empty') if domain.empty?
+      @app     = domain
+      @domain  = domain
+      @app_dir = File.join(@config.remote_base, domain)
+    end
+
+    def detect_ruby_path
+      return "/home/#{config.service_user}/.local/share/mise/installs/ruby/CURRENT/bin/ruby" if @ssh.dry_run
+      out = @ssh.run(<<~SH, as: :service, allow_fail: true)
+        ls -td ~/.local/share/mise/installs/ruby/*/bin/ruby 2>/dev/null | head -n1 || which ruby
+      SH
+      path = out.lines.find { |l| l.strip.start_with?('/') }&.strip
+      raise Error.new("no ruby found on remote (mise not installed for #{config.service_user}?)") if path.to_s.empty?
+      path
+    end
+  end
+end

data/recipes/lib/deploy/doctor.rb

@@ -0,0 +1,238 @@
+require 'yaml'
+
+module LuxDeploy
+  # Named host checks: each entry is [label, check_cmd, fix_cmd_or_nil].
+  # `check_cmd` must exit 0 on PASS, non-zero on FAIL.
+  # `fix_cmd` is optional; if present and check fails, we run it (when --fix)
+  # and re-check. Anything that needs interactive judgement leaves fix_cmd nil.
+  module Doctor
+    GREEN ||= "\e[32m"
+    RED   ||= "\e[31m"
+    DIM   ||= "\e[2m"
+    RESET ||= "\e[0m"
+
+    # Placeholders the engine always provides at deploy time; templates
+    # may reference these without declaring them in .env or .yaml.
+    PROVIDED_VARS ||= %w[
+      GIT_BRANCH GIT_BRANCH_UNDERSCORE APP APP_UNDERSCORE HASH TAG
+      PORT DIR RUBY RUBY_DIR
+    ].freeze
+
+    module_function
+
+    def run(ssh, config, fix: true)
+      puts 'Local config'
+      local_failed = local_checks(config)
+      puts
+
+      puts 'Remote host'
+      checks = build_checks(config)
+      failed = local_failed
+
+      checks.each do |label, check_cmd, fix_cmd|
+        if passes?(ssh, check_cmd)
+          puts "  #{GREEN}PASS#{RESET}  #{label}"
+          next
+        end
+
+        if fix && fix_cmd
+          puts "  #{DIM}FIX#{RESET}   #{label}"
+          ssh.run(fix_cmd, allow_fail: true)
+          if passes?(ssh, check_cmd)
+            puts "  #{GREEN}PASS#{RESET}  #{label} (after fix)"
+            next
+          end
+        end
+
+        failed += 1
+        puts "  #{RED}FAIL#{RESET}  #{label}"
+        puts "  #{DIM}        check: #{check_cmd.lines.first.chomp}#{RESET}"
+      end
+
+      puts
+      if failed.zero?
+        puts "#{GREEN}all checks passed#{RESET}"
+      else
+        puts "#{RED}#{failed} check#{failed == 1 ? '' : 's'} failed#{RESET}"
+        raise Error.new("doctor reported #{failed} failure(s)")
+      end
+    end
+
+    # Run check command, return true on exit 0.
+    def passes?(ssh, cmd)
+      out = ssh.run(cmd + ' && echo __OK__ || echo __FAIL__', allow_fail: true)
+      out.include?('__OK__')
+    end
+
+    # Lifecycle hooks (run during `up` if present in config/deploy/).
+    # Optional - doctor reports their presence/absence, never creates.
+    # Scaffolds with explanatory header comments ship via `app:init`.
+    HOOK_FILES ||= %w[local_before.sh remote_before.sh remote_after.sh local_after.sh].freeze
+
+    # True when any local config/deploy template references {{RUBY}}. Gates
+    # the ruby/bundler host checks so a Go/Python app doesn't fail doctor.
+    def ruby_runtime?(dir = './config/deploy')
+      Dir.glob("#{dir}/*").any? { |f| File.file?(f) && File.read(f).include?('{{RUBY') }
+    end
+
+    def local_checks(_config)
+      dir = './config/deploy'
+      failed = 0
+
+      report = ->(ok, label, detail = nil) {
+        if ok
+          puts "  #{GREEN}PASS#{RESET}  #{label}"
+        else
+          failed += 1
+          puts "  #{RED}FAIL#{RESET}  #{label}"
+          puts "  #{DIM}        #{detail}#{RESET}" if detail
+        end
+      }
+
+      skip = ->(label) { puts "  #{DIM}SKIP  #{label} (does not exist)#{RESET}" }
+
+      unless Dir.exist?(dir)
+        report.call(false, "#{dir}/ directory present",
+                    "missing; run: deploy app:init")
+        return failed
+      end
+
+      # Parse .yaml; bail early if absent or malformed since other
+      # checks depend on its keys.
+      yaml_path = "#{dir}/.yaml"
+      yaml_data = nil
+      if File.exist?(yaml_path)
+        report.call(true, "#{yaml_path} present")
+        begin
+          yaml_data = YAML.safe_load(File.read(yaml_path)) || {}
+          report.call(yaml_data.is_a?(Hash), "#{yaml_path} is a YAML mapping")
+          yaml_data = {} unless yaml_data.is_a?(Hash)
+          report.call(!yaml_data['server'].to_s.strip.empty?, ".yaml 'server:' set")
+          report.call(!yaml_data['domain'].to_s.strip.empty?, ".yaml 'domain:' set")
+        rescue Psych::SyntaxError => e
+          report.call(false, "#{yaml_path} parses", e.message)
+          yaml_data = {}
+        end
+      else
+        report.call(false, "#{yaml_path} present", "missing; run: deploy app:init")
+        yaml_data = {}
+      end
+
+      report.call(File.exist?("#{dir}/.env"),            "#{dir}/.env present")
+      report.call(File.exist?("#{dir}/caddy.conf"),      "#{dir}/caddy.conf present")
+      report.call(File.exist?("#{dir}/systemd.service"), "#{dir}/systemd.service present")
+
+      # Lifecycle hooks - optional. Report each as PASS (present, will run)
+      # or SKIP (absent, hook step will be skipped during `up`).
+      HOOK_FILES.each do |name|
+        path = "#{dir}/#{name}"
+        if File.exist?(path)
+          report.call(true, "#{path} present (will run)")
+        else
+          skip.call("#{path} (lifecycle hook)")
+        end
+      end
+
+      yaml_keys = yaml_data.keys.map { |k| k.to_s.upcase }
+
+      # Every template is rendered with the same vars: engine-provided +
+      # yaml. The rendered .env is uploaded verbatim; it never feeds back
+      # into the template namespace, so caddy.conf / *.service can only
+      # reference yaml keys + engine vars (not anything defined in .env).
+      # Every *.service file is a service; only systemd.service is required.
+      # PORT-prefixed placeholders are engine-provided (auto-allocated).
+      service_files       = Dir.children(dir).select { |f| f.end_with?('.service') && !f.start_with?('!') }.sort
+      optional            = %w[.env.staging] + (service_files - %w[systemd.service])
+      placeholder_targets = %w[.env .env.staging caddy.conf] + service_files
+      provided            = PROVIDED_VARS + yaml_keys
+      placeholder_targets.uniq.each do |name|
+        path = "#{dir}/#{name}"
+        unless File.exist?(path)
+          skip.call(name) if optional.include?(name)
+          next
+        end
+
+        placeholders = File.read(path).scan(Template::PLACEHOLDER).flatten.uniq
+        missing      = placeholders.reject { |v| provided.include?(v) || v.start_with?('PORT') }
+        ok           = missing.empty?
+        report.call(ok, "#{name}: placeholders resolve",
+                    ok ? nil : "missing: #{missing.map { |v| "{{#{v}}}" }.join(' ')}")
+      end
+
+      failed
+    end
+
+    def build_checks(config)
+      user = config.service_user
+      base = config.remote_base
+      [
+        [
+          "#{user} user exists",
+          "id #{user} >/dev/null 2>&1",
+          "useradd -m -s /bin/bash #{user}"
+        ],
+        [
+          "/home/#{user} is traversable (0755)",
+          # caddy + systemd need to read symlinks into ~/<base>;
+          # useradd defaults home to 0700 on Debian, which blocks them.
+          "[ \"$(stat -c %a /home/#{user})\" = 755 ]",
+          "chmod 0755 /home/#{user}"
+        ],
+        [
+          "#{user} in sudo group (passwordless)",
+          "grep -q '^#{user} ' /etc/sudoers.d/#{user} 2>/dev/null && grep -q NOPASSWD /etc/sudoers.d/#{user}",
+          "echo '#{user} ALL=(ALL) NOPASSWD: ALL' > /etc/sudoers.d/#{user} && chmod 0440 /etc/sudoers.d/#{user}"
+        ],
+        [
+          "#{base} exists and owned by #{user}",
+          "[ -d #{base} ] && [ \"$(stat -c %U #{base})\" = #{user} ]",
+          "install -d -o #{user} -g #{user} -m 0755 #{base}"
+        ],
+        [
+          '/etc/caddy/sites exists',
+          "[ -d #{CADDY_SITES} ]",
+          "install -d -m 0755 #{CADDY_SITES}"
+        ],
+        [
+          'caddy running',
+          'systemctl is-active --quiet caddy',
+          nil
+        ],
+        [
+          "caddy imports #{CADDY_SITES}/*.caddy",
+          "grep -Rq 'import #{CADDY_SITES}/\\*.caddy' /etc/caddy/ 2>/dev/null",
+          nil
+        ],
+        [
+          "mise installed for #{user}",
+          "sudo -iu #{user} bash -lc 'command -v mise >/dev/null'",
+          nil
+        ],
+        # Ruby/bundler only matter when a template references {{RUBY}};
+        # a Go/Python app builds in remote_before and needs neither.
+        *(ruby_runtime? ? [
+          [
+            "ruby on #{user} PATH",
+            "sudo -iu #{user} bash -lc 'command -v ruby >/dev/null && ruby -v'",
+            nil
+          ],
+          [
+            "bundler on #{user} PATH",
+            "sudo -iu #{user} bash -lc 'command -v bundle >/dev/null'",
+            "sudo -iu #{user} bash -lc 'gem install bundler --no-document'"
+          ]
+        ] : []),
+        [
+          'xcaddy available (for plugin rebuilds)',
+          'command -v xcaddy >/dev/null',
+          nil
+        ],
+        [
+          'ssh password auth disabled (warn-only)',
+          "sshd -T 2>/dev/null | grep -qx 'passwordauthentication no'",
+          nil
+        ]
+      ]
+    end
+  end
+end

data/recipes/lib/deploy/hammer.rb

@@ -0,0 +1,168 @@
+module LuxDeploy
+  # Registers the lux-deploy Hammer tasks on a host CLI. Designed to be
+  # called from a Hammerfile (the gem's own, the lux-fw plugin's, or any
+  # user's) so all task definitions live in one place.
+  #
+  # Usage from a Hammerfile (block DSL):
+  #
+  #   require 'lux_deploy'
+  #   LuxDeploy::Hammer.register(self)                            # top-level
+  #   LuxDeploy::Hammer.register(self, prefix: :deploy)           # under deploy:
+  #   LuxDeploy::Hammer.register(self,
+  #     prefix: :deploy,
+  #     templates_dir: '/abs/path/to/plugin/templates',
+  #     defaults: {
+  #       service_prefix: 'lux-web',
+  #       remote_base: '/home/deployer/lux-apps',
+  #     }
+  #   )
+  #
+  # `defaults` is merged under user's .yaml (yaml wins). `templates_dir`
+  # is what `app:init` copies from and the deploy step falls back to
+  # when ./config/deploy/<name> is missing.
+  module Hammer
+    module_function
+
+    def safe(opts)
+      yield
+    rescue LuxDeploy::Error => e
+      warn e.to_s
+      exit 1
+    rescue Interrupt
+      warn 'aborted'
+      exit 130
+    end
+
+    def register(receiver, prefix: nil, templates_dir: nil, defaults: nil)
+      LuxDeploy.set_defaults(defaults) if defaults
+      tdir = templates_dir
+      if prefix
+        receiver.namespace(prefix) { LuxDeploy::Hammer.define_on(self, tdir) }
+      else
+        define_on(receiver, tdir)
+      end
+    end
+
+    # `target` must respond to `task` and `namespace` (Builder or Hammer
+    # subclass). `tdir` is captured by task closures so `app:init` and
+    # deploy template fallback both see it.
+    def define_on(target, tdir)
+      target.task :up do
+        desc 'Deploy current branch (rsync, hooks, swap, restart)'
+        opt :server,  desc: 'Override hostname from config/deploy/.yaml'
+        opt :dry_run, type: :boolean, default: false, desc: 'Print commands, do not execute'
+
+        proc { |opts| LuxDeploy::Hammer.safe(opts) { LuxDeploy::Commands.up(opts.merge(templates_dir: tdir)) } }
+      end
+
+      target.task :redeploy do
+        desc 'Destroy then deploy (fresh PORT, blank release history)'
+        opt :server,  desc: 'Override hostname from config/deploy/.yaml'
+        opt :yes,     type: :boolean, default: false, desc: 'Skip destroy confirmation'
+        opt :dry_run, type: :boolean, default: false, desc: 'Print commands, do not execute'
+
+        proc { |opts| LuxDeploy::Hammer.safe(opts) { LuxDeploy::Commands.redeploy(opts.merge(templates_dir: tdir)) } }
+      end
+
+      target.task :destroy do
+        desc 'Stop service, unlink caddy/systemd, remove app dir'
+        opt :server,  desc: 'Override hostname from config/deploy/.yaml'
+        opt :yes,     type: :boolean, default: false, desc: 'Skip type-domain-to-confirm prompt'
+        opt :dry_run, type: :boolean, default: false, desc: 'Print commands, do not execute'
+
+        proc { |opts| LuxDeploy::Hammer.safe(opts) { LuxDeploy::Commands.destroy(opts.merge(templates_dir: tdir)) } }
+      end
+
+      target.task :doctor do
+        desc 'Check & prepare host: service user, dirs, caddy, ruby, bundler'
+        opt :server, desc: 'Override hostname from config/deploy/.yaml'
+        opt :fix,    type: :boolean, default: true, desc: 'Auto-fix safe items (default true; --no-fix to skip)'
+
+        proc { |opts| LuxDeploy::Hammer.safe(opts) { LuxDeploy::Commands.doctor(opts) } }
+      end
+
+      target.task :log do
+        desc 'List server logs, or dump one with --log <name> (--lines 200)'
+        opt :server, desc: 'Override hostname from config/deploy/.yaml'
+        opt :log,    desc: 'Log name to dump (e.g. errors, exceptions); omit to list all logs'
+        opt :lines,  default: 200, desc: 'Lines to show when dumping a log (default 200)'
+        proc { |opts| LuxDeploy::Hammer.safe(opts) { LuxDeploy::Commands.log(opts.merge(templates_dir: tdir)) } }
+      end
+
+      target.namespace(:app)    { LuxDeploy::Hammer.define_app_on(self, tdir) }
+      target.namespace(:server) { LuxDeploy::Hammer.define_server_on(self, tdir) }
+      target.namespace(:on)     { LuxDeploy::Hammer.define_on_hooks_on(self, tdir) }
+    end
+
+    def define_on_hooks_on(target, tdir)
+      target.namespace(:remote) do
+        LuxDeploy::Hammer.define_hook_task_on(self, :before, :remote, :before, tdir, 'Run config/deploy/remote_before.sh on new-release/')
+        LuxDeploy::Hammer.define_hook_task_on(self, :after, :remote, :after, tdir, 'Run config/deploy/remote_after.sh on release/')
+      end
+
+      target.namespace(:local) do
+        LuxDeploy::Hammer.define_hook_task_on(self, :before, :local, :before, tdir, 'Run config/deploy/local_before.sh locally')
+        LuxDeploy::Hammer.define_hook_task_on(self, :after, :local, :after, tdir, 'Run config/deploy/local_after.sh locally')
+      end
+    end
+
+    def define_hook_task_on(target, task_name, side, timing, tdir, description)
+      target.task task_name do
+        desc description
+        opt :server,  desc: 'Override hostname from config/deploy/.yaml'
+        opt :dry_run, type: :boolean, default: false, desc: 'Print commands, do not execute'
+
+        proc { |opts|
+          LuxDeploy::Hammer.safe(opts) {
+            LuxDeploy::Commands.hook(opts.merge(templates_dir: tdir), side, timing)
+          }
+        }
+      end
+    end
+
+    def define_app_on(target, tdir)
+      target.task :init do
+        desc 'Copy shipped templates into ./config/deploy/ (skips existing files)'
+        opt :from, desc: 'Override templates directory (default: caller-provided or bundled)'
+        proc { |opts|
+          LuxDeploy::Hammer.safe(opts) {
+            LuxDeploy::Commands.init(opts.merge(templates_dir: opts[:from] || tdir))
+          }
+        }
+      end
+    end
+
+    def define_server_on(target, tdir)
+      target.task :ssh do
+        desc 'SSH into the release folder as the service user'
+        opt :server, desc: 'Override hostname from config/deploy/.yaml'
+        proc { |opts| LuxDeploy::Hammer.safe(opts) { LuxDeploy::Commands.server_ssh(opts.merge(templates_dir: tdir)) } }
+      end
+
+      target.task :log do
+        desc 'Tail systemd journal for the web service (-f, last 200)'
+        opt :server, desc: 'Override hostname from config/deploy/.yaml'
+        proc { |opts| LuxDeploy::Hammer.safe(opts) { LuxDeploy::Commands.server_log(opts.merge(templates_dir: tdir)) } }
+      end
+
+      target.task :errors do
+        desc 'Tail -f the app error log (release/log/error.log)'
+        opt :server, desc: 'Override hostname from config/deploy/.yaml'
+        proc { |opts| LuxDeploy::Hammer.safe(opts) { LuxDeploy::Commands.server_errors(opts.merge(templates_dir: tdir)) } }
+      end
+
+      target.task :restart do
+        desc 'systemctl restart the web service'
+        opt :server, desc: 'Override hostname from config/deploy/.yaml'
+        proc { |opts| LuxDeploy::Hammer.safe(opts) { LuxDeploy::Commands.server_restart(opts.merge(templates_dir: tdir)) } }
+      end
+
+      target.task :status do
+        desc 'systemctl status the web service'
+        opt :server, desc: 'Override hostname from config/deploy/.yaml'
+        proc { |opts| LuxDeploy::Hammer.safe(opts) { LuxDeploy::Commands.server_status(opts.merge(templates_dir: tdir)) } }
+      end
+    end
+
+  end
+end