easy_caddy 0.1.0 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 15359e9854098ff355b15635597ff9979952d9224835eb31594676492fbd64d9
-  data.tar.gz: b3f4b62942373f0554e0d0ff92671bccb8fe7efd8ffef16038f4248c251687bb
+  metadata.gz: 1c38478a91bcf7a5ef93a10693e73d829b74ab1e88709fb38112c1120d30e499
+  data.tar.gz: c4923a78a738fdd89079df4f80f3f35ac3185a421be7b2e3ae3509d985168790
 SHA512:
-  metadata.gz: 2cccf4fca5dbe0eb0148998507d67666b294dcc0233c34fd83b2789e6c18c44191981dc2391b9f319067bc183729078b2985994641f9247838134c3361efbdf2
-  data.tar.gz: d8c66f1dba6f6d32210c2a2cbfa910a1560668a7ea5e5a84cfe9e6371142036fcd0543035b488f9b415f9e1c6ac9c58b6ac1e17cc06006e6f71a9e8c057e45bf
+  metadata.gz: 59e2de015249c22dc56aa731e9a059655a9548d27582947a6d1ba38bffd713950fc23db4e21867ffee2cb2ae7d6e36bd13a8fe4eff4356e06b25115df2f326c8
+  data.tar.gz: 4a2226c3ad545bdd047dfcb896636eaf52a9fa1bae1a8984d68a7bbf84300e0dc9fcc9c61fc64fe259f994c37b1d3f8fd12e4d413764e6b3775577302f569937

data/CHANGELOG.md

@@ -5,6 +5,38 @@ 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.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.1.2] — 2026-06-09
+
+### Added
+
+- `EasyCaddy::Error` exception class for user-facing failures. `exe/ecaddy`
+  now rescues it and prints a clean one-line message to stderr (exit 1),
+  replacing Ruby's default backtrace dump on expected errors.
+- Registered fragments now have `output file` directives rewritten to
+  include `mode 0660` so log files (and rolled successors) stay
+  group-writable — Caddy runs as root to bind `:80`/`:443`, but
+  `caddy validate` / `caddy reload` run as the unprivileged user and need
+  to open them.
+- `ecaddy audit` now reports each declared log file as writable, missing,
+  or root-locked, with an interactive `--fix` that escalates to
+  `sudo chmod` when needed.
+
+### Fixed
+
+- `ecaddy setup` now starts the Caddy brew service **before** running
+  `caddy trust`, fixing a `connection refused` failure on fresh installs
+  (the local-CA fetch requires the admin endpoint at `localhost:2019` to
+  be running). Setup also polls the admin endpoint for up to 10 s before
+  attempting trust.
+- `caddy trust` failures now surface the underlying output plus an
+  actionable hint (brew restart, `sudo caddy trust`, or re-run `setup`)
+  instead of a generic message.
+- `ecaddy run` / `ecaddy ensure` now pre-create each log file declared
+  in the fragment and fail fast with a `sudo chmod` hint when the file
+  or its directory is owned by another user (typically left over from a
+  previous `sudo` run). The opaque `permission denied` from Caddy's
+  config validator is now translated into a one-line, actionable error.
+
 ## [0.1.0] — 2026-06-09
 
 ### Added
@@ -31,4 +63,5 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   `SIGTERM`/`SIGINT`, and unregisters on exit — designed to drop into a
   Procfile alongside the Rails server.
 
+[0.1.2]: https://github.com/pniemczyk/easy_caddy/releases/tag/v0.1.2
 [0.1.0]: https://github.com/pniemczyk/easy_caddy/releases/tag/v0.1.0

data/README.md

@@ -272,7 +272,7 @@ ecaddy reload
 
 ```bash
 ecaddy version
-# ecaddy 0.1.0
+# ecaddy 0.1.2
 ```
 
 ## Global config layout

data/exe/ecaddy

@@ -3,4 +3,11 @@
 
 require_relative '../lib/easy_caddy'
 
-EasyCaddy::CLI.start(ARGV)
+begin
+  EasyCaddy::CLI.start(ARGV)
+rescue EasyCaddy::Error => e
+  # Deliberately $stderr.puts, not warn: this message must always surface,
+  # even when warnings are disabled (e.g. RUBYOPT=-W0).
+  $stderr.puts e.message # rubocop:disable Style/StderrPuts
+  exit 1
+end

data/lib/easy_caddy/caddy.rb

@@ -1,12 +1,20 @@
 # frozen_string_literal: true
 
 require 'English'
+require 'net/http'
+require 'uri'
+require_relative 'error'
 require_relative 'paths'
 
 module EasyCaddy
   module Caddy
     BINARY = 'caddy'
 
