yamine 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1fef68ea493be93af6dfb3271b446b793536a373d11b030f62e54c0d90438e88
-  data.tar.gz: 69c64d3bd1523b05ca6277f76329e20415879f16c95cd0640e30c9adf77f69cf
+  metadata.gz: 1003241d7826eb9d1b2c1f511a7e9b8e99f4be0d9438d2651dd86864d3cee1cc
+  data.tar.gz: 58ee2023a0f951f508c5032af8079d9417f97427bf76d48af08ec734661fd7a7
 SHA512:
-  metadata.gz: 2864def84f4afefe2dd79adda834a2381964e964da864f99c8740321c19559669ad48874cce4485222c0a09d5a285b343d99d2fdea5f1029ee54f8dc8cd86a76
-  data.tar.gz: fe58b77da7a315e3f6aa3fd59f7c153fe8a0d342ffdbbdf923e4199e8ccba02b039c2cde777a7c9d1855d127563ef3f021171b308c1696f5f7446b9ac068430e
+  metadata.gz: ea87625511591d754116bda3a16849466d9d982c7ba8f69a773508e36142e224e9c9a9ed96335c2f1d28c28f285116a488caa5c34d4ab7704cb06b4bb1d14a3f
+  data.tar.gz: 701589715a07e31778aefd39c60d05f7bdd9c865d77d72517f0a3881054046067ae60c2dc3ae97ecebe6f8b1dfd238ab95de5dd12d3a163bbd0f63aefaba9f3a

data/CHANGELOG.md

@@ -1,6 +1,67 @@
 # Changelog
 
-## [0.6.0] — Unreleased
+## [0.7.0] — 2026-09-10
+
+Keeping the no-port promise when the machine's recorded port goes stale,
+and making boot legible while it happens.
+
+### Added
+
+- `Log::Report::Human` / `Log::Report::Json`: boot progress sinks, one
+  line per phase (`[web] ok (2.2s) healthcheck /up returned 2xx-3xx`).
+  `Readiness.phase`/`wait_all` take a `sink:` and never format output
+  themselves; `--json` emits one JSON object per event on stdout while
+  the human banner moves to stderr, so stdout stays parseable. The phase
+  events were previously computed and discarded — `opts[:events]` was
+  never set — so a 2-minute deps or healthcheck phase looked like a hang.
+- `ProxyControl.default_port?` / `port_notice`, and a `warn` state on
+  `Doctor::Check` (rendered `[warn]`, JSON `warn`/`warnings`, never
+  affecting exit status).
+
+### Fixed
+
+- **A stale recorded proxy port no longer sticks the machine on a
+  port.** `Context#proxy_port` trusted `proxy.port` unconditionally, so a
+  one-off `proxy start -p 1355` (CI, a sandbox, a gem-dev foreground
+  proxy) outlived its process: the next boot raised a fresh proxy on
+  1355 and put `:1355` in every URL — the single outcome yamine exists to
+  prevent. The recorded port is now honored only while something is
+  actually listening on it; otherwise the machine returns to the clean
+  default (443). An explicit `YAMINE_PORT` still wins.
+- **Attaching to a non-default port is now said out loud.** Both
+  `yamine start` and `yamine doctor` report it (`[warn] listening on port
+  1355 — every URL carries :1355 …`) instead of a bare "[ok] listening on
+  port 1355" that let a leftover dev proxy quietly downgrade every
+  project on the machine.
+- **`.localhost` no longer reports as unresolvable.** `Hosts.resolves?`
+  used `Resolv.getaddress` — a pure-Ruby DNS client with no nsswitch and
+  no RFC 6761 knowledge — so it returned "no address for
+  anyworkers.localhost" on a machine where `.localhost` resolves
+  perfectly, and `doctor` printed a `[FAIL] dns` while `yamine start`
+  advised `sudo yamine hosts sync` (an elevated /etc/hosts write) for a
+  problem that did not exist. It now asks the system resolver
+  (`Addrinfo.getaddrinfo`), which is what browsers and curl use.
+- `supervise_tree` names the process that exited and its log path
+  instead of "a process exited — cleaning up all routes".
+
+## [0.6.1] — 2026-09-10
+
+### Fixed
+
+- **Healthchecks no longer speak TLS to the backend.** `--wait` probed
+  `127.0.0.1:$PORT` — the app's own listener — with the *proxy's* `tls`
+  flag, so any app declaring `healthcheck: { path: }` could never boot
+  under the default TLS-on proxy: the probe began an SSL handshake
+  against a plaintext Puma, which logged `Invalid HTTP format, parsing
+  fails. Are you trying to open an SSL connection to a non-SSL Puma?`
+  once per attempt until the process phase timed out and the whole boot
+  was torn down. TLS is the proxy's job; the proxy dials backends with a
+  bare `TCPSocket`, so `Readiness.probe`/`probe_http`/`wait_healthy`/
+  `wait_all` drop the `tls:` keyword entirely (an `https://` banner URL
+  never implied the backend speaks TLS). Reported from anyworkers, whose
+  web process healthchecks `/up`.
+
+## [0.6.0] — 2026-09-09
 
 `yamine start --wait` + boot readiness protocol. The remaining gap from
 “one-storey building” onwards: boot had no definitive answer — agents

