yamine 0.3.0

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

@@ -0,0 +1,113 @@
+---
+name: yamine
+description: Run Ruby apps through yamine for stable named .localhost URLs (e.g. https://myapp.localhost instead of http://localhost:3000). Use when booting dev servers (Rails, Rack, Roda, Sinatra, Jekyll), wiring frontend to API, configuring OAuth callbacks or webhooks, debugging port conflicts, or working in git worktrees.
+---
+
+# Local Dev with yamine
+
+Never invent ports. Never parse them from logs. Every app has a stable URL.
+
+## One file, one command
+
+Every app declares `config/local.yml` — the single source of truth:
+
+```yaml
+service: myapp
+proxy:
+  tld: localhost
+processes:
+  web:
+    cmd: bundle exec puma -b tcp://127.0.0.1:$PORT config.ru
+    proxy: true          # gets https://myapp.localhost
+  worker:
+    cmd: bundle exec sidekiq
+    proxy: false         # background, supervised, no URL
+env:
+  clear:
+    RAILS_ENV: development
+```
+
+If the file is missing, yamine prints `Run yamine init`. Generate it
+with `yamine init` (migrates an existing Procfile). Rails apps need
+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
+```
+
+`$PORT` and `YAMINE_URL` are injected per process; HTTP processes get
+stable URLs, background ones are supervised without routes. A process
+that exits cleans up the whole tree.
+
+## Cross-service wiring
+
+```bash
+yamine get backend            # -> https://backend.localhost
+yamine get backend --variant demo
+```
+
+Use `get` output for frontend-to-API URLs, Cable URLs, and webhook
+targets. Do not guess ports.
+
+## Variants are files
+
+A variant is a file overlay, Kamal-style: `config/local.<variant>.yml`
+deep-merges over `config/local.yml`. Select it with `YAMINE_VARIANT`
+or `--variant`. Worktrees get a branch prefix automatically.
+
+```bash
+YAMINE_VARIANT=fix-ui yamine    # boots with config/local.fix-ui.yml merged
+```
+
+## First time on a machine
+
+Run `yamine start` — it does the one-shot CA trust, port 443, and
+hosts sync if anything is missing, then boots. Prefer `yamine setup`
+for workstation setup without booting. If any command fails with a
+privileged-port error, do not work around it with `-p` — run
+`yamine setup` instead. A `:port` suffix in a URL means someone
+explicitly opted into it.
+
+## OAuth and webhooks
+
+Build callback URLs from `YAMINE_URL` (injected into every HTTP
+process):
+
+```ruby
+callback = "#{Yamine::Rails.url}/auth/google/callback"
+```
+
+Strict providers (Google, Apple) reject `.localhost`. Serve the app on a
+domain you own instead — no code change, just config:
+
+```yaml
+proxy:
+  host: myapp.local.example.com   # instead of tld: localhost
+```
+
+## Troubleshooting
+
+```bash
+yamine doctor                 # read-only: proxy, routes, DNS, CA trust
+yamine list --json            # routes as stable JSON
+yamine prune                  # clear stale routes from crashed sessions
+```
+
+If a hostname does not resolve: `yamine hosts sync`. If the browser
+warns about TLS: `yamine trust`.
+
+## When NOT to use yamine
+
+- **CI pipelines**: no TTY, no sudo, no browsers. Run the app's own test
+  command directly; yamine fails fast here by design.
+- **Production consoles and servers**: the proxy binds loopback only and
+  the CA is self-signed. Use Kamal + kamal-proxy for anything real.
+- **Docker-internal networking**: containers reach each other by service
+  name on the compose network, not via the host's `.localhost`.
+- **Debugging the proxy itself**: use `yamine proxy start --foreground`
+  and read the log; do not layer another yamine on top.

data/lib/yamine/certs.rb

@@ -0,0 +1,177 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "openssl"
+
+module Yamine
+  # Local CA + per-hostname certificates, all in-process via OpenSSL.
+  #
+  # *.localhost sits at a public-suffix boundary so a wildcard cert is
+  # not honored; every hostname gets an exact-SAN cert minted on demand
+  # through the SNI callback and held in an in-memory LRU
+  # (puma-dev ssl.go does the same; portless caches on disk instead).
+  module Certs
+    CA_COMMON_NAME = "Ask Local CA"
+    CA_VALIDITY_DAYS = 3650
+    HOST_VALIDITY_DAYS = 825
+    CACHE_SIZE = 1024
+
+    module_function
+
+    def state_dir
+      ENV["YAMINE_STATE_DIR"] || File.join(home, ".yamine")
+    end
+
+    def home
+      ENV["HOME"] || Dir.home
+    rescue ArgumentError
+      Dir.pwd
+    end
+
+    def ca_paths(dir = state_dir)
+      { cert: File.join(dir, "ca.pem"), key: File.join(dir, "ca-key.pem") }
+    end
+
+    def ensure_ca(dir = state_dir)
+      FileUtils.mkdir_p(dir, mode: 0o755)
+      Ownership.fix(dir)
+      paths = ca_paths(dir)
+      return paths if valid_pair?(paths[:cert], paths[:key])
+
+      key = OpenSSL::PKey::EC.generate("prime256v1")
+      cert = OpenSSL::X509::Certificate.new
+      cert.version = 2
+      cert.serial = OpenSSL::BN.rand(128, 0)
+      cert.subject = cert.issuer = OpenSSL::X509::Name.parse("/CN=#{CA_COMMON_NAME}")
+      cert.not_before = Time.now - 3600
+      cert.not_after = Time.now + (CA_VALIDITY_DAYS * 86_400)
+      cert.public_key = key
+      ef = OpenSSL::X509::ExtensionFactory.new
+      ef.subject_certificate = cert
+      ef.issuer_certificate = cert
+      cert.add_extension(ef.create_extension("basicConstraints", "CA:TRUE", true))
+      cert.add_extension(ef.create_extension("keyUsage", "keyCertSign,cRLSign", true))
+      cert.sign(key, "SHA256")
+
+      File.write(paths[:key], key.to_pem, mode: "w", perm: 0o600)
+      File.write(paths[:cert], cert.to_pem, mode: "w", perm: 0o644)
+      Ownership.fix(paths[:key], paths[:cert])
+      paths
+    rescue OpenSSL::OpenSSLError => e
+      raise CertError, "Could not generate local CA: #{e.message}"
+    end
+
+    def load_ca(dir = state_dir)
+      paths = ensure_ca(dir)
+      [OpenSSL::X509::Certificate.new(File.read(paths[:cert])),
+       OpenSSL::PKey.read(File.read(paths[:key]))]
+    end
+
+    # Mint a leaf cert for one hostname, signed by the CA.
+    def mint_host(hostname, ca_cert, ca_key)
+      key = OpenSSL::PKey::EC.generate("prime256v1")
+      cert = OpenSSL::X509::Certificate.new
+      cert.version = 2
+      cert.serial = OpenSSL::BN.rand(128, 0)
+      cert.subject = OpenSSL::X509::Name.parse("/CN=#{hostname[0, 64]}")
+      cert.issuer = ca_cert.subject
+      cert.not_before = Time.now - 3600
+      cert.not_after = Time.now + (HOST_VALIDITY_DAYS * 86_400)
+      cert.public_key = key
+      ef = OpenSSL::X509::ExtensionFactory.new
+      ef.subject_certificate = cert
+      ef.issuer_certificate = ca_cert
+      cert.add_extension(ef.create_extension("basicConstraints", "CA:FALSE", true))
+      cert.add_extension(ef.create_extension("keyUsage", "digitalSignature,keyEncipherment", true))
+      cert.add_extension(ef.create_extension("extendedKeyUsage", "serverAuth"))
+      cert.add_extension(ef.create_extension("subjectAltName", "DNS:#{hostname}"))
+      cert.sign(ca_key, "SHA256")
+      [cert, key]
+    end
+
+    # Build an SSLContext whose SNI callback serves the right cert per host.
+    def server_context(dir = state_dir)
+      ca_cert, ca_key = load_ca(dir)
+      cache = CertCache.new(CACHE_SIZE)
+      ctx = OpenSSL::SSL::SSLContext.new
+      ctx.cert = ca_cert
+      ctx.key = ca_key
+      # ruby-openssl versions differ in how the callback receives its
+      # arguments: [[socket, name]] (one array arg), (socket, name), or
+      # (name). Flatten defensively — a raise inside the callback
+      # surfaces as an unrecognized-name handshake alert.
+      ctx.servername_cb = lambda do |*args|
+        host = Array(args).flatten.last.to_s.downcase
+        entry = cache.fetch(host) do
+          cert, key = mint_host(host, ca_cert, ca_key)
+          [cert, key]
+        end
+        entry ? OpenSSL::SSL::SSLContext.new.tap { |c| c.cert, c.key = entry } : nil
+      end
+      ctx
+    end
+
+    def trusted?(dir = state_dir)
+      paths = ca_paths(dir)
+      return false unless File.file?(paths[:cert])
+
+      marker = File.join(dir, "ca.trusted")
+      return false unless File.file?(marker)
+
+      Digest::SHA256.hexdigest(File.read(paths[:cert])).then do |fp|
+        File.read(marker).strip == fp
+      end
+    rescue SystemCallError
+      false
+    end
+
+    def mark_trusted(dir = state_dir)
+      require "digest"
+      paths = ca_paths(dir)
+      fp = Digest::SHA256.hexdigest(File.read(paths[:cert]))
+      File.write(File.join(dir, "ca.trusted"), "#{fp}\n")
+    end
+
+    def valid_pair?(cert_path, key_path)
+      return false unless File.file?(cert_path) && File.file?(key_path)
+
+      cert = OpenSSL::X509::Certificate.new(File.read(cert_path))
+      cert.not_after > Time.now + (7 * 86_400) &&
+        cert.subject.to_s.include?(CA_COMMON_NAME)
+    rescue OpenSSL::OpenSSLError, SystemCallError, ArgumentError
+      false
+    end
+
+    # In-memory LRU for minted host certs.
+    class CertCache
+      def initialize(max)
+        @max = max
+        @store = {}
+        @order = []
+        @mutex = Mutex.new
+      end
+
+      def fetch(host)
+        @mutex.synchronize do
+          if @store.key?(host)
+            @order.delete(host)
+            @order << host
+            return @store[host]
+          end
+          value = yield
+          @store[host] = value
+          @order << host
+          if @order.length > @max
+            oldest = @order.shift
+            @store.delete(oldest)
+          end
+          value
+        end
+      end
+
+      def size
+        @mutex.synchronize { @store.size }
+      end
+    end
+  end
+end

data/lib/yamine/cli/boot.rb

@@ -0,0 +1,247 @@
+# frozen_string_literal: true
+
+module Yamine
+  class CLI
+    # Boot commands: `yamine`, `yamine start`, `yamine run`.
+    # The config file is mandatory — missing file prints the fix and exits.
+    # `boot_all` fans out over every process declared in config/local.yml.
+    # No inference, no Procfile at boot, no single-process default.
+    module BootCommand
+      PORT_IGNORING = %w[jekyll middleman bridgetown].freeze
+
+      module_function
+
+      # Bare `yamine` / `yamine start` / `yamine run`.
+      # Reads config/local.yml via the resolver, ensures the proxy,
+      # 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])
+        resolved = resolve!(ctx, variant: opts[:variant] || variant, tld: opts[:tld])
+        ensure_proxy!(ctx)
+        boot_all(ctx, resolved, opts)
+      end
+
+      def run_explicit(ctx, args)
+        run_inferred(ctx, args)
+      end
+
+      def run_named(ctx, name, _args)
+        $stderr.puts "Error: `yamine #{name}` is no longer supported."
+        $stderr.puts "  All processes come from config/local.yml. Run `yamine init` to create one."
+        exit 1
+      end
+
+      # Core boot loop: iterate processes from config/local.yml,
+      # classify HTTP vs background, spawn each, register routes for
+      # HTTP processes, then supervise the tree.
+      def boot_all(ctx, resolved, opts)
+        service = resolved.app
+        tld = resolved.tld
+        host = resolved.host
+        processes = resolved.processes
+
+        if processes.empty?
+          $stderr.puts "Error: no processes in config/local.yml. Add at least one."
+          exit 1
+        end
+
+        primary = Resolver.primary_proc(resolved)
+        if primary.nil?
+          $stderr.puts "Error: no HTTP process (proxy: true) found in config/local.yml."
+          exit 1
+        end
+
+        runner = Runner.new(store: ctx.store)
+        children = []
+        routes_registered = []
+
+        puts "yamine (#{service})"
+        puts "--"
+
+        processes.each do |proc_name, entry|
+          next if entry["proxy"] == false
+
+          hostname = Resolver.hostname_for(resolved, proc_name)
+          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]
+          # Always allow the proxied hostname in Rails dev (Rails ignores
+          # this env var when not a Rails app — safe for every framework).
+          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)
+          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}"
+        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 }
+        trap_cleanup(ctx, routes_registered.flat_map { |r| r[:hostnames] }, all_pids)
+        supervise_tree(ctx, routes_registered.flat_map { |r| r[:hostnames] }, all_pids)
+      end
+
+      def build_env(ctx, resolved, entry)
+        env = {}
+        # Merge config env.clear
+        config_env = resolved.secrets || {}
+        entry_env = entry["env"] || {}
+        (entry_env["clear"] || {}).each { |k, v| env[k] = v }
+        # Merge secrets from config/local.secrets
+        secret_keys = entry_env["secret"] || []
+        secret_keys.each do |k|
+          env[k] = config_env[k] if config_env.key?(k)
+        end
+        # Host env (dotenv from .env) already in ENV
+        env
+      end
+
+      def supervise_tree(ctx, hostnames, pids)
+        loop do
+          sleep 0.5
+          if pids.any? { |pid| !ProxyControl.pid_alive?(pid) }
+            puts "\nA process exited — cleaning up all routes."
+            cleanup_routes(ctx, hostnames)
+            # Kill remaining children
+            pids.each do |pid|
+              Process.kill("TERM", pid) rescue nil
+            end
+            exit 0
+          end
+        end
+      end
+
+      def inject_port_flags(command, port)
+        return command if command.empty?
+        return command if command.any? { |a| a.match?(/\A(-p|--port)(=|\z)/) }
+        return command if command.any? { |a| a.include?("$PORT") }
+
+        bin = File.basename(command.first.to_s)
+        needs_flags = PORT_IGNORING.include?(bin) ||
+          (command.length > 2 && PORT_IGNORING.include?(File.basename(command[2].to_s)))
+        return command unless needs_flags
+
+        command + ["--port", port.to_s, "--host", "127.0.0.1"]
+      end
+
+      # Legacy procfile parsing for backwards compat.
+      def procfile_command(process = nil)
+        path = ::Yamine::Procfile.find_file(Dir.pwd)
+        return nil unless path
+        lines = ::Yamine::Procfile.parse_file(path)
+        line = if process
+                 lines.find { |l| l.name == process }
+               else
+                 lines.first
+               end
+        return nil unless line
+        line.compound ? nil : ["sh", "-c", line.command]
+      end
+
+      def trap_cleanup(ctx, hostnames, pids = [])
+        %w[INT TERM].each do |sig|
+          trap(sig) do
+            cleanup_routes(ctx, hostnames)
+            pids.each { |pid| Process.kill("TERM", pid) rescue nil }
+            exit 0
+          end
+        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
+            entry = ctx.store.find(h)
+            pid = ctx.backend_pid_for(entry) if entry
+            if pid && ProxyControl.pid_alive?(pid)
+              Process.kill("TERM", pid) rescue nil
+            end
+            ctx.store.remove_route(h, owner_pid: Process.pid) rescue nil
+            FileUtils.rm_f(File.join(ctx.store.dir, "backend-#{h}.pid"))
+          rescue StandardError
+            nil
+          end
+        end
+      end
+
+      def resolve!(ctx, variant: nil, tld: nil)
+        # The resolver calls Config.load, which raises ConfigError if
+        # config/local.yml is missing — exactly what we want.
+        Yamine::Resolver.resolve(Dir.pwd, variant: variant, tld: tld)
+      end
+
+      def ensure_proxy!(ctx)
+        port = ctx.proxy_port
+        tls = ctx.proxy_tls
+        if ProxyControl.listening?(port)
+          return if ProxyControl.ours?(port, tls: tls)
+          $stderr.puts "Error: port #{port} is in use by another process."
+          $stderr.puts "  Stop it, or yamine proxy start -p <port>"
+          exit 1
+        end
+        privileged = port < 1024 && !ProxyControl.root?
+        if privileged && !ctx.interactive?
+          $stderr.puts "Error: proxy is not running and port #{port} needs root."
+          $stderr.puts "  Human: run this once — yamine setup"
+          $stderr.puts "  Agent/CI: pre-provision passwordless sudo once —"
+          $stderr.puts "    yamine sudoers > /tmp/yamine.sudoers"
+          $stderr.puts "    sudo install -o root -g wheel -m 440 /tmp/yamine.sudoers /etc/sudoers.d/yamine"
+          $stderr.puts "  Or start the proxy by hand: sudo yamine proxy start"
+          exit 1
+        end
+        puts "Starting proxy#{privileged ? " (sudo)" : ""}..."
+        begin
+          Yamine::ProxyControl.spawn_daemon(store: ctx.store, port: port, tls: tls, sudo: privileged)
+        rescue Yamine::ProxyNotRunningError => e
+          $stderr.puts "Error: #{e.message.lines.first&.strip}"
+          $stderr.puts "  Fix once: yamine setup"
+          exit 1
+        end
+      rescue Errno::EACCES
+        $stderr.puts "Error: permission denied binding port #{port}."
+        $stderr.puts "  Fix once: yamine setup"
+        exit 1
+      end
+    end
+  end
+end

