yamine 0.3.0

data/lib/yamine/supervisor.rb

@@ -0,0 +1,242 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "monitor"
+
+module Yamine
+  # Daemon-owned supervision for managed socket apps (puma-dev model).
+  #
+  # The proxy daemon is long-lived and sees every request, so it owns:
+  # last-used tracking (idle kill), tmp/restart.txt watching, backend
+  # liveness, and boot-on-request for stopped apps. Run-mode (tcp)
+  # routes and static aliases are never supervised.
+  #
+  # State is in-memory (the daemon is the only supervisor); routes.json
+  # stays declarative. Killing is graceful-first with a short KILL
+  # fallback so puma drains.
+  class Supervisor
+    DEFAULT_IDLE = 900 # 15 minutes
+
+    attr_reader :interval
+
+    def initialize(store:, runner:, interval: 5.0, idle_timeout: nil, on_event: nil)
+      @store = store
+      @runner = runner
+      @interval = interval
+      @idle_timeout = idle_timeout || Supervisor.env_idle || DEFAULT_IDLE
+      @on_event = on_event || ->(msg) { warn "[yamine] #{msg}" }
+      # Monitor (reentrant): touch → st → state_for nest legitimately.
+      @state = {}.extend(MonitorMixin)
+      @boot_locks = {}
+      @thread = nil
+    end
+
+    def self.env_idle
+      v = ENV["YAMINE_IDLE_TIMEOUT"]
+      return nil unless v && v.to_f >= 0
+
+      v.to_f
+    end
+
+    def supervised?(route)
+      route["kind"] == "socket" && route["spec"].is_a?(Hash) && route["spec"]["dir"].is_a?(String)
+    end
+
+    def touch(hostname)
+      @state.synchronize do
+        st(hostname)[:last_used] = clock_now
+      end
+    end
+
+    # Boot a stopped app on demand. Returns the route (unchanged — the
+    # target path is deterministic) or nil on boot failure.
+    def ensure_running(route, timeout: 60)
+      return route unless supervised?(route)
+
+      socket_alive?(route) ? route : boot(route, timeout)
+    end
+
+    # Start the background supervision thread.
+    def start
+      @thread ||= Thread.new do
+        loop do
+          sleep @interval
+          begin
+            tick
+          rescue StandardError => e
+            @on_event.call("supervision error: #{e.message}")
+          end
+        end
+      end
+    end
+
+    def stop
+      @thread&.kill
+      @thread = nil
+    end
+
+    # One supervision pass (public for tests): kills idle/dead/restarted
+    # backends. Rebooting happens lazily on the next request.
+    def tick(now = clock_now)
+      @store.load_routes.each do |route|
+        next unless supervised?(route)
+
+        hostname = route["hostname"]
+        st = state_for(hostname, route, now)
+        next if st[:restarting]
+
+        if restart_changed?(route, st)
+          @on_event.call("restart.txt changed for #{hostname} — stopping backend")
+          kill_backend(route)
+          st[:restarting] = true
+        elsif !socket_alive?(route)
+          @on_event.call("backend for #{hostname} is down — will boot on next request")
+          st[:restarting] = true
+        elsif idle?(st, now)
+          @on_event.call("#{hostname} idle — stopping backend (boots on next request)")
+          kill_backend(route)
+          st[:restarting] = true
+        end
+      end
+    end
+
+    # Kill every supervised backend (daemon shutdown).
+    def shutdown
+      @store.load_routes.each do |route|
+        kill_backend(route) if supervised?(route)
+      end
+    end
+
+    def idle?(st, now)
+      return false if @idle_timeout.zero?
+      return false unless st[:last_used]
+
+      (now - st[:last_used]) > @idle_timeout
+    end
+
+    def socket_alive?(route)
+      target = route["target"]
+      return false unless target && File.socket?(target)
+
+      UNIXSocket.new(target).close
+      true
+    rescue SystemCallError, IOError
+      false
+    end
+
+    def backend_pid(route)
+      sidecar = File.join(@store.dir, "backend-#{route["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 kill_backend(route)
+      pid = backend_pid(route)
+      if pid && pid_alive?(pid)
+        begin
+          Process.kill("TERM", pid)
+          wait_exit(pid, 10)
+        rescue SystemCallError
+          nil
+        end
+      end
+      FileUtils.rm_f(route["target"]) if route["target"]
+      FileUtils.rm_f(File.join(@store.dir, "backend-#{route["hostname"]}.pid"))
+    end
+
+    private
+
+    def clock_now
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+
+    def state_for(hostname, route, now)
+      @state.synchronize do
+        s = st(hostname)
+        # First sighting: baseline so a freshly booted app gets a full
+        # idle window and an existing restart.txt doesn't count as changed.
+        s[:restart_mtime] = restart_mtime(route) if s[:restart_mtime].nil?
+        s[:last_used] = now if s[:last_used].nil?
+        s
+      end
+    end
+
+    def st(hostname)
+      @state.synchronize { @state[hostname] ||= {} }
+    end
+
+    def restart_mtime(route)
+      path = restart_path(route)
+      path && File.exist?(path) ? File.mtime(path) : nil
+    rescue SystemCallError
+      nil
+    end
+
+    def restart_changed?(route, st)
+      path = restart_path(route)
+      return false unless path
+
+      current = File.exist?(path) ? File.mtime(path) : nil
+      if current != st[:restart_mtime]
+        st[:restart_mtime] = current
+        true
+      else
+        false
+      end
+    rescue SystemCallError
+      false
+    end
+
+    def restart_path(route)
+      dir = route.dig("spec", "dir")
+      dir ? File.join(dir, "tmp", "restart.txt") : nil
+    end
+
+    def boot(route, timeout)
+      hostname = route["hostname"]
+      lock = @boot_locks[hostname] ||= Mutex.new
+      lock.synchronize do
+        # Double-check under the boot lock.
+        return route if socket_alive?(route)
+
+        spec = route["spec"]
+        @on_event.call("booting #{hostname} on request (#{spec["dir"]})")
+        url = Hostname.url(hostname, port: ProxyControl.proxy_port(@store),
+          tls: ProxyControl.proxy_tls(@store))
+        @runner.boot_supervised(name: hostname, hostname: hostname,
+          url: url, dir: spec["dir"])
+        st = st(hostname)
+        st[:last_used] = clock_now
+        route
+      end
+    rescue StandardError => e
+      @on_event.call("boot failed for #{hostname}: #{e.message.lines.first&.strip}")
+      nil
+    end
+
+    def wait_exit(pid, timeout)
+      deadline = clock_now + timeout
+      while clock_now < deadline
+        return unless pid_alive?(pid)
+
+        sleep 0.2
+      end
+      begin
+        Process.kill("KILL", pid)
+      rescue SystemCallError
+        nil
+      end
+    end
+
+    def pid_alive?(pid)
+      Process.kill(0, pid)
+      true
+    rescue SystemCallError
+      false
+    end
+  end
+end

data/lib/yamine/trust.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+require "open3"
+
+module Yamine
+  # Install the local CA into the OS trust store.
+  module Trust
+    module_function
+
+    def platform
+      case RUBY_PLATFORM
+      when /darwin/ then :macos
+      when /linux/ then :linux
+      when /mingw|mswin/ then :windows
+      else :unknown
+      end
+    end
+
+    def trust(dir = Certs.state_dir)
+      paths = Certs.ensure_ca(dir)
+      case platform
+      when :macos then trust_macos(paths[:cert])
+      when :linux then trust_linux(paths[:cert])
+      when :windows then trust_windows(paths[:cert])
+      else return { trusted: false, error: "Unsupported platform: #{RUBY_PLATFORM}" }
+      end
+      Certs.mark_trusted(dir)
+      { trusted: true }
+    rescue StandardError => e
+      { trusted: false, error: e.message }
+    end
+
+    def trust_macos(cert_path)
+      if Process.uid.zero?
+        # Running elevated (service install / root proxy): add to the
+        # System keychain with the admin (-d) domain. Root can modify it
+        # silently — no GUI authorization popup, and every user's
+        # browsers trust the proxy.
+        _out, status = Command.capture2("security", "add-trusted-cert",
+          "-d", "-r", "trustRoot", "-k", "/Library/Keychains/System.keychain", cert_path)
+        raise CertError, "security add-trusted-cert (system) failed" unless status.success?
+      else
+        keychain = login_keychain
+        _out, status = Command.capture2("security", "add-trusted-cert",
+          "-r", "trustRoot", "-k", keychain, cert_path)
+        raise CertError, "security add-trusted-cert failed" unless status.success?
+      end
+    end
+
+    def login_keychain
+      out, status = Command.capture2("security", "default-keychain")
+      if status.success? && (m = out.match(/"(.+)"/))
+        m[1]
+      else
+        File.join(Certs.home, "Library", "Keychains", "login.keychain-db")
+      end
+    end
+
+    def trust_linux(cert_path)
+      dest_dir, update_cmd = linux_ca_config
+      FileUtils.mkdir_p(dest_dir)
+      FileUtils.cp(cert_path, File.join(dest_dir, "yamine-ca.crt"))
+      _out, status = Command.capture2(update_cmd)
+      raise CertError, "#{update_cmd} failed" unless status.success?
+    end
+
+    def linux_ca_config
+      os_release = begin
+        File.read("/etc/os-release").downcase
+      rescue SystemCallError
+        ""
+      end
+      if os_release.include?("arch")
+        ["/etc/ca-certificates/trust-source/anchors", "update-ca-trust"]
+      elsif os_release.match?(/fedora|rhel|centos/)
+        ["/etc/pki/ca-trust/source/anchors", "update-ca-trust"]
+      elsif os_release.include?("suse")
+        ["/etc/pki/trust/anchors", "update-ca-certificates"]
+      else
+        ["/usr/local/share/ca-certificates", "update-ca-certificates"]
+      end
+    end
+
+    def trust_windows(cert_path)
+      _out, status = Command.capture2("certutil", "-addstore", "-user", "Root", cert_path)
+      raise CertError, "certutil failed" unless status.success?
+    end
+
+    # Best-effort removal of the CA from the OS trust store. Only
+    # attempts when our marker says we trusted it; used by `clean`.
+    def untrust(dir = Certs.state_dir)
+      return { removed: true } unless Certs.trusted?(dir)
+
+      paths = Certs.ca_paths(dir)
+      errors = []
+      case platform
+      when :macos
+        Command.capture2("security", "remove-trusted-cert", paths[:cert])
+        # delete-certificate fails silently when no match remains; loop
+        # to clear duplicate CN entries from each keychain.
+        [login_keychain, "/Library/Keychains/System.keychain"].each do |kc|
+          5.times do
+            Command.capture2("security", "delete-certificate", "-c", Certs::CA_COMMON_NAME, kc)
+          end
+        rescue SystemCallError
+          nil
+        end
+      when :linux
+        dest_dir, update_cmd = linux_ca_config
+        dest = File.join(dest_dir, "yamine-ca.crt")
+        FileUtils.rm_f(dest) if File.file?(dest)
+        Command.capture2(update_cmd)
+      when :windows
+        Command.capture2("certutil", "-delstore", "-user", "Root", Certs::CA_COMMON_NAME)
+      end
+      trusted_after = begin
+        Certs.trusted?(dir)
+      rescue StandardError
+        false
+      end
+      File.unlink(File.join(dir, "ca.trusted")) if File.file?(File.join(dir, "ca.trusted"))
+      if trusted_after
+        { removed: false, error: errors.empty? ? "CA still trusted (remove manually)" : errors.join("; ") }
+      else
+        { removed: true }
+      end
+    rescue StandardError => e
+      { removed: false, error: e.message }
+    end
+  end
+end

data/lib/yamine/variant.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+require "open3"
+require "pathname"
+
+module Yamine
+  # Variant resolution: the malleable axis of the hostname.
+  #
+  # Precedence: explicit --variant flag -> YAMINE_VARIANT env ->
+  # linked git worktree branch -> current git branch (opt-in via
+  # --branch / YAMINE_BRANCH=1) -> none.
+  #
+  # Main/master (and detached HEAD) never produce a variant.
+  module Variant
+    DEFAULT_BRANCHES = %w[main master].freeze
+
+    module_function
+
+    # Returns [variant, source] or nil.
+    def resolve(cwd = Dir.pwd, explicit: nil, use_branch: false)
+      return labeled(explicit, "flag") if present?(explicit)
+
+      env = ENV["YAMINE_VARIANT"]
+      return labeled(env, "YAMINE_VARIANT") if present?(env)
+
+      worktree = worktree_prefix(cwd)
+      return [worktree, "git worktree"] if worktree
+
+      branch_flag = use_branch || %w[1 true].include?(ENV["YAMINE_BRANCH"])
+      return nil unless branch_flag
+
+      branch = current_branch(cwd)
+      prefix = branch_to_prefix(branch)
+      prefix ? [prefix, "git branch"] : nil
+    end
+
+    def apply(base_name, variant)
+      variant ? "#{variant}.#{base_name}" : base_name
+    end
+
+    # NOTE: do not add a `private` keyword in this module — it would
+    # cancel `module_function` mode and demote the helpers below to
+    # plain private instance methods. They stay module functions
+    # (private as instance methods) by omitting it.
+    def present?(value)
+      !value.nil? && !value.to_s.strip.empty?
+    end
+
+    def labeled(value, source)
+      label = Sanitize.hostname_label(value)
+      label.empty? ? nil : [label, source]
+    end
+
+    def branch_to_prefix(branch)
+      return nil if branch.nil? || branch.empty?
+      return nil if branch == "HEAD" || DEFAULT_BRANCHES.include?(branch)
+
+      last = branch.split("/").last.to_s
+      label = Sanitize.hostname_label(last)
+      label.empty? ? nil : label
+    end
+
+    # Only linked worktrees (created via `git worktree add`) get a prefix.
+    # Developers on feature branches in their main checkout keep the bare name.
+    def worktree_prefix(cwd)
+      list_out, list_status = git(cwd, "worktree", "list", "--porcelain")
+      return nil unless list_status.success?
+
+      count = list_out.lines.count { |l| l.start_with?("worktree ") }
+      return nil if count <= 1
+
+      git_dir, s1 = git(cwd, "rev-parse", "--git-dir")
+      common_dir, s2 = git(cwd, "rev-parse", "--git-common-dir")
+      return nil unless s1.success? && s2.success?
+
+      # Same dir => main worktree, no prefix.
+      expanded = File.expand_path(git_dir.strip, cwd)
+      expanded_common = File.expand_path(common_dir.strip, cwd)
+      return nil if expanded == expanded_common
+
+      branch, s3 = git(cwd, "rev-parse", "--abbrev-ref", "HEAD")
+      return nil unless s3.success?
+
+      branch_to_prefix(branch.strip)
+    rescue SystemCallError
+      filesystem_worktree_prefix(cwd)
+    end
+
+    # Fallback when git CLI is unavailable: a linked worktree has a .git
+    # FILE pointing into a /worktrees/ path (submodules point to /modules/).
+    def filesystem_worktree_prefix(cwd)
+      dir = Pathname.new(File.expand_path(cwd))
+      until dir.root?
+        git_path = dir.join(".git")
+        if git_path.file?
+          content = git_path.read.strip
+          match = content.match(/\Agitdir:\s*(.+)\z/)
+          if match && match[1].match?(%r{[/\\]worktrees[/\\][^/\\]+\z})
+            head = File.join(File.expand_path(match[1], dir.to_s), "HEAD")
+            branch = read_branch_from_head(head)
+            prefix = branch_to_prefix(branch.to_s)
+            return prefix ? [prefix, "git worktree"].first : nil
+          end
+          return nil
+        end
+        return nil if git_path.directory?
+
+        dir = dir.parent
+      end
+      nil
+    rescue SystemCallError
+      nil
+    end
+
+    def read_branch_from_head(head_path)
+      content = File.read(head_path).strip
+      match = content.match(%r{\Aref:\s*refs/heads/(.+)\z})
+      match && match[1]
+    rescue SystemCallError
+      nil
+    end
+
+    def current_branch(cwd)
+      out, status = git(cwd, "rev-parse", "--abbrev-ref", "HEAD")
+      status.success? ? out.strip : nil
+    end
+
+    def git(cwd, *args)
+      Open3.capture2("git", *args, chdir: cwd, err: File::NULL)
+    rescue SystemCallError, ArgumentError
+      ["", nil]
+    end
+  end
+end

data/lib/yamine/version.rb

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

data/lib/yamine.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative "yamine/version"
+require_relative "yamine/errors"
+require_relative "yamine/sanitize"
+require_relative "yamine/hostname"
+require_relative "yamine/inference"
+require_relative "yamine/variant"
+require_relative "yamine/framework"
+require_relative "yamine/config"
+require_relative "yamine/ownership"
+require_relative "yamine/command"
+require_relative "yamine/log"
+require_relative "yamine/route_store"
+require_relative "yamine/certs"
+require_relative "yamine/ports"
+require_relative "yamine/hosts"
+require_relative "yamine/proxy"
+require_relative "yamine/proxy_control"
+require_relative "yamine/supervisor"
+require_relative "yamine/runner"
+require_relative "yamine/resolver"
+require_relative "yamine/trust"
+require_relative "yamine/doctor"
+require_relative "yamine/cli/context"
+require_relative "yamine/procfile"
+require_relative "yamine/cli/boot"
+require_relative "yamine/cli/routes"
+require_relative "yamine/cli/system"
+require_relative "yamine/cli"
+
+# Stable named .localhost URLs for Ruby development.
+#
+# Yamine replaces memorized ports with stable hostnames:
+# `yamine` in your app dir boots it at https://<app>.localhost.
+module Yamine
+end

metadata

@@ -0,0 +1,137 @@
+--- !ruby/object:Gem::Specification
+name: yamine
+version: !ruby/object:Gem::Version
+  version: 0.3.0
+platform: ruby
+authors:
+- Kaka Ruto
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: base64
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.25'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.25'
+- !ruby/object:Gem::Dependency
+  name: mocha
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+description: Gives every Ruby app a stable https://<app>.localhost URL instead of
+  a memorized port. Explicit-run reverse proxy with zero-config name inference, git-worktree
+  variants, per-host TLS, and agent-friendly list/get/doctor commands. Ruby stdlib
+  only.
+email:
+- kaka@myrrlabs.com
+executables:
+- yamine
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- bin/yamine
+- lib/ask/skills/yamine/SKILL.md
+- lib/yamine.rb
+- lib/yamine/certs.rb
+- lib/yamine/cli.rb
+- lib/yamine/cli/boot.rb
+- lib/yamine/cli/context.rb
+- lib/yamine/cli/routes.rb
+- lib/yamine/cli/system.rb
+- lib/yamine/command.rb
+- lib/yamine/config.rb
+- lib/yamine/doctor.rb
+- lib/yamine/errors.rb
+- lib/yamine/framework.rb
+- lib/yamine/hostname.rb
+- lib/yamine/hosts.rb
+- lib/yamine/inference.rb
+- lib/yamine/log.rb
+- lib/yamine/ownership.rb
+- lib/yamine/ports.rb
+- lib/yamine/procfile.rb
+- lib/yamine/proxy.rb
+- lib/yamine/proxy_control.rb
+- lib/yamine/resolver.rb
+- lib/yamine/route_store.rb
+- lib/yamine/runner.rb
+- lib/yamine/sanitize.rb
+- lib/yamine/supervisor.rb
+- lib/yamine/trust.rb
+- lib/yamine/variant.rb
+- lib/yamine/version.rb
+homepage: https://github.com/ask-rb/yamine
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/ask-rb/yamine
+  source_code_uri: https://github.com/ask-rb/yamine
+  changelog_uri: https://github.com/ask-rb/yamine/blob/master/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.18
+specification_version: 4
+summary: Stable named .localhost URLs for Ruby development
+test_files: []