data/README.md

@@ -41,6 +41,15 @@ The only port-suffixed URLs are the ones you explicitly ask for:
 `yamine proxy start -p 1355` (CI/sandboxes where 443 is impossible).
 There the suffix is honest, and `YAMINE_URL` carries it faithfully.
 
+Because the port is recorded machine-wide, yamine refuses to let a
+one-off `-p` outlive its process: a recorded port is reused only while
+something is actually listening on it. Stop that proxy and the next
+`yamine` run goes back to the clean default (443) instead of quietly
+raising another proxy on 1355. `yamine doctor` and `yamine start` both
+say so out loud when a running proxy is on a non-default port — the
+`[warn]` line names the port, the `:PORT` it puts in every URL, and how
+to get back to 443.
+
 ## Port 443: one-time setup, then never again
 
 Binding 443 is privileged, so yamine installs a **root-owned launchd
@@ -95,7 +104,9 @@ Optional top-level `db: false` opts out of per-worktree databases
 (exotic setups — manual `establish_connection`, shared staging DB, …);
 `db.schema_load` overrides the schema-load command. Per-process
 `healthcheck: { path: /up, timeout: 30 }` declares what `--wait` polls
-(TCP accept when absent).
+(TCP accept when absent). The poll is plain HTTP against the app's own
+`127.0.0.1:$PORT` listener — TLS is terminated by the proxy, so the path
+is reached over http regardless of the `https://` URL in the banner.)
 
 `yamine init` creates the file (migrating an existing Procfile);
 Rails apps need no extra gem — yamine injects `RAILS_DEVELOPMENT_HOSTS`

data/lib/yamine/cli/boot.rb

@@ -25,6 +25,22 @@ module Yamine
         boot_all(ctx, resolved, opts)
       end
 
+      # Progress sink for the boot's phases. Human runs narrate to stderr
+      # (stdout is the payload); --json runs emit one JSON line per event
+      # on stdout. Without this the phase events were computed and thrown
+      # away (opts[:events] was never set), so a 2-minute dependency or
+      # healthcheck phase looked like a hang.
+      def reporter(json:)
+        json ? Log::Report::Json.new : Log::Report::Human.new
+      end
+
+      # Boot banner / URL lines. In --json mode they move to stderr so
+      # stdout stays pure JSON (one event per line, payload last) for
+      # agents that parse it; humans still get them on stdout.
+      def say(opts, message = "")
+        opts[:json] ? $stderr.puts(message) : puts(message)
+      end
+
       def run_explicit(ctx, args)
         run_inferred(ctx, args)
       end
@@ -43,7 +59,7 @@ module Yamine
         tld = resolved.tld
         host = resolved.host
         processes = resolved.processes
-        events = opts[:events]
+        events = opts[:events] || reporter(json: opts[:json])
 
         if processes.empty?
           $stderr.puts "Error: no processes in config/local.yml. Add at least one."
@@ -59,7 +75,7 @@ module Yamine
         # Pre-flight: verify runtime deps BEFORE spawning anything.
         # A missing bundle fails here in seconds with the fix, instead
         # of a 60s Puma crash-loop ending in "did not boot".
-        deps = Readiness.phase(:deps, "check", out: events) do
+        deps = Readiness.phase(:deps, "deps", sink: events) do
           ok, fix = Readiness.check_deps(Dir.pwd)
           raise fix unless ok
 
