yamine 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0c28579a9f53f3078412006a6f697d366cd7f0b2f897e7cf52025b742b2d5ba2
-  data.tar.gz: e7c826ffece34cf08ac88fcb31d1613418a9f3f5713badb08f6725937d906409
+  metadata.gz: 1fef68ea493be93af6dfb3271b446b793536a373d11b030f62e54c0d90438e88
+  data.tar.gz: 69c64d3bd1523b05ca6277f76329e20415879f16c95cd0640e30c9adf77f69cf
 SHA512:
-  metadata.gz: e1a77d9dad1424f4cdbd0fa351224f626a858e986c6300063a70650dc7c02007f8ea8cbb83e2658a5f06e1a3ff8ba091986ce1480c28e510d9a096c287cc596d
-  data.tar.gz: 9194bc35c52acdb669a177bb758af0539c2983056c8e7e4dbd700d937ea850a2947708fef0315d8e2d6281b33850bb96a2de4f26abb0878a2b1b8d3db91cd777
+  metadata.gz: 2864def84f4afefe2dd79adda834a2381964e964da864f99c8740321c19559669ad48874cce4485222c0a09d5a285b343d99d2fdea5f1029ee54f8dc8cd86a76
+  data.tar.gz: fe58b77da7a315e3f6aa3fd59f7c153fe8a0d342ffdbbdf923e4199e8ccba02b039c2cde777a7c9d1855d127563ef3f021171b308c1696f5f7446b9ac068430e

data/CHANGELOG.md

@@ -1,5 +1,48 @@
 # Changelog
 
