yamine 0.3.0

data/lib/yamine/framework.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require "pathname"
+
+module Yamine
+  # Detect what kind of Ruby app lives in a directory so the runner
+  # knows how to boot it. Pure filesystem convention, no shell-outs.
+  module Framework
+    RAILS = :rails
+    RACK = :rack
+    JEKYLL = :jekyll
+    BRIDGETOWN = :bridgetown
+    MIDDLEMAN = :middleman
+    PROCFILE = :procfile
+    UNKNOWN = :unknown
+
+    STATIC_GENERATORS = [JEKYLL, BRIDGETOWN, MIDDLEMAN].freeze
+
+    module_function
+
+    def detect(dir = Dir.pwd)
+      path = Pathname.new(File.expand_path(dir))
+      return RAILS if rails?(path)
+      return JEKYLL if jekyll?(path)
+      return BRIDGETOWN if bridgetown?(path)
+      return MIDDLEMAN if middleman?(path)
+      return RACK if rack?(path)
+      return PROCFILE if procfile?(path)
+
+      UNKNOWN
+    end
+
+    # Managed mode (unix socket via puma) applies to live Rack apps.
+    def managed?(framework)
+      framework == RAILS || framework == RACK
+    end
+
+    def rails?(path)
+      path.join("config", "application.rb").file? &&
+        path.join("config", "application.rb").read.match?(/<\s*Rails::Application/)
+    rescue SystemCallError
+      false
+    end
+
+    def rack?(path)
+      path.join("config.ru").file?
+    end
+
+    def jekyll?(path)
+      path.join("_config.yml").file? && gemfile_includes?(path, "jekyll")
+    end
+
+    def bridgetown?(path)
+      path.join("bridgetown.config.yml").file? ||
+        (path.join("config", "initializers").directory? && gemfile_includes?(path, "bridgetown"))
+    end
+
+    def middleman?(path)
+      path.join("config.rb").file? && gemfile_includes?(path, "middleman")
+    end
+
+    def procfile?(path)
+      path.join("Procfile.dev").file? || path.join("Procfile").file?
+    end
+
+    def gemfile_includes?(path, gem_name)
+      gemfile = path.join("Gemfile")
+      return false unless gemfile.file?
+
+      gemfile.read.match?(/gem\s+["']#{Regexp.escape(gem_name)}["']/)
+    rescue SystemCallError
+      false
+    end
+  end
+end

data/lib/yamine/hostname.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Yamine
+  # Hostname composition: {variant}.{service}.{app}.{tld}
+  #
+  # Each axis is independent. The web service is bare (myapp.localhost);
+  # any other service prefixes (api.myapp.localhost). A variant prefixes
+  # everything (fix-ui.myapp.localhost, fix-ui.api.myapp.localhost).
+  # An explicit full hostname bypasses composition entirely.
+  module Hostname
+    DEFAULT_TLD = "localhost"
+
+    module_function
+
+    # Build hostnames for every configured TLD.
+    def build(app:, tlds: [DEFAULT_TLD], service: nil, variant: nil)
+      tld_list = Array(tlds).flatten.compact
+      tld_list = [DEFAULT_TLD] if tld_list.empty?
+      tld_list.map { |tld| compose(app: app, tld: tld, service: service, variant: variant) }
+    end
+
+    def compose(app:, tld:, service: nil, variant: nil)
+      parts = [app.to_s]
+      # The web service is bare (myapp.localhost); every other service
+      # prefixes (api.myapp.localhost). "web" is the default service.
+      svc = service.to_s
+      parts.unshift(svc) if !svc.empty? && svc != "web"
+      parts.unshift(variant.to_s) if variant && !variant.to_s.empty?
+      "#{parts.join(".")}.#{tld}"
+    end
+
+    def url(hostname, port:, tls:)
+      scheme = tls ? "https" : "http"
+      default_port = tls ? 443 : 80
+      suffix = (port == default_port) ? "" : ":#{port}"
+      "#{scheme}://#{hostname}#{suffix}"
+    end
+
+    # Strip an explicit :port from a Host header for routing.
+    def strip_port(authority)
+      authority.to_s.split(":").first.to_s.downcase
+    end
+  end
+end

data/lib/yamine/hosts.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require "resolv"
+require "timeout"
+
+module Yamine
+  # /etc/hosts sync for Safari + custom TLDs (.localhost resolves natively
+  # in Chrome/Firefox/Edge; Safari uses the system resolver).
+  # Same managed-block approach as portless hosts.ts.
+  module Hosts
+    BEGIN_MARKER = "# --- yamine begin ---"
+    END_MARKER = "# --- yamine end ---"
+    PATH = "/etc/hosts"
+
+    module_function
+
+    def managed_block(hostnames)
+      lines = [BEGIN_MARKER]
+      hostnames.uniq.sort.each { |h| lines << "127.0.0.1 #{h}" }
+      lines << END_MARKER
+      "#{lines.join("\n")}\n"
+    end
+
+    def read(path = PATH)
+      File.read(path)
+    rescue SystemCallError
+      ""
+    end
+
+    def managed_hostnames(content = read)
+      inside = false
+      names = []
+      content.each_line do |line|
+        inside = true if line.strip == BEGIN_MARKER
+        next unless inside
+        break if line.strip == END_MARKER
+
+        parts = line.split
+        names.concat(parts[1..]) if parts.first == "127.0.0.1"
+      end
+      names
+    end
+
+    def sync(hostnames, path = PATH)
+      content = read(path)
+      block = managed_block(hostnames)
+      if content.include?(BEGIN_MARKER)
+        updated = content.sub(/#{Regexp.escape(BEGIN_MARKER)}.*?#{Regexp.escape(END_MARKER)}\n?/m, block)
+      else
+        updated = "#{content.rstrip}\n#{block}"
+      end
+      File.write(path, updated)
+      true
+    rescue SystemCallError
+      false
+    end
+
+    # True when /etc/hosts already carries exactly the managed block for
+    # these hostnames. The root service install syncs under elevation;
+    # plain re-runs of setup must not fail trying to rewrite it
+    # unprivileged when nothing changed.
+    def synced?(hostnames, path = PATH)
+      read(path).include?(managed_block(hostnames))
+    end
+
+    def clean(path = PATH)
+      content = read(path)
+      updated = content.sub(/#{Regexp.escape(BEGIN_MARKER)}.*?#{Regexp.escape(END_MARKER)}\n?/m, "")
+      File.write(path, updated)
+      true
+    rescue SystemCallError
+      false
+    end
+
+    def resolves?(hostname)
+      Timeout.timeout(2) { Resolv.getaddress(hostname) }
+      true
+    rescue Resolv::ResolvError, SystemCallError, Timeout::Error
+      false
+    end
+
+    def unresolved(hostnames)
+      hostnames.reject { |h| resolves?(h) }
+    end
+  end
+end

data/lib/yamine/inference.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+require "json"
+require "open3"
+require "pathname"
+
+module Yamine
+  # Zero-flag app name inference.
+  #
+  # Order: yamine.json "name" -> Rails module in config/application.rb ->
+  # gemspec name -> package.json name (for hybrid apps) -> git root basename
+  # -> directory basename. First non-empty sanitized name wins.
+  module Inference
+    CONFIG_FILENAME = "yamine.json"
+
+    module_function
+
+    # Returns [name, source].
+    def infer(cwd = Dir.pwd)
+      from_config(cwd) ||
+        from_rails_module(cwd) ||
+        from_gemspec(cwd) ||
+        from_package_json(cwd) ||
+        from_git_root(cwd) ||
+        from_directory(cwd)
+    end
+
+    def from_config(cwd)
+      path = File.join(cwd, CONFIG_FILENAME)
+      return nil unless File.file?(path)
+
+      parsed = JSON.parse(File.read(path))
+      name = parsed["name"] || parsed.dig("apps", ".", "name")
+      return nil if name.nil? || name.strip.empty?
+
+      [Sanitize.hostname_label(name), "yamine.json"]
+    rescue JSON::ParserError, SystemCallError
+      nil
+    end
+
+    # Myapp::Application -> myapp (walks up for config/application.rb).
+    def from_rails_module(cwd)
+      dir = Pathname.new(cwd)
+      until dir.root?
+        candidate = dir.join("config", "application.rb")
+        if candidate.file?
+          mod = parse_rails_module(candidate.read)
+          return [Sanitize.hostname_label(mod), "config/application.rb"] if mod
+        end
+        dir = dir.parent
+      end
+      nil
+    end
+
+    def parse_rails_module(source)
+      match = source.match(/module\s+([A-Z][A-Za-z0-9_]*)/)
+      return nil unless match
+
+      # CamelCase with digit runs -> kebab: Rails8Min => rails-8-min,
+      # MyApp => my-app. Underscores become hyphens as well.
+      match[1].gsub(/([a-z0-9])([A-Z])/, '\1-\2')
+        .gsub(/([A-Z]+)([A-Z][a-z])/, '\1-\2')
+        .gsub(/([a-zA-Z])(\d)/, '\1-\2')
+        .gsub(/(\d)([a-zA-Z])/, '\1-\2')
+        .tr("_", "-").downcase
+    end
+
+    # First *.gemspec with a name in cwd (non-recursive, top level only).
+    def from_gemspec(cwd)
+      Dir.glob(File.join(cwd, "*.gemspec")).sort.each do |path|
+        name = parse_gemspec_name(File.read(path))
+        next if name.nil? || name.empty?
+
+        base = name.split("/").last
+        labeled = Sanitize.hostname_label(base)
+        return [labeled, File.basename(path)] unless labeled.empty?
+      end
+      nil
+    rescue SystemCallError
+      nil
+    end
+
+    def parse_gemspec_name(source)
+      match = source.match(/\.name\s*=\s*["']([^"']+)["']/)
+      match && match[1]
+    end
+
+    def from_package_json(cwd)
+      dir = Pathname.new(cwd)
+      until dir.root?
+        pkg = dir.join("package.json")
+        if pkg.file?
+          parsed = JSON.parse(pkg.read)
+          raw = parsed["name"]
+          if raw.is_a?(String) && !raw.empty?
+            base = raw.sub(%r{\A@[^/]+/}, "")
+            labeled = Sanitize.hostname_label(base)
+            return [labeled, "package.json"] unless labeled.empty?
+          end
+        end
+        dir = dir.parent
+      end
+      nil
+    rescue JSON::ParserError, SystemCallError
+      nil
+    end
+
+    def from_git_root(cwd)
+      root = git_root(cwd)
+      return nil unless root
+
+      labeled = Sanitize.hostname_label(File.basename(root))
+      labeled.empty? ? nil : [labeled, "git root"]
+    end
+
+    def from_directory(cwd)
+      labeled = Sanitize.hostname_label(File.basename(File.expand_path(cwd)))
+      raise Error, "Could not infer a project name from #{cwd}" if labeled.empty?
+
+      [labeled, "directory name"]
+    end
+
+    def git_root(cwd)
+      out, status = Open3.capture2("git", "rev-parse", "--show-toplevel",
+        chdir: cwd, err: File::NULL)
+      return out.strip if status.success? && !out.strip.empty?
+
+      walk_up_for_git(cwd)
+    rescue SystemCallError, ArgumentError
+      walk_up_for_git(cwd)
+    end
+
+    def walk_up_for_git(cwd)
+      dir = Pathname.new(File.expand_path(cwd))
+      until dir.root?
+        return dir.to_s if dir.join(".git").exist?
+        dir = dir.parent
+      end
+      nil
+    end
+  end
+end

data/lib/yamine/log.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Yamine
+  # Size-based log rotation. Nothing rotated today: proxy.log grows
+  # forever and every managed boot appends to the app log — a Rails app
+  # with HMR polling plus a long-lived daemon eventually fills the disk,
+  # and ENOSPC on the socket dir looks like our bug. Rotate before write.
+  module Log
+    # Rotate when the file exceeds this size; keep one generation.
+    MAX_BYTES = Integer(ENV.fetch("YAMINE_LOG_MAX_BYTES", 5 * 1024 * 1024))
+    KEEP_GENERATIONS = 1
+
+    module_function
+
+    # Open path for appending, rotating first if oversize. Returns the
+    # open File so spawn(out:) can take it directly.
+    def open_append(path, max_bytes: MAX_BYTES)
+      rotate(path, max_bytes: max_bytes)
+      FileUtils.mkdir_p(File.dirname(path))
+      File.open(path, "a")
+    end
+
+    def rotate(path, max_bytes: MAX_BYTES)
+      return unless File.file?(path)
+      return unless File.size(path) > max_bytes
+
+      KEEP_GENERATIONS.downto(1) do |gen|
+        src = gen == 1 ? path : "#{path}.#{gen - 1}"
+        dst = "#{path}.#{gen}"
+        FileUtils.mv(src, dst, force: true) if File.file?(src)
+      end
+    rescue SystemCallError
+      nil
+    end
+
+    # Bytes under dir (state dir or app log dir), for doctor reporting.
+    def disk_usage(dir)
+      total = 0
+      Dir.glob(File.join(dir, "**", "*")).each do |f|
+        total += File.size(f) if File.file?(f)
+      rescue SystemCallError
+        nil
+      end
+      total
+    end
+
+    def human_bytes(bytes)
+      if bytes >= 1024 * 1024
+        format("%.1f MB", bytes.to_f / (1024 * 1024))
+      elsif bytes >= 1024
+        format("%.1f KB", bytes.to_f / 1024)
+      else
+        "#{bytes} B"
+      end
+    end
+  end
+end

data/lib/yamine/ownership.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require "etc"
+require "fileutils"
+
+module Yamine
+  # File ownership across the root/user boundary.
+  #
+  # The sudo-spawned daemon and the root LaunchDaemon both write into
+  # the invoking user's state dir. The first root-owned file lands,
+  # the unprivileged CLI can no longer register routes — and the
+  # failure looks like corruption, not permissions. Every root write
+  # path calls fix() so the tree stays user-owned.
+  module Ownership
+    module_function
+
+    # The user behind sudo, or nil when not elevated.
+    def invoking_user
+      sudo_user = ENV["SUDO_USER"]
+      return nil if sudo_user.nil? || sudo_user.empty?
+
+      Etc.getpwnam(sudo_user)
+    rescue ArgumentError
+      nil
+    end
+
+    # Chown path (recursively for dirs) to the invoking user. No-op
+    # when not running as root or when the user cannot be resolved.
+    def fix(*paths)
+      user = invoking_user
+      return unless user
+      return unless Process.uid.zero?
+
+      paths.each do |path|
+        begin
+          if File.directory?(path) && !File.symlink?(path)
+            FileUtils.chown_R(user.uid, user.gid, path)
+          else
+            FileUtils.chown(user.uid, user.gid, path)
+          end
+        rescue SystemCallError, ArgumentError
+          nil
+        end
+      end
+    end
+
+    # Fresh state files a root proxy creates: routes, pid/port/tls
+    # markers and the log. Called after ensure_dir in daemon boot paths.
+    def chown_state_dir(dir)
+      fix(dir)
+    end
+  end
+end

data/lib/yamine/ports.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require "socket"
+
+module Yamine
+  # Ephemeral TCP ports for run-mode backends (4000-4999, portless range).
+  # Random-first then sequential; WHATWG blocked ports skipped.
+  module Ports
+    MIN_PORT = 4000
+    MAX_PORT = 4999
+    RANDOM_ATTEMPTS = 50
+
+    # Browsers refuse these (WHATWG fetch "bad port" list); Next.js too.
+    BLOCKED = [0, 1, 7, 9, 11, 13, 15, 17, 19, 20, 21, 22, 23, 25, 37, 42,
+      43, 53, 69, 77, 79, 87, 95, 101, 102, 103, 104, 109, 110, 111, 113,
+      115, 117, 119, 123, 135, 137, 139, 143, 161, 179, 389, 427, 465, 512,
+      513, 514, 515, 526, 530, 531, 532, 540, 548, 554, 556, 563, 587, 601,
+      636, 989, 990, 993, 995, 1719, 1720, 1723, 2049, 3659, 4045, 4190,
+      5060, 5061, 6000, 6566, 6665, 6666, 6667, 6668, 6669, 6679, 6697,
+      10080].to_h { |p| [p, true] }.freeze
+
+    module_function
+
+    def free?(port)
+      server = TCPServer.new("127.0.0.1", port)
+      server.close
+      true
+    rescue SystemCallError
+      false
+    end
+
+    def find_free(min: MIN_PORT, max: MAX_PORT)
+      raise Error, "min (#{min}) must be <= max (#{max})" if min > max
+
+      RANDOM_ATTEMPTS.times do
+        port = min + rand(max - min + 1)
+        return port if !BLOCKED[port] && free?(port)
+      end
+      (min..max).each do |port|
+        return port if !BLOCKED[port] && free?(port)
+      end
+      raise Error, "No free port found in range #{min}-#{max}"
+    end
+  end
+end

data/lib/yamine/procfile.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+module Yamine
+  # Procfile.dev multi-process support: parse every line, classify each
+  # process as HTTP (gets a .localhost URL) or background (supervised,
+  # no URL), and boot them all with one command.
+  #
+  # Classification is deliberately permissive (portless lesson: proxy by
+  # default): a process is background only when its NAME says so
+  # (worker/job/sidekiq/watch/tunnel/build/css) or an yamine.json
+  # override says so. Everything else is HTTP. A misclassified worker
+  # harmlessly gets an unvisited route; a misclassified server with NO
+  # route is a broken dev day — so the bias is toward HTTP, and the boot
+  # banner always prints the classification so the fix is obvious.
+  #
+  # The Procfile stays canonical: Heroku, Docker, and plain
+  # `foreman start` keep working. yamine.json only overrides
+  # classification, ports, and env — it never replaces the Procfile.
+  module Procfile
+    HTTP = :http
+    BACKGROUND = :background
+
+    # Name fragments that mark a background process. Matched against
+    # the process NAME (left of the colon), not the command.
+    BACKGROUND_HINTS = %w[
+      worker job sidekiq solid_queue mission_control
+      watch tailwind css esbuild vite assets
+      tunnel cloudflared ngrok expose
+      build compile
+    ].freeze
+
+    COMPOUND = /&&|\|\||[|;]/.freeze
+
+    module_function
+
+    # Parsed line: {name, command, compound?}. Compound lines (shell
+    # operators) cannot be safely injected with PORT — refused loudly
+    # by the caller, never silently rewritten.
+    Line = Struct.new(:name, :command, :compound, keyword_init: true)
+
+    def parse_file(path)
+      lines = File.readlines(path, chomp: true)
+      entries = []
+      lines.each do |line|
+        stripped = line.strip
+        next if stripped.empty? || stripped.start_with?("#")
+        next unless stripped.include?(":")
+
+        name, cmd = stripped.split(":", 2).map(&:strip)
+        next if name.nil? || name.empty? || cmd.nil? || cmd.empty?
+
+        entries << Line.new(name: name, command: cmd, compound: cmd.match?(COMPOUND))
+      end
+      entries
+    rescue SystemCallError
+      []
+    end
+
+    def find_file(dir = Dir.pwd)
+      %w[Procfile.dev Procfile].each do |name|
+        path = File.join(dir, name)
+        return path if File.file?(path)
+      end
+      nil
+    end
+
+    # Classify one process. Overrides win: {"processes": {"worker":
+    # {"type": "background"}}} in yamine.json. Otherwise background
+    # on name hints, HTTP for everything else.
+    def classify(name, overrides: {})
+      override = overrides[name] || overrides[name.to_s]
+      if override.is_a?(Hash) && override["type"]
+        return override["type"].to_s == "background" ? BACKGROUND : HTTP
+      end
+      lowered = name.to_s.downcase
+      return BACKGROUND if BACKGROUND_HINTS.any? { |hint| lowered.include?(hint) }
+
+      HTTP
+    end
+
+    # Per-process overrides from yamine.json "processes" map:
+    # {"web": {"type": "http", "port": 3000, "env": {...}}, ...}.
+    # Unknown keys warn; the Procfile stays the source of the command.
+    def load_overrides(dir = Dir.pwd)
+      config = Config.load(dir)
+      return {} unless config
+
+      procs = config.data["processes"]
+      return {} unless procs.is_a?(Hash)
+
+      procs
+    end
+
+    # Split command string into argv for spawn (no shell). Returns nil
+    # for compound lines the caller must refuse.
+    def to_argv(command)
+      return nil if command.match?(COMPOUND)
+
+      split_command(command)
+    end
+
+    # Minimal shell-word split (quotes + backslash escapes), matching
+    # Config.split_command semantics for Procfile lines.
+    def split_command(command)
+      args = []
+      current = +""
+      in_single = false
+      in_double = false
+      escaped = false
+      command.each_char do |ch|
+        if escaped
+          current << ch
+          escaped = false
+          next
+        end
+        if ch == "\\" && !in_single
+          escaped = true
+          next
+        end
+        if ch == "'" && !in_double
+          in_single = !in_single
+        elsif ch == '"' && !in_single
+          in_double = !in_double
+        elsif ch.match?(/\s/) && !in_single && !in_double
+          unless current.empty?
+            args << current
+            current = +""
+          end
+        else
+          current << ch
+        end
+      end
+      args << current unless current.empty?
+      args
+    end
+  end
+end