@@ -74,8 +90,8 @@ module Yamine
         children = []
         routes_registered = []
 
-        puts "yamine (#{service})"
-        puts "--"
+        say opts, "yamine (#{service})"
+        say opts, "--"
 
         # Per-worktree database: one database per directory so concurrent
         # agents never share tables. Resolved once, injected into every
@@ -86,14 +102,14 @@ module Yamine
         db_name = Database.name_for(Dir.pwd, env: rails_env,
           state_dir: ctx.store.dir)
         db_created, db_url = setup_database(ctx, resolved, db_name, events: events)
-        puts "  [db] #{db_name}#{db_created ? " (created)" : ""}" if db_url
+        events&.note("[db] #{db_name}#{db_created ? " (created)" : ""}") if db_url
 
         with_wait = !opts[:no_wait]
         spawn_plan = collect_spawns(ctx, runner, resolved, opts, db_url, children)
 
         if with_wait
           boot_concurrent(ctx, runner, resolved, opts, spawn_plan, children,
-            routes_registered, db_url, db_name, db_created)
+            routes_registered, db_url, db_name, db_created, events: events)
         else
           boot_sequential(ctx, runner, resolved, opts, spawn_plan, children,
             routes_registered, db_url, events: events)
@@ -101,17 +117,20 @@ module Yamine
 
         background = processes.select { |_, v| v["proxy"] == false }
         unless background.empty?
-          puts "  [background] #{background.keys.join(', ')}"
+          say opts, "  [background] #{background.keys.join(', ')}"
         end
 
-        puts
+        say opts
         ctx.report_unresolved(routes_registered.flat_map { |r| r[:hostnames] })
 
-        # Supervisor: exit when ANY child dies (loud cleanup).
-        all_pids = routes_registered.map { |r| r[:app].pid } + children.map { |c| c[:pid] }
+        # Supervisor: exit when ANY child dies (loud cleanup). pid => name
+        # so the message names the casualty instead of "a process".
+        named_pids = {}
+        routes_registered.each { |r| named_pids[r[:app].pid] = r[:app].name }
+        children.each { |c| named_pids[c[:pid]] = c[:name] }
         all_hostnames = routes_registered.flat_map { |r| r[:hostnames] }
-        trap_cleanup(ctx, all_hostnames, all_pids)
-        supervise_tree(ctx, all_hostnames, all_pids)
+        trap_cleanup(ctx, all_hostnames, named_pids.keys)
+        supervise_tree(ctx, all_hostnames, named_pids, reporter: events)
       end
 
       # One pass over config: background processes spawn immediately
@@ -148,7 +167,7 @@ module Yamine
       def boot_sequential(ctx, runner, resolved, opts, plan, children,
         routes_registered, db_url, events: nil)
         plan.each do |item|
-          puts "  [#{item[:name]}] #{item[:url]}"
+          say opts, "  [#{item[:name]}] #{item[:url]}"
           # Always allow the proxied hostname in Rails dev (Rails ignores
           # this env var when not a Rails app — safe for every framework).
           # DATABASE_URL points at this worktree's own database; non-Ruby
@@ -171,10 +190,10 @@ module Yamine
       # never leak into the proxy. A backend that dies before its route
       # registers is cleaned up like any other failed process.
       def boot_concurrent(ctx, runner, resolved, opts, plan, children,
-        routes_registered, db_url, db_name, db_created)
+        routes_registered, db_url, db_name, db_created, events: nil)
         apps = {}
         plan.each do |item|
-          puts "  [#{item[:name]}] #{item[:url]}"
+          say opts, "  [#{item[:name]}] #{item[:url]}"
           apps[item[:name]] = {
             item: item,
             app: runner.spawn_http(name: item[:name], hostname: item[:hostname],
@@ -183,7 +202,7 @@ module Yamine
               database_url: db_url, force: opts[:force])
           }
         end
-        wait_result = Readiness.wait_all(apps, tls: ctx.proxy_tls, out: nil)
+        wait_result = Readiness.wait_all(apps, sink: events)
         failed = wait_result.select { |r| r[:status] != "ok" }
 
         if failed.empty?
