ask-local 0.1.0

data/lib/ask/local/supervisor.rb

@@ -0,0 +1,244 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "monitor"
+
+module Ask
+  module Local
+    # 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 "[ask-local] #{msg}" }
+        # Monitor (reentrant): touch → st → state_for nest legitimately.
+        @state = {}.extend(MonitorMixin)
+        @boot_locks = {}
+        @thread = nil
+      end
+
+      def self.env_idle
+        v = ENV["ASK_LOCAL_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
+end

data/lib/ask/local/trust.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+require "open3"
+
+module Ask
+  module Local
+    # 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)
+        keychain = login_keychain
+        _out, status = Open3.capture2("security", "add-trusted-cert",
+          "-r", "trustRoot", "-k", keychain, cert_path)
+        raise CertError, "security add-trusted-cert failed" unless status.success?
+      end
+
+      def login_keychain
+        out, status = Open3.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, "ask-local-ca.crt"))
+        _out, status = Open3.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 = Open3.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
+          Open3.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
+              Open3.capture2("security", "delete-certificate", "-c", CA_COMMON_NAME, kc)
+            end
+          rescue SystemCallError
+            nil
+          end
+        when :linux
+          dest_dir, update_cmd = linux_ca_config
+          dest = File.join(dest_dir, "ask-local-ca.crt")
+          FileUtils.rm_f(dest) if File.file?(dest)
+          Open3.capture2(update_cmd)
+        when :windows
+          Open3.capture2("certutil", "-delstore", "-user", "Root", 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
+end

data/lib/ask/local/variant.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+require "open3"
+require "pathname"
+
+module Ask
+  module Local
+    # Variant resolution: the malleable axis of the hostname.
+    #
+    # Precedence: explicit --variant flag -> ASK_LOCAL_VARIANT env ->
+    # linked git worktree branch -> current git branch (opt-in via
+    # --branch / ASK_LOCAL_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["ASK_LOCAL_VARIANT"]
+        return labeled(env, "ASK_LOCAL_VARIANT") if present?(env)
+
+        worktree = worktree_prefix(cwd)
+        return [worktree, "git worktree"] if worktree
+
+        branch_flag = use_branch || %w[1 true].include?(ENV["ASK_LOCAL_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
+end

data/lib/ask/local/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Ask
+  module Local
+    VERSION = "0.1.0"
+  end
+end

data/lib/ask/skills/ask-local/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: ask-local
+description: Run Ruby apps through ask-local 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, Procfile apps), wiring frontend to API, configuring OAuth callbacks or webhooks, debugging port conflicts, or working in git worktrees.
+---
+
+# Local Dev with ask-local
+
+Never invent ports. Never parse them from logs. Every app has a stable URL.
+
+## Booting apps
+
+```bash
+ask-local                        # infer name, boot -> https://<app>.localhost
+ask-local --service api          # -> https://api.myapp.localhost
+ask-local run -- bin/dev         # Procfile apps, PORT injected
+ask-local run --proc worker      # boot a specific Procfile process
+```
+
+Managed apps are supervised by the proxy daemon: they idle-stop after 15
+minutes (`ASK_LOCAL_IDLE_TIMEOUT`), stop when `tmp/restart.txt` is
+touched, and boot again on the next request.
+
+## Lifecycle
+
+```bash
+ask-local stop                   # stop this app's backend + routes
+ask-local restart                # touch tmp/restart.txt (supervised reboot)
+ask-local log [n]                # tail this app's backend log
+```
+
+The runner injects `ASK_LOCAL_URL`, `PORT`, and `HOST=127.0.0.1` into the
+child. In Rails, read it via `Ask::Local::Rails.url` — never hardcode
+`localhost:3000`.
+
+## Cross-service wiring
+
+```bash
+ask-local get backend            # -> https://backend.localhost
+```
+
+Use `get` output for frontend-to-API URLs, Cable URLs, and webhook
+targets. Do not guess ports.
+
+## Variants (worktrees, branches, demos)
+
+Hostnames compose as `{variant}.{service}.{app}.{tld}`. Linked worktrees
+get a branch prefix automatically (`fix-ui.myapp.localhost`); main keeps
+the bare name. Override with `--variant` or `ASK_LOCAL_VARIANT`.
+
+## OAuth and webhooks
+
+Build callback URLs from `ASK_LOCAL_URL`:
+
+```ruby
+callback = "#{Ask::Local::Rails.url}/auth/google/callback"
+```
+
+Strict providers (Google, Apple) reject `.localhost`. Serve the app on a
+domain you own instead — no code change:
+
+```bash
+ask-local --tld local.example.com   # -> https://myapp.local.example.com
+```
+
+## Troubleshooting
+
+```bash
+ask-local doctor                 # read-only: proxy, routes, DNS, CA trust
+ask-local list                   # active routes
+ask-local prune                  # clear stale routes from crashed sessions
+```
+
+Prefer `list --json`, `status --json`, and `doctor --json` when parsing
+output programmatically — stable keys, no prose scraping.
+
+If a hostname does not resolve: `ask-local hosts sync`. If the browser
+warns about TLS: `ask-local trust`. Never run dev servers on bare ports
+alongside ask-local — they bypass routing and reintroduce conflicts.
+
+## When NOT to use ask-local
+
+- **CI pipelines**: no TTY, no sudo, no browsers. Run the app's own test
+  command directly; ask-local 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 `ask-local proxy start --foreground`
+  and read the log; do not layer another ask-local on top.

data/lib/ask-local.rb

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