data/lib/yamine/cli/context.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module Yamine
+  class CLI
+    # Shared state and helpers for command objects. Every command gets a
+    # Context instead of reaching into CLI privates, so cli.rb stays a
+    # thin dispatcher.
+    class Context
+      def store
+        @store ||= RouteStore.new(Certs.state_dir,
+          on_warning: ->(m) { warn m })
+      end
+
+      def interactive?
+        $stdin.tty? && ENV["CI"].nil?
+      end
+
+      def proxy_port
+        ProxyControl.proxy_port(store) || ProxyControl.default_port(proxy_tls)
+      end
+
+      def proxy_tls
+        ProxyControl.proxy_tls(store)
+      end
+
+      def report_unresolved(hostnames)
+        missing = Hosts.unresolved(hostnames)
+        return if missing.empty?
+
+        warn "Warning: #{missing.join(", ")} will not resolve. Run: yamine hosts sync"
+      end
+
+      def wait_for_exit(pid, timeout:)
+        deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
+        until Process.clock_gettime(Process::CLOCK_MONOTONIC) > deadline
+          return true unless ProxyControl.pid_alive?(pid)
+
+          sleep 0.25
+        end
+        !ProxyControl.pid_alive?(pid)
+      end
+
+      def backend_pid_for(entry)
+        return nil unless entry
+
+        sidecar = File.join(store.dir, "backend-#{entry["hostname"]}.pid")
+        return nil unless File.file?(sidecar)
+
+        pid = File.read(sidecar).strip.to_i
+        pid.positive? ? pid : nil
+      rescue SystemCallError, ArgumentError
+        nil
+      end
+
+      def backend_alive?(entry)
+        case entry["kind"]
+        when "socket"
+          File.socket?(entry["target"].to_s)
+        when "tcp"
+          host, port = entry["target"].to_s.split(":", 2)
+          begin
+            TCPSocket.new(host, port.to_i).close
+            true
+          rescue SystemCallError
+            false
+          end
+        else
+          false
+        end
+      end
+
+      def parse_flags(args, known)
+        opts = { rest: [] }
+        i = 0
+        rest_start = nil
+        while i < args.length
+          arg = args[i]
+          if arg == "--"
+            rest_start = i + 1
+            break
+          elsif arg.start_with?("--")
+            key = arg.sub(/\A--/, "").tr("-", "_").to_sym
+            if known.include?(key)
+              if %i[branch force].include?(key)
+                opts[key] = true
+                i += 1
+              else
+                opts[key] = args.fetch(i + 1)
+                i += 2
+              end
+            else
+              raise Error, "Unknown flag #{arg}"
+            end
+          else
+            rest_start = i
+            break
+          end
+        end
+        opts[:rest] = rest_start ? args[rest_start..] : []
+        opts
+      end
+    end
+  end
+end