yamine 0.4.0 → 0.6.0

data/lib/yamine/cli/system.rb

@@ -657,18 +657,28 @@ module Yamine
       def start(ctx, args)
         if args.include?("--help") || args.include?("-h")
           puts <<~HELP
-            Usage: yamine start [name] [cmd...] [options]
+            Usage: yamine start [options]
 
             One-setup-and-go: if the workstation isn't ready (CA, proxy,
             hosts), runs the minimal needed setup first, then boots the
             app in the current directory.
 
-              yamine start              # infer name, boot -> https://<app>.localhost
-              yamine start myapp       # explicit name
+              yamine start              # block until every route is healthy, then supervise
+              yamine start --no-wait   # fire-and-forget (register routes immediately)
+              yamine start --json       # machine-readable result payload (--wait only)
               yamine start -- --help   # pass --help to the app, not here
 
             Options are passed through to the boot path:
-              --name <name> --service <svc> --variant <v> --tld <tld> --branch
+              --variant <v> --tld <tld> --force --app-port <port>
+              --wait (alias, default) --no-wait --json
+
+            Default waits: every process is spawned concurrently, each
+            healthcheck (or TCP accept when none is declared) is polled,
+            routes are registered only when all are healthy, and `ready:`
+            is printed with exit 0. On failure everything spawned is
+            killed, the failed process + its log tail is printed, and
+            the CLI exits 1 — no half-booted routes. `--no-wait` keeps
+            the old fire-and-forget path.
 
             Setup failures become hard errors pointing at `yamine setup`;
             non-interactive CI without a running proxy exits immediately.
@@ -763,6 +773,134 @@ module Yamine
         puts "    - #{app}-#{slug}.#{domain}"
         puts "  # Prefer Kamal multi-host for production; single-host preview above is fine for ephemeral branches."
       end
+
+      # Per-worktree databases: list/create/drop, plus orphan cleanup.
+      # `db list` shows every claimed database with its worktree dir.
+      # `db create` resolves this worktree's name and creates it.
+      # `db drop <name>` drops one database (refuses without --force
+      # when its worktree still exists).
+      def db(ctx, args)
+        sub = args.first
+        case sub
+        when "list", nil then db_list(ctx)
+        when "create" then db_create(ctx)
+        when "drop" then db_drop(ctx, args[1..] || [])
+        else raise Error, "Usage: yamine db [list|create|drop <name> [--force]]"
+        end
+      end
+
+      def db_list(ctx)
+        map = Database.load_map(ctx.store.dir)
+        if map.empty?
+          puts "No worktree databases claimed yet."
+          puts "Boot an app with a DATABASE_URL template to create one."
+          return
+        end
+        map.each do |name, info|
+          alive = File.directory?(info["dir"]) ? "" : " (worktree gone)"
+          puts "  #{name}  ->  #{info["dir"]}#{alive}"
+        end
+      end
+
+      def db_create(ctx)
+        resolved = Resolver.resolve(Dir.pwd)
+        name = Database.name_for(Dir.pwd, env: boot_env_name,
+          state_dir: ctx.store.dir)
+        template = ENV["DATABASE_URL"]
+        unless template && !template.strip.empty?
+          $stderr.puts "Error: set DATABASE_URL (template with host/user; database segment is replaced)."
+          exit 1
+        end
+        if Database.ensure_exists(name, template)
+          puts "Database #{name} ready."
+        else
+          $stderr.puts "Error: could not create #{name}. Check the database server is running."
+          exit 1
+        end
+      end
+
+      def db_drop(ctx, args)
+        force = args.delete("--force")
+        name = args.first
+        raise Error, "Usage: yamine db drop <name> [--force]" unless name
+
+        map = Database.load_map(ctx.store.dir)
+        info = map[name]
+        if info && File.directory?(info["dir"]) && !force
+          $stderr.puts "Error: worktree #{info["dir"]} still exists. Use --force to drop #{name} anyway."
+          exit 1
+        end
+        if drop_database(ctx, name)
+          map.delete(name)
+          Database.save_map(ctx.store.dir, map)
+          puts "Dropped #{name}."
+        else
+          $stderr.puts "Error: could not drop #{name}."
+          exit 1
+        end
+      end
+
+      def drop_database(_ctx, name)
+        template = ENV["DATABASE_URL"]
+        return false unless template && !template.strip.empty?
+
+        case Database.adapter_for(template)
+        when :postgres
+          uri = URI.parse(template)
+          _out, status = Open3.capture2("dropdb", name, env: Database.pg_env(uri))
+          status.success?
+        when :mysql
+          uri = URI.parse(template)
+          args = ["-h", uri.host || "127.0.0.1", "-u",
+                  URI.decode_www_form_component(uri.user || "root")]
+          _out, status = Open3.capture2("mysqladmin", *args, "drop", name, "-f")
+          status.success?
+        else
+          false
+        end
+      rescue SystemCallError
+        false
+      end
+
+      def boot_env_name
+        ENV.fetch("RAILS_ENV", "development")
+      end
+
+      # Worktree helpers: list claimed databases with liveness, clean
+      # drops databases whose worktree dirs are gone.
+      def worktree(ctx, args)
+        sub = args.first
+        case sub
+        when "list", nil
+          map = Database.load_map(ctx.store.dir)
+          if map.empty?
+            puts "No worktree databases claimed yet."
+            return
+          end
+          map.each do |name, info|
+            alive = File.directory?(info["dir"]) ? "alive" : "gone"
+            puts "  #{name}  #{info["dir"]}  (#{alive})"
+          end
+        when "clean"
+          orphaned = Database.orphaned(ctx.store.dir)
+          if orphaned.empty?
+            puts "No orphaned worktree databases."
+            return
+          end
+          orphaned.each do |name, _info|
+            if drop_database(ctx, name)
+              puts "Dropped orphaned #{name}."
+            else
+              $stderr.puts "Could not drop #{name} — remove manually."
+            end
+          end
+          map = Database.load_map(ctx.store.dir)
+          orphaned.each_key { |name| map.delete(name) }
+          Database.save_map(ctx.store.dir, map)
+        else
+          raise Error, "Usage: yamine worktree [list|clean]"
+        end
+      end
     end
   end
 end