@@ -191,38 +210,45 @@ module Yamine
             runner.adopt(slot[:item][:hostname], slot[:app], force: opts[:force],
               spec: { "dir" => File.expand_path(Dir.pwd), "proc" => name })
             routes_registered << { hostnames: slot[:item][:hostnames], app: slot[:app] }
-            puts "  -> #{slot[:item][:url]}"
+            say opts, "  -> #{slot[:item][:url]}"
           end
         end
         finish_wait(ctx, resolved, apps, wait_result, failed, routes_registered,
           children, db_name, db_url, db_created, json: opts[:json])
       end
 
-      # --wait epilogue: on success the summary payload (URLs + per-process
-      # health) goes to stdout and boot continues into supervision. On
-      # failure every spawned child is killed and removed, the failure
-      # payload (failed phase + log tail) prints, and start exits 1 —
-      # no half-booted routes left behind.
+      # --wait epilogue. Success: the summary line and, with --json, the
+      # success payload on stdout (the human summary moves to stderr so
+      # stdout stays parseable). Failure: every spawned child is killed
+      # and removed, the failed phase + that process's log tail is
+      # reported, and start exits 1 — no half-booted routes left behind.
       def finish_wait(ctx, resolved, apps, wait_result, failed, routes_registered,
         children, db_name, db_url, db_created, json: false)
         urls = apps.transform_values { |slot| slot[:item][:url] }
+        summary = "ready: #{urls.map { |n, u| "#{n}=#{u}" }.join(" ")}"
+
         if failed.empty?
-          puts "ready: #{urls.map { |n, u| "#{n}=#{u}" }.join(" ")}"
           payload = Yamine::WaitPayload.success(resolved, wait_result, urls: urls,
-            db_name: db_name, db_url: db_url, created: db_created) if json
-          puts JSON.generate(payload) if json
+            db_name: db_name, db_url: db_url, created: db_created)
+          if json
+            $stderr.puts summary
+            puts JSON.generate(payload)
+          else
+            puts summary
+          end
           return
         end
 
         apps.each_value { |slot| stop_spawned(slot[:app]) }
         children.each { |c| stop_spawned_pid(c[:pid]) }
         first = failed.first
+        error = "Error: #{first[:name]} failed (#{first[:phase]}): #{first[:detail]}"
         payload = Yamine::WaitPayload.failure(resolved, wait_result, failed: first,
-          log_tail: tail_for(failed.first, apps))
+          log_tail: tail_for(first, apps))
+        $stderr.puts error
         if json
           puts JSON.generate(payload)
         else
-          $stderr.puts "Error: #{first[:name]} failed (#{first[:phase]}): #{first[:detail]}"
           $stderr.puts payload[:log_tail].to_s.lines.last(10).join if payload[:log_tail]
           $stderr.puts "Full log: #{payload[:log_path]}" if payload[:log_path]
         end
@@ -265,7 +291,7 @@ module Yamine
           force: opts[:force], rails_dev_host: nil, register: false,
           database_url: db_url)
         children << { name: proc_name, pid: app.pid }
-        puts "  [#{proc_name}] background (pid #{app.pid})"
+        say opts, "  [#{proc_name}] background (pid #{app.pid})"
       end
 
       # Refuse to boot over another agent's live routes unless forced.
@@ -335,7 +361,7 @@ module Yamine
         url = Database.url_for(db_name, template)
         return [false, nil] unless url
 
-        db_event = Readiness.phase(:db, "ensure #{db_name}", out: events) do
+        db_event = Readiness.phase(:db, "ensure #{db_name}", sink: events) do
           existed = Database.exists?(db_name, template)
           raise "database server unreachable — is postgres/mysql running?" unless Database.ensure_exists(db_name, template)
 
@@ -347,7 +373,7 @@ module Yamine
         end
         created = db_event.detail.to_s.start_with?("created")
 
-        schema_event = Readiness.phase(:schema, "load #{db_name}", out: events) do
+        schema_event = Readiness.phase(:schema, "load #{db_name}", sink: events) do
           next "skipped (already exists)" unless created
 
           run_schema_load(resolved, url)
@@ -437,15 +463,26 @@ module Yamine
         File.file?(File.join(Dir.pwd, "config", "application.rb"))
       end
 