+    # Group-writable mode for Caddy log files. A root-run Caddy (needed to bind :443/:80)
+    # creates logs the unprivileged user can't open during `caddy validate`/`reload`;
+    # 0660 + macOS staff-group inheritance keeps them openable. See the log-permission fix.
+    LOG_FILE_MODE = '0660'
+
     def self.installed?
       system('which caddy > /dev/null 2>&1')
     end
@@ -19,8 +27,34 @@ module EasyCaddy
       return unless caddyfile.exist?
 
       out = `#{BINARY} validate --config #{caddyfile} 2>&1`
-      raise "Caddy config invalid:\n#{out}" unless $CHILD_STATUS.success?
+      return if $CHILD_STATUS.success?
+
+      raise Error, translate_validate_error(out)
+    end
+
+    # Caddy validate emits a wall of JSON log lines on stderr. Pull out the
+    # actual error and, for common cases (log file permission), turn it into
+    # an actionable message.
+    # rubocop:disable Metrics/MethodLength
+    def self.translate_validate_error(output)
+      error_line = output.lines.find { |l| l.start_with?('Error:') }&.strip
+
+      if error_line && error_line.match?(/setting up custom log.*permission denied/i)
+        path = error_line[%r{open\s+(/\S+):\s*permission denied}, 1]
+        hint =
+          if path
+            "Caddy runs as root and created this log 0600; validation runs as you and can't " \
+            "open it.\nFix it once with:  sudo chmod #{LOG_FILE_MODE} #{path}\n" \
+            'or run `ecaddy audit --fix` to do it interactively.'
+          else
+            'Check ownership of the log file referenced above, or run `ecaddy audit --fix`.'
+          end
+        return "Caddy config invalid — log file not writable:\n  #{error_line}\n\n#{hint}"
+      end
+
+      "Caddy config invalid:\n#{error_line || output}"
     end
+    # rubocop:enable Metrics/MethodLength
 
     def self.reload(caddyfile = Paths.caddyfile)
       unless caddyfile.exist?
@@ -29,13 +63,46 @@ module EasyCaddy
       end
 
       out = `#{BINARY} reload --config #{caddyfile} 2>&1`
-      raise "Caddy reload failed:\n#{out}" unless $CHILD_STATUS.success?
+      raise Error, "Caddy reload failed:\n#{out}" unless $CHILD_STATUS.success?
     end
 
     def self.trust
       system("#{BINARY} trust")
     end
 
+    # Runs `caddy trust` and captures stdout+stderr so callers can inspect failures.
+    #
+    # @return [Array(String, Boolean)] combined output and whether the command succeeded
+    def self.trust_with_output
+      out = `#{BINARY} trust 2>&1`
+      [out, $CHILD_STATUS.success?]
+    end
+
+    ADMIN_ENDPOINT = 'http://localhost:2019/pki/ca/local'
+
+    # Polls Caddy's admin API until it responds or the timeout elapses.
+    #
+    # @param timeout [Numeric] seconds to wait before giving up
+    # @return [Boolean] true if the admin endpoint responded
+    def self.wait_for_admin_endpoint(timeout: 5)
+      deadline = Time.now + timeout
+      until Time.now > deadline
+        return true if admin_endpoint_reachable?
+
+        sleep 0.25
+      end
+      false
+    end
+
+    def self.admin_endpoint_reachable?
+      uri = URI(ADMIN_ENDPOINT)
+      Net::HTTP.start(uri.host, uri.port, open_timeout: 1, read_timeout: 1) do |http|
+        http.get(uri.request_uri).is_a?(Net::HTTPSuccess)
+      end
+    rescue StandardError
+      false
+    end
+
     def self.running?
       pid = brew_service_pid
       pid && pid > 0

data/lib/easy_caddy/commands/audit.rb

@@ -399,15 +399,42 @@ module EasyCaddy
         if log_paths.empty?
           info 'No log files configured (add a log { output file … } block)'
         else
-          log_paths.each do |path|
-            if File.exist?(path)
-              ok("log #{path}  (#{humanize_bytes(File.size(path))})")
-            else
-              warn("log #{path}  — not yet created")
-            end
-          end
+          log_paths.each { |path| print_log_file(path) }
+        end
+      end
+      # rubocop:enable Metrics/MethodLength
+
+      def print_log_file(path)
+        if !File.exist?(path)
+          warn("log #{path}  — not yet created")
+        elsif File.writable?(path)
+          ok("log #{path}  (#{humanize_bytes(File.size(path))})")
+        else
+          fail("log #{path}  — NOT writable by you (root-owned?)",
+               hint: 'Caddy runs as root and created this 0600 log; `caddy validate` runs as ' \
+                     'you and cannot open it. Make it group-writable.',
+               fix: log_permission_fix(path))
         end
       end