data/lib/yamine/cli.rb

@@ -10,7 +10,7 @@ module Yamine
   # In non-interactive environments (no TTY or CI=1) we fail early with
   # a clear message instead of prompting (portless lesson).
   class CLI
-    SUBCOMMANDS = %w[run get alias hosts list doctor trust clean prune proxy service sudoers kamal stop restart log status open setup start init].freeze
+    SUBCOMMANDS = %w[run get alias hosts list doctor trust clean prune proxy service sudoers kamal stop restart log status open setup start init db worktree].freeze
 
     def self.run(argv)
       new.run(argv)
@@ -47,6 +47,8 @@ module Yamine
       when "setup" then SystemCommand.setup(ctx, args)
       when "init" then SystemCommand.init(ctx, args)
       when "start" then SystemCommand.start(ctx, args)
+      when "db" then SystemCommand.db(ctx, args)
+      when "worktree" then SystemCommand.worktree(ctx, args)
       when "kamal" then SystemCommand.kamal(ctx, args)
       when "stop"
         exit RoutesCommand.stop(ctx, args)
@@ -81,6 +83,8 @@ module Yamine
           yamine trust                  Add local CA to trust store
           yamine clean                  Remove state and hosts entries
           yamine prune                  Remove stale routes
+          yamine db list|create|drop      Per-worktree databases
+          yamine worktree list|clean     Worktree databases + orphan cleanup
           yamine proxy start|stop       Control the proxy
           yamine service install|status|uninstall   OS startup service
           yamine sudoers                Print scoped passwordless-sudo rules for port 443
@@ -90,8 +94,7 @@ module Yamine
           yamine restart                Touch tmp/restart.txt
           yamine log [-f] [n]           Tail (or follow) this app's backend log
 
-        Flags: --name, --service, --variant, --tld, --branch, --force,
-               --app-port, --proc (pick a Procfile process, e.g. --proc web)
+        Flags: --variant, --tld, --force, --app-port, --wait (default), --no-wait, --json
         Env: YAMINE_NAME/SERVICE/VARIANT/TLD/PORT/STATE_DIR, YAMINE_BRANCH=1
       HELP
     end