-      def supervise_tree(ctx, hostnames, pids)
+      # Supervise the booted tree: the first child to exit ends the run,
+      # because a half-stack is worse than no stack — a dead jobs worker
+      # with a live web process looks healthy until someone wonders why
+      # nothing is being processed. Name the casualty and its log: "a
+      # process exited" left the user to guess which one, and the log
+      # worth reading is per-process.
+      def supervise_tree(ctx, hostnames, named_pids, reporter: nil)
         loop do
           sleep 0.5
-          if pids.any? { |pid| !ProxyControl.pid_alive?(pid) }
-            puts "\nA process exited — cleaning up all routes."
+          dead = named_pids.find { |pid, _| !ProxyControl.pid_alive?(pid) }
+          if dead
+            pid, name = dead
+            $stderr.puts "\n[#{name}] exited (pid #{pid}) — stopping the whole tree."
+            log = File.join(Dir.pwd, "log", "yamine-#{name}.log")
+            $stderr.puts "  log: #{log}" if File.file?(log)
+            reporter&.note("#{name} exited; cleaning up routes")
             cleanup_routes(ctx, hostnames)
             # Kill remaining children
-            pids.each do |pid|
-              Process.kill("TERM", pid) rescue nil
+            named_pids.each_key do |other|
+              Process.kill("TERM", other) rescue nil
             end
             exit 0
           end
@@ -515,7 +552,10 @@ module Yamine
         port = ctx.proxy_port
         tls = ctx.proxy_tls
         if ProxyControl.listening?(port)
-          return if ProxyControl.ours?(port, tls: tls)
+          if ProxyControl.ours?(port, tls: tls)
+            warn_non_default_port(port, tls)
+            return
+          end
           $stderr.puts "Error: port #{port} is in use by another process."
           $stderr.puts "  Stop it, or yamine proxy start -p <port>"
           exit 1
@@ -543,6 +583,24 @@ module Yamine
         $stderr.puts "  Fix once: yamine setup"
         exit 1
       end
+
+      # yamine's whole promise is a bare https://<app>.localhost. An
+      # already-running proxy on another port silently defeats it: every
+      # URL grows a :1355, which then leaks into OAuth callbacks, mailer
+      # hosts, and webhooks. The port file is machine-wide state, so a
+      # single `-p 1355` run (CI, a sandbox, a gem-dev foreground proxy)
+      # downgrades every project on the machine until someone notices.
+      #
+      # Not an error: CI and sandboxes opt into a port deliberately, and
+      # refusing would break them. So: proceed, but say plainly what the
+      # URL will look like and how to get the clean one back.
+      def warn_non_default_port(port, tls)
+        return if ENV["YAMINE_PORT"] && ENV["YAMINE_PORT"].to_i == port
+        notice = ProxyControl.port_notice(port, tls)
+        return unless notice
+
+        $stderr.puts "Warning: #{notice}"
+      end
     end
   end
 end

data/lib/yamine/cli/context.rb

@@ -15,8 +15,23 @@ module Yamine
         $stdin.tty? && ENV["CI"].nil?
       end
 
+      # The port the proxy is on, or the port it should be started on.
+      #
+      # The recorded port is machine-wide sticky state, and trusting it
+      # blindly is how a one-off `proxy start -p 1355` (CI, a sandbox, a
+      # gem-dev foreground proxy) downgrades the machine permanently: the
+      # file outlives the process, so the NEXT boot would raise a fresh
+      # proxy on 1355 and put a port in every URL again — the exact
+      # outcome yamine exists to prevent.
+      #
+      # So the recorded port is honored only while something is actually
+      # listening there. A dead proxy leaves the machine on the clean
+      # default (443), and an explicit YAMINE_PORT always wins.
       def proxy_port
-        ProxyControl.proxy_port(store) || ProxyControl.default_port(proxy_tls)
+        recorded = ProxyControl.proxy_port(store)
+        return recorded if recorded && ProxyControl.listening?(recorded)
+
+        ProxyControl.default_port(proxy_tls)
       end
 
       def proxy_tls

data/lib/yamine/doctor.rb

@@ -4,7 +4,15 @@ module Yamine
   # Read-only health checks: proxy, routes, DNS, CA trust.
   # Never changes state; safe for agents to call any time.
   module Doctor