+## [0.6.0] — Unreleased
+
+`yamine start --wait` + boot readiness protocol. The remaining gap from
+“one-storey building” onwards: boot had no definitive answer — agents
+polled, guessed from logs, and raced half-booted routes. Now every phase
+(deps, db, schema, per-process health) has a real event and `--wait`
+delivers one call with a pass/fail payload. Credentials-only DB URLs
+warn loudly instead of sharing silently.
+
+### Added
+
+- `Yamine::Readiness`: phased events (`phase`, `action`, `status`,
+  `duration_ms`, `detail`), `check_deps` pre-flight, `wait_healthy`
+  (healthcheck path or TCP accept), concurrent `wait_all` (one thread
+  per process, dead-pid short-circuit so a crash fails fast), per-phase
+  timeouts (deps 30s, db 15s, schema 90s, process 45s or per-healthcheck
+  timeout). `Yamine::WaitPayload` success/failure payloads for `--json`.
+- `yamine start --wait [--json]`: spawns every process, polls until
+  healthy, registers routes only on success, kills everything (including
+  background children) and exits 1 with the failed phase + that process's
+  own log tail on failure — no half-booted routes. `--wait` is kept as a no-op alias;
+  `--no-wait` keeps the old sequential fire-and-forget path.
+  `--json` is only meaningful with wait (now default).
+- Per-process `healthcheck: { path: /up, timeout: 30 }` in
+  `config/local.yml`, respected by `--wait`. Absent means TCP accept.
+- Boot phases now visible: deps pre-flight, db (`exists?`/`ensure_exists`
+  split so provenance doesn't need a second probe), schema, per-process.
+  `Runner#spawn_http`/`adopt`/`spawned?` support the concurrent path;
+  `boot_run` child output is logged so failure payloads can tail it.
+
+### Fixed
+
+- Top-level `db: false` opts out of per-worktree databases (exotic
+  setups: manual `establish_connection`, shared staging DB, …). Validated
+  as boolean-or-mapping; `x-` extensions still ignored. `db.schema_load`
+  moves to top-level `db` (per-process ghost `db` entry was a category
+  error). Credentials-stored `DATABASE_URL`s now work when the template is
+  declared in `env.clear` (password via `local.secrets`); when no template
+  exists but the app looks database-backed (`database.yml` adapter or
+  `pg`/`mysql2`/`trilogy` in `Gemfile`) boot warns loudly with the fix
+  instead of silently sharing one database. Framework-agnostic: injection
+  is still `DATABASE_URL`, no `ask-auth` dep, no Rails load at boot.
+
 ## [0.5.0] — Unreleased
 
 Per-worktree databases: every worktree directory gets its own database

data/README.md

@@ -91,6 +91,12 @@ processes:
     proxy: false
 ```
 
+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).
+
 `yamine init` creates the file (migrating an existing Procfile);
 Rails apps need no extra gem — yamine injects `RAILS_DEVELOPMENT_HOSTS`
 so the proxied hostname is allowed automatically. `yamine`
@@ -133,19 +139,21 @@ yamine --tld preview.example.com                # your own domain (OAuth parity)
 ## Commands
 
 ```bash
-yamine                        # infer name, boot app
+yamine                        # boot app (waits until healthy, then supervises)
+yamine start --no-wait        # fire-and-forget (register routes immediately)
+yamine start --json           # machine-readable wait result (--wait default)
 yamine run -- <cmd>           # run explicit command through proxy
-yamine <name> <cmd>           # explicit app name
 yamine get <name>             # print URL for cross-service wiring
 yamine alias <name> <port>    # static route (e.g. Docker)
 yamine list [--json]          # show active routes (+ backend liveness)
 yamine status [--json]        # show effective naming context here
 yamine doctor [--json]        # machine-readable health checks
 yamine open [name]            # open the app URL in a browser
-yamine doctor                 # read-only health check (state, proxy, routes, DNS, CA)
 yamine trust                  # add local CA to system 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 stop                   # stop this app's backend + routes
 yamine restart                # touch tmp/restart.txt (managed apps reboot)
 yamine log [-f] [n]           # tail (or follow) this app's backend log
@@ -186,12 +194,18 @@ connection (verified end-to-end: RFC 6455 handshake + frame echo).
 
 ## Machine-readable output
 
-`list`, `status`, and `doctor` accept `--json` with stable keys for
+`list`, `status`, `doctor`, and `yamine start --wait` accept `--json` with stable keys for
 agents and scripts (`DevUrl` in ask-ruby-harness consumes the same data
 in-process). Hostnames that fall outside the configured TLDs get a bare
 404 naming nothing — route names never leak to foreign hosts
 (DNS-rebinding boundary).
 
+`yamine start` (default `--wait`) exits 0 only once every HTTP route is healthy
+(healthcheck path when declared, TCP accept otherwise). On failure it
+exits 1 with the failed process, its phase, and the tail of its own log
+— no guessing, no polling, no half-booted routes. `--no-wait` keeps the
+old fire-and-forget path.
+
 ## Log rotation
 
 `proxy.log` and per-app backend logs rotate at 5MB

data/lib/ask/skills/yamine/SKILL.md

@@ -33,11 +33,13 @@ no extra gem — the proxied hostname is allowed automatically via
 `RAILS_DEVELOPMENT_HOSTS`.
 
 ```bash
-yamine start          # setup if needed, then boot every process
-yamine                # same as start
-yamine stop           # stop this app's backend + routes
-yamine status         # show service, processes, and URLs
-yamine log [-f]       # tail the web process log
+yamine start              # setup if needed, then boot every process (waits until healthy)
+yamine start --no-wait   # fire-and-forget (register routes immediately)
+yamine start --json       # machine-readable wait result (--wait default)
+yamine                    # same as start
+yamine stop               # stop this app's backend + routes
+yamine status             # show service, processes, and URLs
+yamine log [-f]           # tail the web process log
 ```
 
 `$PORT` and `YAMINE_URL` are injected per process; HTTP processes get
@@ -96,6 +98,7 @@ proxy:
 yamine doctor                 # read-only: proxy, routes, DNS, CA trust
 yamine list --json            # routes as stable JSON
 yamine prune                  # clear stale routes from crashed sessions
+yamine start --json           # boot readiness payload (pass/fail + log tail)
 ```
 
 If a hostname does not resolve: `yamine hosts sync`. If the browser

data/lib/yamine/cli/boot.rb

@@ -16,7 +16,7 @@ module Yamine
       # boots every process, supervises the tree, cleans up on exit.
       def run_inferred(ctx, args)
         variant = ENV["YAMINE_VARIANT"]
-        opts = ctx.parse_flags(args, %i[variant tld force])
+        opts = ctx.parse_flags(args, %i[variant tld force app_port wait no_wait json])
         resolved = resolve!(ctx, variant: opts[:variant] || variant, tld: opts[:tld])
         # Ownership gate before any side effects: no proxy spawn, no
         # port allocation when we'd refuse anyway.
@@ -43,6 +43,7 @@ module Yamine
         tld = resolved.tld
         host = resolved.host
         processes = resolved.processes
+        events = opts[:events]
 
         if processes.empty?
           $stderr.puts "Error: no processes in config/local.yml. Add at least one."
@@ -55,6 +56,20 @@ module Yamine
           exit 1
         end
 
+        # 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
+          ok, fix = Readiness.check_deps(Dir.pwd)
+          raise fix unless ok
+
+          "dependencies satisfied"
+        end
+        unless deps.status == "ok"
+          $stderr.puts "Error: #{deps.detail}"
+          exit 1
+        end
+
         runner = Runner.new(store: ctx.store)
         children = []
         routes_registered = []
@@ -70,59 +85,169 @@ module Yamine
         # branches hop).
         db_name = Database.name_for(Dir.pwd, env: rails_env,
           state_dir: ctx.store.dir)
-        db_url = setup_database(ctx, resolved, db_name)
-        puts "  [db] #{db_name}" if db_url
+        db_created, db_url = setup_database(ctx, resolved, db_name, events: events)
+        puts "  [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)
+        else
+          boot_sequential(ctx, runner, resolved, opts, spawn_plan, children,
+            routes_registered, db_url, events: events)
+        end
+
+        background = processes.select { |_, v| v["proxy"] == false }
+        unless background.empty?
+          puts "  [background] #{background.keys.join(', ')}"
+        end
+
+        puts
+        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] }
+        all_hostnames = routes_registered.flat_map { |r| r[:hostnames] }
+        trap_cleanup(ctx, all_hostnames, all_pids)
+        supervise_tree(ctx, all_hostnames, all_pids)
+      end
 
+      # One pass over config: background processes spawn immediately
+      # (no route to wait on), HTTP processes become a spawn plan the
+      # boot mode executes. Compound-line refusal happens here so both
+      # paths share one rule.
+      def collect_spawns(ctx, runner, resolved, opts, db_url, children)
+        plan = []
+        processes = resolved.processes
         processes.each do |proc_name, entry|
           hostname = Resolver.hostname_for(resolved, proc_name)
           if entry["proxy"] == false
-            boot_background(ctx, runner, resolved, proc_name, entry, opts, children, db_url)
+            boot_background(ctx, runner, resolved, proc_name, entry, opts,
+              children, db_url)
             next
           end
           next unless hostname
 
           url = Hostname.url(hostname, port: ctx.proxy_port, tls: ctx.proxy_tls)
-          hostnames = [hostname]
-          puts "  [#{proc_name}] #{url}"
-
-          # Each process cmd runs through the shell so $PORT (and other
-          # env refs) expand — same trust boundary as a Procfile line
-          # (repo code, not user input). Compound lines are refused.
           cmd = entry["cmd"].to_s
           if cmd.match?(Yamine::Procfile::COMPOUND)
             $stderr.puts "  [#{proc_name}] ERROR: compound line (&&, ||, |, ;) — run explicitly: yamine run -- #{cmd}"
             next
           end
-
           port = opts[:app_port] || Ports.find_free
-          shell_cmd = ["sh", "-c", cmd]
+          plan << { name: proc_name, entry: entry, hostname: hostname,
+            hostnames: [hostname], url: url, port: port,
+            command: ["sh", "-c", cmd] }
+        end
+        plan
+      end
+
+      # Default: sequential boot, route registered per process as before.
+      def boot_sequential(ctx, runner, resolved, opts, plan, children,
+        routes_registered, db_url, events: nil)
+        plan.each do |item|
+          puts "  [#{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
           # frameworks that honor it get isolation for free, others ignore it.
-          app = runner.boot_run(name: proc_name, hostname: hostname, url: url,
-            dir: Dir.pwd, command: shell_cmd, port: port, force: opts[:force],
-            rails_dev_host: hostname, database_url: db_url)
-          register_all(ctx, hostnames, app, force: opts[:force],
-            spec: { "dir" => File.expand_path(Dir.pwd), "proc" => proc_name })
-          routes_registered << { hostnames: hostnames, app: app }
-
-          puts "  -> #{url}"
+          # boot_run registers the route + backend sidecar itself
+          # (register: true default); no separate adopt step needed.
+          app = runner.boot_run(name: item[:name], hostname: item[:hostname],
+            url: item[:url], dir: Dir.pwd, command: item[:command],
+            port: item[:port], force: opts[:force],
+            rails_dev_host: item[:hostname], database_url: db_url)
+          routes_registered << { hostnames: item[:hostnames], app: app }
+
+          puts "  -> #{item[:url]}"
         end
+        children
+      end
 
-        background = processes.select { |_, v| v["proxy"] == false }
-        unless background.empty?
-          puts "  [background] #{background.keys.join(', ')}"
+      # --wait: spawn everything first, then poll every port/path until
+      # healthy. No route exists until its backend answers, so half-boots
+      # 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)
+        apps = {}
+        plan.each do |item|
+          puts "  [#{item[:name]}] #{item[:url]}"
+          apps[item[:name]] = {
+            item: item,
+            app: runner.spawn_http(name: item[:name], hostname: item[:hostname],
+              url: item[:url], dir: Dir.pwd, command: item[:command],
+              port: item[:port], rails_dev_host: item[:hostname],
+              database_url: db_url, force: opts[:force])
+          }
+        end
+        wait_result = Readiness.wait_all(apps, tls: ctx.proxy_tls, out: nil)
+        failed = wait_result.select { |r| r[:status] != "ok" }
+
+        if failed.empty?
+          apps.each do |name, slot|
+            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]}"
+          end
         end
+        finish_wait(ctx, resolved, apps, wait_result, failed, routes_registered,
+          children, db_name, db_url, db_created, json: opts[:json])
+      end
 
-        puts
-        ctx.report_unresolved(routes_registered.flat_map { |r| r[:hostnames] })
+      # --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.
+      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] }
+        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
+          return
+        end
 
-        # Supervisor: exit when ANY child dies (loud cleanup).
-        all_pids = routes_registered.map { |r| r[:app].pid } + children.map { |c| c[:pid] }
-        all_hostnames = routes_registered.flat_map { |r| r[:hostnames] }
-        trap_cleanup(ctx, all_hostnames, all_pids)
-        supervise_tree(ctx, all_hostnames, all_pids)
+        apps.each_value { |slot| stop_spawned(slot[:app]) }
+        children.each { |c| stop_spawned_pid(c[:pid]) }
+        first = failed.first
+        payload = Yamine::WaitPayload.failure(resolved, wait_result, failed: first,
+          log_tail: tail_for(failed.first, apps))
+        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
+        cleanup_routes(ctx, apps.values.map { |slot| slot[:item][:hostname] })
+        exit 1
+      end
+
+      def tail_for(failure, apps)
+        name = failure[:name]
+        slot = apps[name]
+        path = slot ? File.expand_path(File.join(Dir.pwd, "log", "yamine-#{name}.log")) : nil
+        lines = path && File.file?(path) ? File.readlines(path).last(20).join : "(no log file)"
+        { path: path, tail: lines }
+      rescue SystemCallError
+        { path: path, tail: "(unreadable log)" }
+      end
+
+      def stop_spawned(app)
+        stop_spawned_pid(app.pid)
+      end
+
+      def stop_spawned_pid(pid)
+        Process.kill("TERM", pid)
+      rescue SystemCallError
+        nil
       end
 
       # A background process (proxy: false) is spawned, logged, and
@@ -187,51 +312,125 @@ module Yamine
       end
 
       # Resolve this worktree's database, create it if missing, and run
-      # the app's schema-load command on first creation. Returns the
-      # DATABASE_URL for injection, or nil when there's nothing to do
-      # (no template URL, sqlite, or the app opted out via db: false).
-      def setup_database(ctx, resolved, db_name)
-        return nil if resolved.processes["db"] == false
+      # the app's schema-load command on first creation. Returns
+      # [created, url]: created is true only when this boot created the
+      # database (so --wait can report provenance without a second
+      # probe), url is nil when there is nothing to inject.
+      #
+      # Template sources: ENV DATABASE_URL, then config env.clear
+      # DATABASE_URL (top-level env, falling back to per-process env
+      # for configs written before top-level env existed). Injected
+      # DATABASE_URL overrides database.yml/credentials at connection
+      # time (ActiveRecord merges env over file config), so credentials
+      # apps work — they just need the template declared in config.
+      def setup_database(ctx, resolved, db_name, events: nil)
+        return [false, nil] if db_opted_out?(resolved)
 
         template = ENV["DATABASE_URL"] || database_template_from_config(resolved)
-        return nil if template.nil? || template.strip.empty?
+        if template.nil? || template.strip.empty?
+          warn_missing_template(resolved)
+          return [false, nil]
+        end
 
         url = Database.url_for(db_name, template)
-        return nil unless url
+        return [false, nil] unless url
+
+        db_event = Readiness.phase(:db, "ensure #{db_name}", out: events) do
+          existed = Database.exists?(db_name, template)
+          raise "database server unreachable — is postgres/mysql running?" unless Database.ensure_exists(db_name, template)
+
+          existed ? "already exists" : "created #{db_name}"
+        end
+        unless db_event.status == "ok"
+          $stderr.puts "  [db] WARNING: #{db_event.detail} — processes share the template database."
+          return [false, nil]
+        end
+        created = db_event.detail.to_s.start_with?("created")
+
+        schema_event = Readiness.phase(:schema, "load #{db_name}", out: events) do
+          next "skipped (already exists)" unless created
 
-        if Database.ensure_exists(db_name, template)
-          puts "  [db] created #{db_name}" unless database_exists?(db_name, template)
           run_schema_load(resolved, url)
-        else
-          $stderr.puts "  [db] WARNING: could not create #{db_name} — processes share the template database."
-          return nil
         end
-        url
+        unless schema_event.status == "ok"
+          $stderr.puts "  [db] WARNING: schema load #{schema_event.status}: #{schema_event.detail}."
+        end
+        [created, url]
       end
 
-      def database_exists?(name, template)
-        # ensure_exists is idempotent; this second call is cheap (psql -lqt)
-        # and tells us whether to print "created" vs nothing.
-        Database.ensure_exists(name, template)
+      # Top-level `db: false` opts out of per-worktree databases.
+      # (A `db` process entry still boots as a process — only the
+      # explicit top-level key opts out.)
+      def db_opted_out?(resolved)
+        resolved.db == false
+      end
+
+      # The dangerous case made loud: the app looks database-backed
+      # (server adapter in database.yml, or pg/mysql2 in the Gemfile)
+      # but no template was declared, so every worktree would silently
+      # share one database. Name the fix; do not guess.
+      def warn_missing_template(resolved)
+        return unless database_backed?
+
+        $stderr.puts "  [db] WARNING: app looks database-backed but no DATABASE_URL template found."
+        $stderr.puts "    Each worktree would share one database. Declare the template in config/local.yml:"
+        $stderr.puts "      env:"
+        $stderr.puts "        clear:"
+        $stderr.puts "          DATABASE_URL: postgres://user@localhost:5432/myapp_development"
+        $stderr.puts "    (password via config/local.secrets + env.secret), or opt out with top-level `db: false`."
+      end
+
+      # Heuristics, deliberately conservative: only warn when there is
+      # positive evidence of a server database. SQLite-only and
+      # database-less apps stay silent.
+      def database_backed?
+        database_yml_server? || gemfile_server_adapter?
+      end
+
+      def database_yml_server?(path = File.join(Dir.pwd, "config", "database.yml"))
+        return false unless File.file?(path)
+
+        content = File.read(path)
+        content.match?(/adapter:\s*(postgresql|postgres|postgis|mysql2?|trilogy)/i)
+      rescue SystemCallError
+        false
+      end
+
+      def gemfile_server_adapter?(path = File.join(Dir.pwd, "Gemfile"))
+        return false unless File.file?(path)
+
+        content = File.read(path)
+        content.match?(/gem\s+["'](pg|mysql2|trilogy)["']/)
+      rescue SystemCallError
+        false
       end
 
       def database_template_from_config(resolved)
+        top = resolved.env.is_a?(Hash) ? resolved.env["clear"] : nil
+        from_top = top.is_a?(Hash) ? top["DATABASE_URL"] : nil
+        return from_top if from_top && !from_top.to_s.strip.empty?
+
         env = resolved.processes.values.map { |e| e["env"] || {} }
         clear = env.map { |e| e["clear"] || {} }.reduce({}, :merge)
         clear["DATABASE_URL"]
       end
 
       # Schema-load on first boot uses the app's own command when declared
-      # (db.schema_load in config/local.yml), else a Rails default when a
-      # Rails app is detected, else nothing (frameworks without a
-      # schema concept need no step).
+      # (top-level db.schema_load in config/local.yml), else a Rails
+      # default when a Rails app is detected, else nothing (frameworks
+      # without a schema concept need no step). Returns a detail string.
       def run_schema_load(resolved, url)
-        cmd = resolved.processes.dig("db", "schema_load") ||
+        cmd = db_schema_load(resolved) ||
           ("bin/rails db:schema:load" if rails_app?)
-        return unless cmd
+        return "no schema-load command" unless cmd
 
-        system({ "DATABASE_URL" => url, "RAILS_ENV" => rails_env },
+        ok = system({ "DATABASE_URL" => url, "RAILS_ENV" => rails_env },
           "sh", "-c", cmd, chdir: Dir.pwd, out: File::NULL, err: File::NULL)
+        ok ? "loaded schema via #{cmd}" : raise("schema-load exited non-zero: #{cmd}")
+      end
+
+      def db_schema_load(resolved)
+        resolved.db.is_a?(Hash) ? resolved.db["schema_load"] : nil
       end
 
       def rails_app?
@@ -290,21 +489,6 @@ module Yamine
         end
       end
 
-      def register_all(ctx, hostnames, app, force:, spec: nil)
-        hostnames[1..].each do |h|
-          ctx.store.add_route(h, app.target, Process.pid, kind: app.kind,
-            force: force, spec: spec)
-          write_backend_sidecar(ctx, h, app.pid)
-        end
-      end
-
-      def write_backend_sidecar(ctx, hostname, pid)
-        ctx.store.ensure_dir
-        File.write(File.join(ctx.store.dir, "backend-#{hostname}.pid"), "#{pid}\n")
-      rescue SystemCallError
-        nil
-      end
-
       def cleanup_routes(ctx, hostnames)
         hostnames.each do |h|
           begin

data/lib/yamine/cli/context.rb

@@ -81,7 +81,7 @@ module Yamine
           elsif arg.start_with?("--")
             key = arg.sub(/\A--/, "").tr("-", "_").to_sym
             if known.include?(key)
-              if %i[branch force].include?(key)
+              if %i[branch force wait no_wait json].include?(key)
                 opts[key] = true
                 i += 1
               else

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.

data/lib/yamine/cli.rb

@@ -94,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

@@ -136,6 +136,16 @@ module Yamine
       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)
@@ -149,13 +159,7 @@ module Yamine
     def ensure_postgres(name, database_url)
       uri = URI.parse(database_url)
       env = pg_env(uri)
-      _out, status = Open3.capture2(env, "psql", "-lqt")
-      return false unless status.success?
-
-      exists = Open3.capture2(env, "psql", "-lqt")[0].split("\n").any? do |line|
-        line.split("|").first.to_s.strip == name
-      end
-      return true if exists
+      return true if pg_exists?(name, database_url)
 
       _out, status = Open3.capture2(env, "createdb", name)
       status.success?
@@ -163,24 +167,43 @@ module Yamine
       false
     end
 
-    def ensure_mysql(name, database_url)
+    def pg_exists?(name, database_url)
       uri = URI.parse(database_url)
-      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
-      _out, status = Open3.capture2("mysqladmin", *args, "create", name)
-      status.success? || already_exists_mysql(args, name)
+      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 already_exists_mysql(args, name)
+    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",

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

data/lib/yamine/resolver.rb

@@ -9,7 +9,7 @@ module Yamine
     module_function
 
     Result = Struct.new(:app, :tld, :host, :processes, :secrets,
-      :sources, :variant, keyword_init: true)
+      :sources, :variant, :db, :env, keyword_init: true)
 
     def resolve(dir = Dir.pwd, variant: nil, tld: nil, host: nil)
       config = Config.load(dir, variant: variant)
@@ -51,7 +51,9 @@ module Yamine
         processes: processes,
         secrets: config.secrets,
         sources: sources,
-        variant: variant_name
+        variant: variant_name,
+        db: config.data["db"],
+        env: config.env_config
       )
     end
 

data/lib/yamine/runner.rb

@@ -91,22 +91,59 @@ module Yamine
 
     # Run an arbitrary command with PORT + YAMINE_URL. Returns App.
     # register: false spawns without a route (background processes).
+    # Child output goes to log/yamine-<name>.log so `--wait` failure
+    # payloads can tail it (same file the managed path uses).
     def boot_run(name:, hostname:, url:, dir:, command:, port: nil, force: false,
-      rails_dev_host: nil, register: true, database_url: nil)
+      rails_dev_host: nil, register: true, database_url: nil, spec: nil)
       port ||= Ports.find_free
       env = child_env(dir, url: url, port: port, rails_dev_host: rails_dev_host,
         database_url: database_url)
-      pid = with_clean_env { spawn(env, *command, chdir: dir) }
+      path = log_path(dir, name)
+      pid = with_clean_env { spawn(env, *command, chdir: dir, out: path, err: [:child, :out]) }
       Process.detach(pid)
       target = "127.0.0.1:#{port}"
       if register
-        @store.add_route(hostname, target, Process.pid, kind: "tcp", force: force)
+        spec ||= { "dir" => File.expand_path(dir), "proc" => name }
+        @store.add_route(hostname, target, Process.pid, kind: "tcp",
+          force: force, spec: spec)
         write_backend_pid(hostname, pid)
       end
       App.new(name: name, hostname: hostname, url: url, pid: pid,
         target: target, kind: "tcp", command: command)
     end
 
+    # Spawn without registering or waiting: the --wait path spins the
+    # whole tree up concurrently, then polls every route until healthy.
+    # Returns the placeholder App (target known before bind). Fate of
+    # the backend is decided by wait, not by spawn.
+    def spawn_http(name:, hostname:, url:, dir:, command:, port:, rails_dev_host: nil,
+      database_url: nil, force: false)
+      env = child_env(dir, url: url, port: port, rails_dev_host: rails_dev_host,
+        database_url: database_url)
+      path = log_path(dir, name)
+      pid = with_clean_env { spawn(env, *command, chdir: dir, out: path, err: [:child, :out]) }
+      Process.detach(pid)
+      App.new(name: name, hostname: hostname, url: url, pid: pid,
+        target: "127.0.0.1:#{port}", kind: "tcp", command: command)
+    end
+
+    # Register an already-spawned backend: route + sidecar, together.
+    def adopt(hostname, app, force: false, spec: nil)
+      @store.add_route(hostname, app.target, Process.pid, kind: app.kind,
+        force: force, spec: spec)
+      write_backend_pid(hostname, app.pid)
+      nil
+    end
+
+    # Still running? A port that accepts is not proof of life, but a
+    # reaped/dead pid is proof of death — that is all wait needs.
+    def spawned?(pid)
+      Process.kill(0, pid)
+      true
+    rescue SystemCallError
+      false
+    end
+
     def child_env(dir, url:, port:, rails_dev_host: nil, database_url: nil)
       env = { "YAMINE_URL" => url }
       env["PORT"] = port.to_s if port
@@ -217,6 +254,8 @@ module Yamine
       end
     end
 
+    # Log path for a process — public so the --wait failure payload
+    # can tail the right file for the phase that failed.
     def log_path(dir, name)
       path = File.expand_path(File.join(dir, "log", "yamine-#{name}.log"))
       FileUtils.mkdir_p(File.dirname(path))
@@ -234,6 +273,8 @@ module Yamine
       nil
     end
 
+    # Last lines of a log file for failure payloads. Public so the
+    # --wait path can attribute the right tail to the failed phase.
     def log_tail(path, lines: 10)
       return "(no log file)" unless File.file?(path)
 
@@ -242,6 +283,8 @@ module Yamine
       "(unreadable log)"
     end
 
+    private
+
     def stop_pid(pid)
       Process.kill("TERM", pid)
     rescue SystemCallError

data/lib/yamine/version.rb

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

data/lib/yamine.rb

@@ -21,6 +21,7 @@ require_relative "yamine/proxy"
 require_relative "yamine/proxy_control"
 require_relative "yamine/supervisor"
 require_relative "yamine/runner"
+require_relative "yamine/readiness"
 require_relative "yamine/resolver"
 require_relative "yamine/trust"
 require_relative "yamine/doctor"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: yamine
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Kaka Ruto
@@ -104,6 +104,7 @@ files:
 - lib/yamine/procfile.rb
 - lib/yamine/proxy.rb
 - lib/yamine/proxy_control.rb
+- lib/yamine/readiness.rb
 - lib/yamine/resolver.rb
 - lib/yamine/route_store.rb
 - lib/yamine/runner.rb