data/lib/yamine/config.rb

@@ -53,6 +53,10 @@ module Yamine
         "tld" => "localhost",
         "host" => "myapp.local.example.com"
       },
+      # db: false opts out of per-worktree databases entirely (exotic
+      # setups: manual establish_connection, shared staging DB, ...).
+      # Absent means enabled. A mapping holds future db options.
+      "db" => false,
       "processes" => {
         "web" => {
           "cmd" => "bin/rails server -p $PORT",
@@ -238,6 +242,9 @@ module Yamine
       if data["proxy"]
         validate_proxy(data["proxy"], "#{@path} proxy")
       end
+      if data.key?("db")
+        validate_db(data["db"], "#{@path} db")
+      end
       if data["processes"]
         validate_processes(data["processes"], "#{@path} processes")
       end
@@ -269,6 +276,11 @@ module Yamine
       end
     end
 
+    def validate_db(value, context)
+      return if value == false
+      raise ConfigError, "#{context} must be false or a mapping" unless value.is_a?(Hash)
+    end
+
     def validate_processes(value, context)
       raise ConfigError, "#{context} must be a mapping" unless value.is_a?(Hash)
       raise ConfigError, "#{context} must list at least one process" if value.empty?

data/lib/yamine/database.rb

@@ -0,0 +1,216 @@
+# frozen_string_literal: true
+
+require "digest"
+require "fileutils"
+require "json"
+require "open3"
+
+module Yamine
+  # Per-worktree databases. Every worktree directory gets its own database
+  # so concurrent agents never share tables: no migration races, no seed
+  # pollution, no schema drift between branches.
+  #
+  # Naming: <sanitized-dir-basename>_<env> — e.g. /Users/kaka/code/myapp-fix
+  # becomes myapp_fix_development. The branch a worktree has checked out is
+  # irrelevant and mutable, so it plays no part; the directory is stable.
+  # The main checkout keeps the bare <basename>_<env> name. Postgres
+  # identifiers cap at 63 bytes; overlong names truncate with a hash
+  # suffix (same rule as hostname labels).
+  #
+  # Collision guard: two directories can sanitize identically
+  # (myapp-fix vs myapp_fix). A state file records which directory
+  # claimed which name first; on collision the newcomer gets a short
+  # hash suffix. Silent sharing would be exactly the bug this exists to
+  # kill, so the check is mandatory, not best-effort.
+  #
+  # Framework-agnostic: yamine injects DATABASE_URL and never touches
+  # framework files. SQLite needs nothing (relative paths already isolate
+  # per worktree). Creation runs the app's own schema-load command from
+  # config/local.yml — never assumed.
+  module Database
+    module_function
+
+    MAX_IDENTIFIER_BYTES = 63
+    STATE_FILE = "databases.json"
+
+    # Database name for a worktree dir + env (development/test).
+    # Main checkout (no worktree marker) keeps the bare name.
+    def name_for(dir, env: "development", state_dir: nil)
+      base = sanitize(File.basename(File.expand_path(dir)))
+      name = "#{base}_#{env}"
+      name = truncate(name)
+      claimed = claim(name, dir, state_dir: state_dir)
+      claimed || "#{truncate("#{base}_#{short_hash(dir)}")}_#{env}"
+    end
+
+    # The main checkout is the one whose .git is a directory (linked
+    # worktrees have a .git FILE pointing into /worktrees/). Main keeps
+    # the bare name; only linked worktrees get suffixed names... in
+    # practice every dir gets the mapping, but main's mapping is itself.
+    def main_checkout?(dir)
+      File.directory?(File.join(File.expand_path(dir), ".git"))
+    end
+
+    def sanitize(name)
+      name.downcase.gsub(/[^a-z0-9_]/, "_").gsub(/_+/, "_").gsub(/\A_+|_+\z/, "")
+    end
+
+    def truncate(name)
+      return name if name.bytesize <= MAX_IDENTIFIER_BYTES
+
+      hash = Digest::SHA256.hexdigest(name)[0, 6]
+      prefix = name.byteslice(0, MAX_IDENTIFIER_BYTES - 7).gsub(/_+\z/, "")
+      "#{prefix}_#{hash}"
+    end
+
+    def short_hash(dir)
+      Digest::SHA256.hexdigest(File.expand_path(dir))[0, 6]
+    end
+
+    # Record dir -> name claim; returns the name if ours (or unclaimed),
+    # nil if another dir claimed it first (caller must suffix).
+    def claim(name, dir, state_dir: nil)
+      return name unless state_dir
+
+      dir = File.expand_path(dir)
+      map = load_map(state_dir)
+      if map.key?(name) && map[name]["dir"] != dir
+        return nil
+      end
+      map[name] = { "dir" => dir, "claimed_at" => Time.now.utc.iso8601 }
+      save_map(state_dir, map)
+      name
+    rescue SystemCallError
+      name
+    end
+
+    def load_map(state_dir)
+      path = File.join(state_dir, STATE_FILE)
+      return {} unless File.file?(path)
+
+      JSON.parse(File.read(path))
+    rescue JSON::ParserError, SystemCallError
+      {}
+    end
+
+    def save_map(state_dir, map)
+      FileUtils.mkdir_p(state_dir)
+      File.write(File.join(state_dir, STATE_FILE), JSON.pretty_generate(map))
+    rescue SystemCallError
+      nil
+    end
+
+    # Databases whose worktree dirs no longer exist (for `worktree clean`).
+    def orphaned(state_dir)
+      load_map(state_dir).select { |_, v| !File.directory?(v["dir"]) }
+    end
+
+    # Adapter detection from DATABASE_URL scheme. Returns :postgres,
+    # :mysql, :sqlite, or :unknown. Only postgres/mysql get create +
+    # DATABASE_URL treatment; sqlite is left alone (relative paths
+    # already isolate per worktree).
+    def adapter_for(database_url)
+      str = database_url.to_s.strip
+      return :sqlite if str.empty?
+
+      scheme = str[/\A[a-z0-9+]+/i].to_s.downcase
+      case scheme
+      when "postgres", "postgresql" then :postgres
+      when "mysql", "mysql2" then :mysql
+      when "sqlite", "sqlite3" then :sqlite
+      else :unknown
+      end
+    end
+
+    # Build a DATABASE_URL for name from a template URL (host, port, user
+    # preserved; database segment replaced). Returns nil when the template
+    # is absent or sqlite.
+    def url_for(name, template_url)
+      return nil if template_url.nil? || template_url.strip.empty?
+      return nil if adapter_for(template_url) == :sqlite
+
+      uri = URI.parse(template_url)
+      uri.path = "/#{name}"
+      uri.to_s
+    rescue URI::InvalidURIError
+      nil
+    end
+
+    # True when the named database already exists. False covers both
+    # missing and unreachable server — ensure_exists decides creation.
+    def exists?(name, database_url)
+      case adapter_for(database_url)
+      when :postgres then pg_exists?(name, database_url)
+      when :mysql then mysql_exists?(name, database_url)
+      else false
+      end
+    end
+
+    # Create the database if missing. Uses createdb/mysqladmin when
+    # available; returns true/false, never raises (boot reports, not dies).
+    def ensure_exists(name, database_url)
+      case adapter_for(database_url)
+      when :postgres then ensure_postgres(name, database_url)
+      when :mysql then ensure_mysql(name, database_url)
+      else false
+      end
+    end
+
+    def ensure_postgres(name, database_url)
+      uri = URI.parse(database_url)
+      env = pg_env(uri)
+      return true if pg_exists?(name, database_url)
+
+      _out, status = Open3.capture2(env, "createdb", name)
+      status.success?
+    rescue SystemCallError
+      false
+    end
+
+    def pg_exists?(name, database_url)
+      uri = URI.parse(database_url)
+      out, status = Open3.capture2(pg_env(uri), "psql", "-lqt")
+      return false unless status.success?
+
+      out.split("\n").any? do |line|
+        line.split("|").first.to_s.strip == name
+      end
+    rescue SystemCallError
+      false
+    end
+
+    def mysql_exists?(name, database_url)
+      uri = URI.parse(database_url)
+      args = mysql_args(uri)
+      out, status = Open3.capture2("mysql", *args, "-e", "SHOW DATABASES;")
+      status.success? && out.split("\n").include?(name)
+    rescue SystemCallError
+      false
+    end
+
+    def ensure_mysql(name, database_url)
+      uri = URI.parse(database_url)
+      args = mysql_args(uri)
+      _out, status = Open3.capture2("mysqladmin", *args, "create", name)
+      status.success? || mysql_exists?(name, database_url)
+    rescue SystemCallError
+      false
+    end
+
+    def mysql_args(uri)
+      args = ["-h", uri.host || "127.0.0.1", "-P", (uri.port || 3306).to_s,
+              "-u", URI.decode_www_form_component(uri.user || "root")]
+      args += ["-p#{URI.decode_www_form_component(uri.password)}"] if uri.password
+      args
+    end
+
+    def pg_env(uri)
+      {
+        "PGHOST" => uri.host || "127.0.0.1",
+        "PGPORT" => (uri.port || 5432).to_s,
+        "PGUSER" => URI.decode_www_form_component(uri.user || ENV["USER"].to_s),
+        "PGPASSWORD" => uri.password ? URI.decode_www_form_component(uri.password) : nil
+      }.compact
+    end
+  end
+end

data/lib/yamine/readiness.rb

@@ -0,0 +1,232 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "open3"
+require "openssl"
+require "socket"
+require "timeout"
+require "uri"
+
+module Yamine
+  # Phased boot readiness: every boot step emits a structured event
+  # (phase, action, status, duration_ms, detail) so agents get one call
+  # with a definitive answer instead of polling logs and guessing.
+  #
+  # Phases: deps (bundle check etc) -> db (create) -> schema (load) ->
+  # process (spawn + healthcheck per process). Each phase has its own
+  # timeout; a timeout reports that phase's logs, not the whole tree's.
+  #
+  # `start --wait` blocks until every HTTP route is healthy and exits 0
+  # with a summary payload, or non-zero with the failed phase + log tail.
+  module Readiness
+    module_function
+
+    DEFAULT_TIMEOUTS = {
+      deps: 30,
+      db: 15,
+      schema: 90,
+      process: 45
+    }.freeze
+
+    Event = Struct.new(:phase, :action, :status, :duration_ms, :detail,
+      keyword_init: true) do
+      def to_h
+        { phase: phase, action: action, status: status,
+          duration_ms: duration_ms, detail: detail }.compact
+      end
+    end
+
+    # 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)
+      timeout ||= DEFAULT_TIMEOUTS.fetch(name, 30)
+      started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      event = nil
+      begin
+        result = Timeout.timeout(timeout) { yield }
+        ms = elapsed_ms(started)
+        event = Event.new(phase: name, action: action, status: "ok",
+          duration_ms: ms, detail: result.is_a?(String) ? result : nil)
+      rescue Timeout::Error
+        ms = elapsed_ms(started)
+        event = Event.new(phase: name, action: action, status: "timeout",
+          duration_ms: ms, detail: "exceeded #{timeout}s")
+      rescue StandardError => e
+        ms = elapsed_ms(started)
+        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
+      event
+    end
+
+    def elapsed_ms(started)
+      ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - started) * 1000).round
+    end
+
+    # Pre-flight: verify runtime dependencies before spawning anything.
+    # Ruby (bundle check), Node (node_modules present). Returns [ok, fix].
+    # Fast-fails with the fix instead of letting Puma crash-loop for 60s.
+    def check_deps(dir = Dir.pwd)
+      gemfile = File.join(dir, "Gemfile")
+      if File.file?(gemfile)
+        _out, status = Open3.capture2("bundle", "check", chdir: dir,
+          err: File::NULL)
+        unless status.success?
+          return [false, "gems missing — run `bundle install` in #{dir}"]
+        end
+      end
+      package = File.join(dir, "package.json")
+      if File.file?(package) && !File.directory?(File.join(dir, "node_modules"))
+        return [false, "node_modules missing — run `npm install` in #{dir}"]
+      end
+      [true, nil]
+    rescue SystemCallError => e
+      [false, e.message.lines.first&.strip]
+    end
+
+    # 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)
+      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)
+        return [true, nil] if ok
+
+        last_error = detail
+        sleep 0.5
+      end
+      [false, last_error]
+    end
+
+    def probe(hostname, port, tls:, path: nil)
+      if path
+        probe_http(hostname, port, tls: tls, path: path)
+      else
+        probe_tcp(port)
+      end
+    end
+
+    def probe_tcp(port)
+      TCPSocket.new("127.0.0.1", port).close
+      [true, nil]
+    rescue SystemCallError => e
+      [false, e.message.lines.first&.strip]
+    end
+
+    def probe_http(hostname, port, tls:, 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 })
+      if res.code.to_i.between?(200, 399)
+        [true, nil]
+      else
+        [false, "HTTP #{res.code} on #{path}"]
+      end
+    rescue StandardError => e
+      [false, e.message.lines.first&.strip]
+    end
+
+    # Wait for every spawned app concurrently. Each entry: name =>
+    # { item: {entry, hostname, port...}, app: <Runner::App> }.
+    # Returns an array of result hashes: {name, status, phase, detail,
+    # duration_ms}. status is "ok", "fail" (died with log tail hint),
+    # 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)
+      threads = apps.map do |name, slot|
+        Thread.new do
+          Thread.current[:result] = wait_one(name, slot, tls: tls, out: out)
+        end
+      end
+      threads.each(&:join)
+      threads.map { |t| t[:result] }
+    end
+
+    def wait_one(name, slot, tls:, out:)
+      item = slot[:item]
+      app = slot[:app]
+      hc = item[:entry]["healthcheck"] || {}
+      path = hc["path"]
+      timeout = hc["timeout"] || DEFAULT_TIMEOUTS[:process]
+      started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      deadline = started + timeout
+      last_error = "not yet attempted"
+      until Process.clock_gettime(Process::CLOCK_MONOTONIC) > deadline
+        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)
+        end
+        ok, detail = probe(item[:hostname], item[:port], tls: tls, path: path)
+        if ok
+          ms = elapsed_ms(started)
+          return ok_result(name, started, ms, path, out)
+        end
+        last_error = detail
+        sleep 0.5
+      end
+      ms = elapsed_ms(started)
+      status = process_alive?(app.pid) ? "timeout" : "fail"
+      detail = process_alive?(app.pid) ? "no healthy response within #{timeout}s (#{last_error})" :
+        "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
+      { name: name, status: status, phase: "process", detail: detail, duration_ms: ms }
+    end
+
+    def ok_result(name, started, ms, path, out)
+      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
+      { name: name, status: "ok", phase: "process", detail: detail, duration_ms: ms }
+    end
+
+    def fail_result(name, started, ms, detail, out)
+      event = Event.new(phase: "process", action: name, status: "fail",
+        duration_ms: ms, detail: detail)
+      out&.puts(JSON.generate(event.to_h)) if out
+      { name: name, status: "fail", phase: "process", detail: detail, duration_ms: ms }
+    end
+
+    def process_alive?(pid)
+      Process.kill(0, pid)
+      true
+    rescue SystemCallError
+      false
+    end
+  end
+
+  # Machine-readable --wait payloads. Success carries URLs + per-process
+  # health + db provenance; failure names the first failed process, its
+  # phase, and the tail of its own log.
+  module WaitPayload
+    module_function
+
+    def success(resolved, wait_result, urls:, db_name:, db_url:, created:)
+      { ok: true, service: resolved.app,
+        urls: urls,
+        processes: wait_result.map { |r|
+          { name: r[:name], status: r[:status], duration_ms: r[:duration_ms] }
+        },
+        db: db_url ? { name: db_name, url: db_url, created: created } : nil }.compact
+    end
+
+    def failure(resolved, wait_result, failed:, log_tail:)
+      { ok: false, service: resolved.app,
+        failed_process: failed[:name], phase: failed[:phase],
+        detail: failed[:detail],
+        processes: wait_result.map { |r| { name: r[:name], status: r[:status] } },
+        log_path: log_tail[:path], log_tail: log_tail[:tail] }.compact
+    end
+  end
+end