-    Check = Struct.new(:name, :ok, :message, keyword_init: true)
+    # `warn` is a third state between ok and FAIL: the check passed, but
+    # something is configured in a way the user should know about and
+    # probably did not choose (a port-suffixed URL). Warnings never
+    # affect the exit status — only failures do.
+    Check = Struct.new(:name, :ok, :message, :warn, keyword_init: true) do
+      def warn?
+        warn ? true : false
+      end
+    end
 
     module_function
 
@@ -66,12 +74,23 @@ module Yamine
         return Check.new(name: "proxy", ok: false,
           message: "port #{port} not listening — run: yamine proxy start")
       end
-      if ProxyControl.ours?(port, tls: tls)
-        Check.new(name: "proxy", ok: true, message: "listening on port #{port}")
-      else
-        Check.new(name: "proxy", ok: false,
+      unless ProxyControl.ours?(port, tls: tls)
+        return Check.new(name: "proxy", ok: false,
           message: "port #{port} is in use by another process")
       end
+
+      # A proxy on a non-default port is legitimate — CI and sandboxes
+      # opt in with `-p` — but it makes EVERY url carry :PORT, which is
+      # the one thing yamine exists to avoid. Reporting that as a bare
+      # "[ok] listening on port 1355" let a stale dev proxy quietly
+      # downgrade every project on the machine.
+      notice = ProxyControl.port_notice(port, tls)
+      if notice
+        Check.new(name: "proxy", ok: true, warn: true,
+          message: "listening on port #{port} — #{notice}")
+      else
+        Check.new(name: "proxy", ok: true, message: "listening on port #{port}")
+      end
     end
 
     def check_routes(store)
@@ -116,14 +135,18 @@ module Yamine
       if json
         require "json"
         out.puts JSON.generate({
-          checks: checks.map { |c| { name: c.name, ok: c.ok, message: c.message } },
-          failed: checks.count { |c| !c.ok }
+          checks: checks.map { |c| { name: c.name, ok: c.ok, warn: c.warn?, message: c.message } },
+          failed: checks.count { |c| !c.ok },
+          warnings: checks.count(&:warn?)
         })
         return checks.count { |c| !c.ok }
       end
       failed = 0
       checks.each do |c|
-        mark = c.ok ? "ok" : "FAIL"
+        mark = if !c.ok then "FAIL"
+        elsif c.warn? then "warn"
+        else "ok"
+        end
         failed += 1 unless c.ok
         out.puts "  [#{mark}] #{c.name}: #{c.message}"
       end

data/lib/yamine/hosts.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require "resolv"
+require "socket"
 require "timeout"
 
 module Yamine
@@ -72,10 +72,21 @@ module Yamine
       false
     end
 
+    # Does the hostname resolve for the programs that will actually use
+    # it — browsers, curl, the app's own HTTP clients? That question can
+    # only be answered by the SYSTEM resolver (getaddrinfo), which reads
+    # nsswitch (so /etc/hosts counts) and implements the RFC 6761
+    # special-use TLDs.
+    #
+    # Ruby's Resolv is a pure-Ruby DNS client: it never sees /etc/hosts
+    # and knows nothing about RFC 6761, so it reports "no address for
+    # myapp.localhost" on a machine where .localhost resolves perfectly.
+    # That false negative sent users to `sudo yamine hosts sync` — an
+    # elevated write to /etc/hosts — to fix a problem they did not have.
     def resolves?(hostname)
-      Timeout.timeout(2) { Resolv.getaddress(hostname) }
+      Timeout.timeout(2) { Addrinfo.getaddrinfo(hostname, nil) }
       true
-    rescue Resolv::ResolvError, SystemCallError, Timeout::Error
+    rescue SocketError, SystemCallError, Timeout::Error
       false
     end
 

data/lib/yamine/log.rb

@@ -55,5 +55,62 @@ module Yamine
         "#{bytes} B"
       end
     end
+
+    # Boot progress sinks. Readiness emits one Event per phase; the sink
+    # decides how to render it. Rendering lives here rather than in
+    # Readiness so the human stream and the --json stream carry exactly
+    # the same events — a phase added to the boot loop shows up in both
+    # without touching either renderer.
+    module Report
+      # "  [web] ok (2.2s) healthcheck /up returned 2xx-3xx" — one line
+      # per completed phase, in the boot banner's bracket style.
+      class Human
+        def initialize(io = $stderr)
+          @io = io
+        end
+
+        def event(event)
+          @io.puts "  [#{event.action}] #{event.status} " \
+            "(#{format_seconds(event.duration_ms)})#{detail(event)}"
+        end
+
+        def note(message)
+          @io.puts "  #{message}"
+        end
+
+        private
+
+        def detail(event)
+          d = event.detail.to_s.strip
+          d.empty? ? "" : " #{d}"
+        end
+
+        # Durations are read by humans deciding whether to wait; a
+        # sub-second boot should not render as "0.0s".
+        def format_seconds(ms)
+          return "0ms" if ms.nil? || ms < 1000
+
+          format("%.1fs", ms / 1000.0)
+        end
+      end
+
+      # One JSON object per line — the agent contract. Same events, no
+      # prose.
+      class Json
+        def initialize(io = $stdout)
+          @io = io
+        end
+
+        def event(event)
+          require "json"
+          @io.puts JSON.generate(event.to_h)
+        end
+
+        def note(message)
+          require "json"
+          @io.puts JSON.generate({ note: message })
+        end
+      end
+    end
   end
 end

data/lib/yamine/proxy_control.rb

@@ -34,6 +34,26 @@ module Yamine
       tls ? DEFAULT_TLS_PORT : DEFAULT_PLAIN_PORT
     end
 
+    # Is this port the clean default for the current scheme — 443 for
+    # https, 80 for http? A default port yields bare
+    # `https://myapp.localhost` URLs; any other port appends :PORT to
+    # every one of them.
+    def default_port?(port, tls)
+      port == (tls ? DEFAULT_TLS_PORT : DEFAULT_PLAIN_PORT)
+    end
+
+    # Human explanation for a non-default port, or nil when the port is
+    # the clean default. Callers use this to surface the downgrade
+    # honestly instead of implying the proxy is misconfigured.
+    def port_notice(port, tls)
+      return nil if default_port?(port, tls)
+
+      "every URL carries :#{port} instead of a clean " \
+        "#{tls ? "https" : "http"}://<app>.localhost. Stop it and run " \
+        "`yamine setup` (or `yamine proxy start`) to move to port " \
+        "#{default_port(tls)}."
+    end
+
     def proxy_tls(store)
       marker = File.join(store.dir, "proxy.tls")
       return false if ENV["YAMINE_HTTPS"] == "0"

data/lib/yamine/readiness.rb

@@ -3,7 +3,6 @@
 require "json"
 require "net/http"
 require "open3"
-require "openssl"
 require "socket"
 require "timeout"
 require "uri"
@@ -39,7 +38,10 @@ module Yamine
 
     # Run a phase with timing + timeout. Yields; returns the Event.
     # On timeout or raise, status is "fail" with the error as detail.
-    def phase(name, action, timeout: nil, out: nil)
+    #
+    # `sink` renders the event (Log::Report::Human for people, Json for
+    # agents); nil means silent. Readiness itself never formats output.
+    def phase(name, action, timeout: nil, sink: nil)
       timeout ||= DEFAULT_TIMEOUTS.fetch(name, 30)
       started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
       event = nil
@@ -57,7 +59,7 @@ module Yamine
         event = Event.new(phase: name, action: action, status: "fail",
           duration_ms: ms, detail: e.message.lines.first&.strip)
       end
-      out&.puts(JSON.generate(event.to_h)) if out
+      sink&.event(event)
       event
     end
 
@@ -89,11 +91,17 @@ module Yamine
     # Poll an HTTP route until healthy or timeout. Healthy = healthcheck
     # path returns 2xx-3xx, or (no healthcheck) TCP accept on the port.
     # Returns [healthy, detail].
-    def wait_healthy(hostname, port:, tls:, path: nil, timeout: 30)
+    #
+    # Probes are plaintext by construction: the target is the app's OWN
+    # listener (127.0.0.1:$PORT). TLS is terminated by the proxy, which
+    # dials backends with a bare TCPSocket (Proxy#connect_backend), so a
+    # `tls:` flag taken from the proxy must never reach here — an
+    # https:// URL in the banner does not mean the backend speaks TLS.
+    def wait_healthy(hostname, port:, path: nil, timeout: 30)
       deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
       last_error = "not yet attempted"
       until Process.clock_gettime(Process::CLOCK_MONOTONIC) > deadline
-        ok, detail = probe(hostname, port, tls: tls, path: path)
+        ok, detail = probe(hostname, port, path: path)
         return [true, nil] if ok
 
         last_error = detail
@@ -102,9 +110,9 @@ module Yamine
       [false, last_error]
     end
 
-    def probe(hostname, port, tls:, path: nil)
+    def probe(hostname, port, path: nil)
       if path
-        probe_http(hostname, port, tls: tls, path: path)
+        probe_http(hostname, port, path: path)
       else
         probe_tcp(port)
       end
@@ -117,10 +125,8 @@ module Yamine
       [false, e.message.lines.first&.strip]
     end
 
-    def probe_http(hostname, port, tls:, path:)
+    def probe_http(hostname, port, path:)
       http = Net::HTTP.new("127.0.0.1", port)
-      http.use_ssl = tls
-      http.verify_mode = OpenSSL::SSL::VERIFY_NONE if tls
       http.open_timeout = 3
       http.read_timeout = 5
       res = http.get(path, { "Host" => hostname })
@@ -140,17 +146,17 @@ module Yamine
     # or "timeout" (never answered within its healthcheck timeout).
     # Dead-pid short-circuit: a reaped backend fails immediately
     # instead of burning its full timeout on connection-refused.
-    def wait_all(apps, tls: true, out: nil)
+    def wait_all(apps, sink: nil)
       threads = apps.map do |name, slot|
         Thread.new do
-          Thread.current[:result] = wait_one(name, slot, tls: tls, out: out)
+          Thread.current[:result] = wait_one(name, slot, sink: sink)
         end
       end
       threads.each(&:join)
       threads.map { |t| t[:result] }
     end
 
-    def wait_one(name, slot, tls:, out:)
+    def wait_one(name, slot, sink:)
       item = slot[:item]
       app = slot[:app]
       hc = item[:entry]["healthcheck"] || {}
@@ -163,12 +169,12 @@ module Yamine
         unless process_alive?(app.pid)
           ms = elapsed_ms(started)
           return fail_result(name, started, ms,
-            "process exited before becoming healthy — see log/yamine-#{name}.log", out)
+            "process exited before becoming healthy — see log/yamine-#{name}.log", sink)
         end