+
+      # rubocop:disable Metrics/MethodLength
+      def log_permission_fix(path)
+        {
+          description: "Make the log group-writable (chmod #{Caddy::LOG_FILE_MODE})",
+          command: "chmod #{Caddy::LOG_FILE_MODE} #{path}",
+          verify: -> { File.writable?(path) },
+          escalation: "You don't own this file — needs sudo.",
+          next_fix: Fix.new(
+            label: "#{path} still not writable",
+            description: 'chmod the root-owned log via sudo',
+            command: "sudo chmod #{Caddy::LOG_FILE_MODE} #{path}",
+            verify: -> { File.writable?(path) },
+            escalation: "Still not writable. Check `ls -l #{path}`; " \
+                        "you may need `sudo chown $USER:staff #{path}`.",
+            next_fix: nil
+          )
+        }
+      end
       # rubocop:enable Metrics/MethodLength
 
       # rubocop:disable Metrics/AbcSize, Metrics/MethodLength

data/lib/easy_caddy/commands/register_helpers.rb

@@ -3,6 +3,7 @@
 require 'fileutils'
 require 'socket'
 require 'openssl'
+require_relative '../error'
 require_relative '../paths'
 require_relative '../registry'
 require_relative '../conflicts'
@@ -12,6 +13,7 @@ require_relative '../parser'
 
 module EasyCaddy
   module Commands
+    # rubocop:disable Metrics/ModuleLength
     module RegisterHelpers
       private
 
@@ -19,10 +21,10 @@ module EasyCaddy
       # Returns the site name on success.
       # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength
       def register(config_path, name)
-        raise ArgumentError, 'Pass --site NAME to identify this project.' unless name
+        raise Error, 'Pass --site NAME to identify this project.' unless name
 
         config_path = File.expand_path(config_path)
-        raise ArgumentError, "Config not found: #{config_path}" unless File.exist?(config_path)
+        raise Error, "Config not found: #{config_path}" unless File.exist?(config_path)
 
         content  = File.read(config_path)
         registry = Registry.load
@@ -33,11 +35,11 @@ module EasyCaddy
         blocks = findings.select { |f| f.severity == 'BLOCK' }
         unless blocks.empty?
           blocks.each { |f| warn "  BLOCK: #{f.message}\n         Hint: #{f.hint}" }
-          raise 'Aborting due to conflict.'
+          raise Error, 'Aborting due to conflict.'
         end
 
         Paths.sites_dir.mkpath
-        rewritten = absolutize_log_paths(content, File.dirname(config_path))
+        rewritten = ensure_log_mode(absolutize_log_paths(content, File.dirname(config_path)))
         Paths.site_file(name).write(rewritten)
 
         ensure_log_dirs(rewritten)
@@ -65,12 +67,66 @@ module EasyCaddy
         end
       end
 