-        ok, detail = probe(item[:hostname], item[:port], tls: tls, path: path)
+        ok, detail = probe(item[:hostname], item[:port], path: path)
         if ok
           ms = elapsed_ms(started)
-          return ok_result(name, started, ms, path, out)
+          return ok_result(name, started, ms, path, sink)
         end
         last_error = detail
         sleep 0.5
@@ -179,22 +185,22 @@ module Yamine
         "process exited before becoming healthy — see log/yamine-#{name}.log"
       event = Event.new(phase: "process", action: name, status: status,
         duration_ms: ms, detail: detail)
-      out&.puts(JSON.generate(event.to_h)) if out
+      sink&.event(event)
       { name: name, status: status, phase: "process", detail: detail, duration_ms: ms }
     end
 
-    def ok_result(name, started, ms, path, out)
+    def ok_result(name, started, ms, path, sink)
       detail = path ? "healthcheck #{path} returned 2xx-3xx" : "port accepted connection"
       event = Event.new(phase: "process", action: name, status: "ok",
         duration_ms: ms, detail: detail)
-      out&.puts(JSON.generate(event.to_h)) if out
+      sink&.event(event)
       { name: name, status: "ok", phase: "process", detail: detail, duration_ms: ms }
     end
 
-    def fail_result(name, started, ms, detail, out)
+    def fail_result(name, started, ms, detail, sink)
       event = Event.new(phase: "process", action: name, status: "fail",
         duration_ms: ms, detail: detail)
-      out&.puts(JSON.generate(event.to_h)) if out
+      sink&.event(event)
       { name: name, status: "fail", phase: "process", detail: detail, duration_ms: ms }
     end
 

data/lib/yamine/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Yamine
-  VERSION = "0.6.0"
+  VERSION = "0.7.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: yamine
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.7.0
 platform: ruby
 authors:
 - Kaka Ruto