+      # Guarantee every `output file` log directive sets a group-writable mode, so a
+      # root-run Caddy's logs (and rolled files) stay openable by the staff-group user that
+      # runs `caddy validate`/`reload`. Leaves an explicit `mode` untouched.
+      def ensure_log_mode(content)
+        content.gsub(/(\boutput\s+file\s+\S+)(\s*\{[^}]*\})?/m) do
+          directive = Regexp.last_match(1)
+          block     = Regexp.last_match(2)
+          next "#{directive} {\n    mode #{Caddy::LOG_FILE_MODE}\n  }" if block.nil?
+          next "#{directive}#{block}" if block.match?(/\bmode\b/)
+
+          "#{directive}#{block.sub('{', "{\n    mode #{Caddy::LOG_FILE_MODE}")}"
+        end
+      end
+
       def ensure_log_dirs(content)
         Parser.parse(content).log_paths.each do |path|
-          FileUtils.mkdir_p(File.dirname(path))
+          ensure_log_writable(path)
         end
       end
 
+      # Make sure each log path exists and is writable by the current user.
+      # Caddy validates configs by *opening* every log file, so a stray
+      # root-owned file (left over from an earlier `sudo` run) makes
+      # validation fail with a confusing "permission denied".
+      def ensure_log_writable(path)
+        dir = File.dirname(path)
+        FileUtils.mkdir_p(dir)
+        FileUtils.touch(path) unless File.exist?(path)
+        return if File.writable?(path) && File.writable?(dir)
+
+        raise Error, build_log_permission_error(path)
+      rescue Errno::EACCES, Errno::EPERM
+        raise Error, build_log_permission_error(path)
+      end
+
+      # rubocop:disable Metrics/MethodLength
+      def build_log_permission_error(path)
+        owner =
+          begin
+            require 'etc'
+            Etc.getpwuid(File.stat(path).uid).name if File.exist?(path)
+          rescue StandardError
+            nil
+          end
+        user = ENV['USER'] || Etc.getlogin
+
+        owner_line = owner ? "  Current owner: #{owner}\n" : ''
+        <<~MSG.strip
+          Cannot write to Caddy log file: #{path}
+          #{owner_line}  Caddy runs as root and created this log 0600; `caddy validate` runs as you
+          (#{user}) and can't open it. Make it group-writable once:
+
+            sudo chmod #{Caddy::LOG_FILE_MODE} #{path}
+
+          or run `ecaddy audit --fix` to do it interactively. Re-registering keeps the mode,
+          so it won't recur after log rolls. Then re-run the same `ecaddy` command.
+        MSG
+      end
+      # rubocop:enable Metrics/MethodLength
+
       def probe_tls(domains)
         domains.each do |domain|
           ok = tls_handshake_ok?(domain)
@@ -112,5 +168,6 @@ module EasyCaddy
         puts "  [ecaddy] #{name} unregistered."
       end
     end
+    # rubocop:enable Metrics/ModuleLength
   end
 end

data/lib/easy_caddy/commands/setup.rb

@@ -23,8 +23,8 @@ module EasyCaddy
         step('Scaffolding config directories') { scaffold_dirs }
         step('Writing global Caddyfile') { write_caddyfile }
         step('Symlinking for brew services') { symlink_brew }
-        step('Trusting local CA') { trust_ca }
         step('Starting caddy service') { start_service }
+        step('Trusting local CA') { trust_ca }
         print_success
       end
 
@@ -76,8 +76,51 @@ module EasyCaddy
       end
 
       def trust_ca
-        puts "\n    Running `caddy trust` — you may be prompted for your password."
-        raise '`caddy trust` failed — re-run `ecaddy setup` or run `sudo caddy trust` manually.' unless Caddy.trust
+        puts "\n    Waiting for Caddy admin endpoint at localhost:2019..."
+        unless Caddy.wait_for_admin_endpoint(timeout: 10)
+          raise <<~MSG.strip
+            Caddy admin endpoint at localhost:2019 is not responding.
+              `caddy trust` needs a running Caddy instance to fetch the local CA.
+              Check that the brew service is up:  brew services list
+              Then re-run:                        ecaddy setup
+          MSG
+        end
+
+        puts '    Running `caddy trust` — you may be prompted for your password.'
+        output, success = Caddy.trust_with_output
+        return if success
+
+        raise build_trust_error(output)
+      end
+
+      def build_trust_error(output)
+        hint =
+          if output.include?('connection refused')
+            <<~HINT
+              Caddy admin endpoint at localhost:2019 became unreachable.
+                Try:  brew services restart caddy && ecaddy setup
+            HINT
+          elsif output.match?(/permission denied|not permitted|requires.*root/i)
+            <<~HINT
+              `caddy trust` needs to add a root certificate to your system keychain.
+                Try running it manually:  sudo caddy trust
+            HINT
+          else
+            <<~HINT
+              Re-run `ecaddy setup`, or run `caddy trust` manually to see the full error.
+            HINT
+          end
+
+        <<~MSG.strip
+          `caddy trust` failed:
+          #{indent(output.strip)}
+
+          #{indent(hint.strip)}
+        MSG
+      end
+
+      def indent(text, prefix = '      ')
+        text.lines.map { |l| "#{prefix}#{l}" }.join.rstrip
       end
 
       def start_service

data/lib/easy_caddy/error.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module EasyCaddy
+  # Raised for expected, user-actionable failures: invalid Caddy config,
+  # domain/port conflicts, unwritable log files. The CLI prints the message
+  # and exits non-zero WITHOUT a Ruby backtrace — these are not bugs, they're
+  # things the user is expected to fix and re-run.
+  class Error < StandardError; end
+end

data/lib/easy_caddy/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module EasyCaddy
-  VERSION = '0.1.0'
+  VERSION = '0.1.2'
 end

data/lib/easy_caddy.rb

@@ -4,6 +4,7 @@ require 'pathname'
 require 'fileutils'
 
 require_relative 'easy_caddy/version'
+require_relative 'easy_caddy/error'
 require_relative 'easy_caddy/paths'
 require_relative 'easy_caddy/site'
 require_relative 'easy_caddy/registry'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: easy_caddy
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.2
 platform: ruby
 authors:
 - Pawel Niemczyk
@@ -139,6 +139,7 @@ files:
 - lib/easy_caddy/commands/status.rb
 - lib/easy_caddy/commands/up.rb
 - lib/easy_caddy/conflicts.rb
+- lib/easy_caddy/error.rb
 - lib/easy_caddy/parser.rb
 - lib/easy_caddy/paths.rb
 - lib/easy_caddy/registry.rb
@@ -167,7 +168,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.6
+rubygems_version: 3.6.9
 specification_version: 4
 summary: CLI to manage a single global Caddy for multiple local Rails projects
 test_files: []