ask-local 0.1.0

data/lib/ask/local/cli/system.rb

@@ -0,0 +1,294 @@
+# frozen_string_literal: true
+
+module Ask
+  module Local
+    class CLI
+      # System commands: proxy, service, hosts, trust, clean, doctor, kamal.
+      module SystemCommand
+        module_function
+
+        def doctor(ctx, args)
+          json = args.delete("--json")
+          failed = Doctor.print(Doctor.run(store: ctx.store), out: $stdout, json: !!json)
+          exit(failed.zero? ? 0 : 1)
+        end
+
+        def trust(_ctx, _args)
+          result = Trust.trust
+          if result[:trusted]
+            puts "CA trusted."
+          else
+            $stderr.puts "Error: #{result[:error]}"
+            exit 1
+          end
+        end
+
+        def clean(ctx, _args)
+          ProxyControl.stop(ctx.store)
+          result = Trust.untrust
+          puts "CA removed from trust store." if result[:removed]
+          warn "CA untrust failed: #{result[:error]}" if result[:error]
+          Hosts.clean
+          require "fileutils"
+          FileUtils.rm_rf(ctx.store.dir)
+          puts "Cleaned ask-local state."
+        end
+
+        def hosts(ctx, args)
+          sub = args.first
+          case sub
+          when "sync"
+            hostnames = ctx.store.load_routes.map { |r| r["hostname"] }
+            if Hosts.sync(hostnames)
+              puts "Synced #{hostnames.length} hostname(s) to /etc/hosts."
+            else
+              $stderr.puts "Could not write /etc/hosts (try sudo)."
+              exit 1
+            end
+          when "clean"
+            Hosts.clean
+            puts "Removed ask-local entries from /etc/hosts."
+          else
+            raise Error, "Usage: ask-local hosts [sync|clean]"
+          end
+        end
+
+        def proxy(ctx, args)
+          sub = args.first
+          case sub
+          when "start"
+            port, tls, foreground = parse_proxy_start(args[1..])
+            tlds = active_tlds(args[1..])
+            if foreground
+              write_tls_marker(ctx, tls)
+              write_tlds_file(ctx, tlds)
+              sup = Supervisor.new(store: ctx.store, runner: Runner.new(store: ctx.store),
+                on_event: ->(m) { warn m })
+              sup.start
+              Proxy.new(store: ctx.store, port: port, tls: tls,
+                state_dir: ctx.store.dir, supervisor: sup, tlds: tlds).start_foreground
+            else
+              ProxyControl.spawn_daemon(store: ctx.store, port: port, tls: tls, tlds: tlds)
+              puts "Proxy started on port #{port}#{tls ? " (HTTPS)" : " (HTTP)"}."
+            end
+          when "stop"
+            case ProxyControl.stop(ctx.store)
+            when :stopped then puts "Proxy stopped."
+            when :stale then puts "Removed stale proxy state."
+            when :not_running then puts "Proxy is not running."
+            when :unknown_process then puts "Port in use by an unknown process."
+            end
+          else
+            raise Error, "Usage: ask-local proxy [start|stop]"
+          end
+        end
+
+        def write_tls_marker(ctx, tls)
+          ctx.store.ensure_dir
+          path = File.join(ctx.store.dir, "proxy.tls")
+          tls ? File.write(path, "1") : File.write(path, "0")
+        end
+
+        # TLDs the proxy serves: --tld flags, else ASK_LOCAL_TLD, else
+        # localhost. Persisted so auto-restarted daemons agree, and so
+        # the 404 page knows which hosts are "ours" (rebinding boundary).
+        def active_tlds(args)
+          flags = []
+          i = 0
+          while i < args.length
+            if args[i] == "--tld"
+              flags << args.fetch(i + 1).to_s
+              i += 2
+            else
+              i += 1
+            end
+          end
+          list = flags.any? ? flags : (ENV["ASK_LOCAL_TLD"]&.split(",")&.map(&:strip) || [])
+          list = list.reject(&:empty?).map(&:downcase).uniq
+          list.empty? ? [Hostname::DEFAULT_TLD] : list
+        end
+
+        def write_tlds_file(ctx, tlds)
+          ctx.store.ensure_dir
+          File.write(File.join(ctx.store.dir, "proxy.tlds"), "#{tlds.join("\n")}\n")
+        rescue SystemCallError
+          nil
+        end
+
+        def parse_proxy_start(args)
+          port = nil
+          tls = true
+          foreground = false
+          i = 0
+          while i < args.length
+            case args[i]
+            when "-p", "--port" then port = args.fetch(i + 1).to_i; i += 2
+            when "--no-tls" then tls = false; i += 1
+            when "--https" then tls = true; i += 1
+            when "--foreground" then foreground = true; i += 1
+            when "--tld" then i += 2 # consumed by active_tlds
+            else i += 1
+            end
+          end
+          [port || ProxyControl.default_port(tls), tls, foreground]
+        end
+
+        def service(ctx, args)
+          sub = args.first
+          case sub
+          when "install" then service_install(ctx, args)
+          when "uninstall" then service_uninstall
+          when "status" then service_status(ctx)
+          else raise Error, "Usage: ask-local service [install|uninstall|status]"
+          end
+        end
+
+        # Root-owned LaunchDaemon binding 80/443 at boot (puma-dev model).
+        # Re-execs under sudo; the proxy runs with the invoking user's state
+        # dir so routes registered by unprivileged CLIs are shared
+        # (portless pattern). A root proxy can also write /etc/hosts.
+        def service_install(ctx, args)
+          if !ProxyControl.root? && !args.include?("--internal")
+            puts "Installing system service (sudo required)..."
+            state = Certs.state_dir
+            ok = system("sudo", "env", "ASK_LOCAL_STATE_DIR=#{state}",
+              RbConfig.ruby, ProxyControl.bin_path,
+              "service", "install", "--internal")
+            exit(ok ? 0 : 1)
+          end
+          case RUBY_PLATFORM
+          when /darwin/ then install_launchd(ctx)
+          when /linux/ then print_linux_unit
+          else raise Error, "Service install not supported on #{RUBY_PLATFORM}"
+          end
+        end
+
+        def user_home_for_service
+          sudo_user = ENV["SUDO_USER"]
+          if sudo_user && !sudo_user.empty?
+            require "etc"
+            Etc.getpwnam(sudo_user).dir
+          else
+            Certs.home
+          end
+        rescue ArgumentError
+          Certs.home
+        end
+
+        def install_launchd(ctx)
+          require "etc"
+          home = user_home_for_service
+          state_dir = ENV["ASK_LOCAL_STATE_DIR"] || File.join(home, ".ask-local")
+          dir = "/Library/LaunchDaemons"
+          FileUtils.mkdir_p(dir)
+          plist = <<~PLIST
+            <?xml version="1.0" encoding="UTF-8"?>
+            <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+            <plist version="1.0">
+            <dict>
+              <key>Label</key><string>dev.ask.local</string>
+              <key>ProgramArguments</key>
+              <array>
+                <string>#{RbConfig.ruby}</string>
+                <string>#{ProxyControl.bin_path}</string>
+                <string>proxy</string><string>start</string><string>--foreground</string>
+              </array>
+              <key>EnvironmentVariables</key>
+              <dict>
+                <key>ASK_LOCAL_STATE_DIR</key><string>#{state_dir}</string>
+                <key>HOME</key><string>#{home}</string>
+              </dict>
+              <key>KeepAlive</key><true/>
+              <key>RunAtLoad</key><true/>
+            </dict>
+            </plist>
+          PLIST
+          path = File.join(dir, "dev.ask.local.plist")
+          File.write(path, plist)
+          File.chmod(0o644, path)
+          Ownership.chown_service_files(path)
+          system("launchctl", "unload", path) rescue nil
+          system("launchctl", "load", path) or raise Error, "launchctl load failed"
+          puts "Installed root LaunchDaemon on port 443 (state: #{state_dir})."
+          puts "Restart your machine or run: sudo launchctl load #{path}"
+        end
+
+        def print_linux_unit
+          home = user_home_for_service
+          state_dir = ENV["ASK_LOCAL_STATE_DIR"] || File.join(home, ".ask-local")
+          puts <<~UNIT
+            # /etc/systemd/system/ask-local.service  (binds 80/443 at boot)
+            [Unit]
+            After=network.target
+
+            [Service]
+            ExecStart=#{RbConfig.ruby} #{ProxyControl.bin_path} proxy start --foreground
+            Environment=ASK_LOCAL_STATE_DIR=#{state_dir}
+            Environment=HOME=#{home}
+
+            [Install]
+            WantedBy=multi-user.target
+
+            Install with: sudo cp ask-local.service /etc/systemd/system/ && sudo systemctl enable --now ask-local
+            (Run that install command with sudo so the service is root-owned.)
+          UNIT
+        end
+
+        def service_uninstall(_ctx)
+          if !ProxyControl.root?
+            state = Certs.state_dir
+            ok = system("sudo", "env", "ASK_LOCAL_STATE_DIR=#{state}",
+              RbConfig.ruby, ProxyControl.bin_path, "service", "uninstall", "--internal")
+            exit(ok ? 0 : 1)
+          end
+          case RUBY_PLATFORM
+          when /darwin/
+            path = "/Library/LaunchDaemons/dev.ask.local.plist"
+            system("launchctl", "unload", path) rescue nil
+            FileUtils.rm_f(path)
+            puts "Removed root LaunchDaemon."
+          else
+            puts "Remove /etc/systemd/system/ask-local.service, then: sudo systemctl disable --now ask-local"
+          end
+        end
+
+        def service_status(ctx)
+          port = ProxyControl.proxy_port(ctx.store)
+          if port.nil? || !ProxyControl.listening?(port)
+            puts "Proxy not running."
+          elsif ProxyControl.ours?(port, tls: ProxyControl.proxy_tls(ctx.store))
+            puts "Proxy running on port #{port}."
+          else
+            puts "Port #{port} in use by another process."
+          end
+        end
+
+        # ask-local kamal <variant> [--app myapp] [--domain preview.example.com]
+        def kamal(_ctx, args)
+          opts = {}
+          rest = []
+          i = 0
+          a = args.dup
+          while i < a.length
+            case a[i]
+            when "--app" then opts[:app] = a.fetch(i + 1); i += 2
+            when "--domain" then opts[:domain] = a.fetch(i + 1); i += 2
+            else rest << a[i]; i += 1
+            end
+          end
+          variant = rest.first
+          raise Error, "Usage: ask-local kamal <variant> [--app myapp] [--domain preview.example.com]" unless variant
+
+          app = opts[:app] || Resolver.resolve(Dir.pwd, use_branch: false).app
+          domain = opts[:domain] || ENV["ASK_LOCAL_KAMAL_DOMAIN"] || "preview.example.com"
+          slug = Sanitize.hostname_label(variant)
+          puts "# Paste into deploy.yml proxy section for a preview of variant #{slug}:"
+          puts "proxy:"
+          puts "  ssl: true"
+          puts "  hosts:"
+          puts "    - #{app}-#{slug}.#{domain}"
+        end
+      end
+    end
+  end
+end

data/lib/ask/local/cli.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require "optparse"
+
+module Ask
+  module Local
+    # Command-line interface. Thin dispatcher: every command lives in
+    # lib/ask/local/cli/{boot,routes,system}.rb behind a shared Context.
+    # OptionParser only, no Thor.
+    #
+    # In non-interactive environments (no TTY or CI=1) we fail early with
+    # a clear message instead of prompting (portless lesson).
+    class CLI
+      SUBCOMMANDS = %w[run get alias hosts list doctor trust clean prune proxy service kamal stop restart log status open].freeze
+
+      def self.run(argv)
+        new.run(argv)
+        0
+      rescue Error => e
+        $stderr.puts "Error: #{e.message}"
+        1
+      rescue OptionParser::InvalidOption => e
+        $stderr.puts "Error: #{e.message}"
+        1
+      end
+
+      def run(argv)
+        args = argv.dup
+        if args.empty? || (!SUBCOMMANDS.include?(args.first) && !args.first.start_with?("-"))
+          return BootCommand.run_inferred(Context.new, args)
+        end
+
+        cmd = args.shift
+        ctx = Context.new
+        case cmd
+        when "run" then BootCommand.run_explicit(ctx, args)
+        when "get" then RoutesCommand.get(ctx, args)
+        when "alias" then RoutesCommand.alias_add(ctx, args)
+        when "hosts" then SystemCommand.hosts(ctx, args)
+        when "list" then RoutesCommand.list(ctx, args)
+        when "doctor" then SystemCommand.doctor(ctx, args)
+        when "trust" then SystemCommand.trust(ctx, args)
+        when "clean" then SystemCommand.clean(ctx, args)
+        when "prune" then RoutesCommand.prune(ctx, args)
+        when "proxy" then SystemCommand.proxy(ctx, args)
+        when "service" then SystemCommand.service(ctx, args)
+        when "kamal" then SystemCommand.kamal(ctx, args)
+        when "stop"
+          exit RoutesCommand.stop(ctx, args)
+        when "restart" then RoutesCommand.restart(ctx, args)
+        when "log" then RoutesCommand.log(ctx, args)
+        when "status" then RoutesCommand.status(ctx, args)
+        when "open" then RoutesCommand.open(ctx, args)
+        when "--help", "-h" then help
+        when "--version", "-v" then puts "ask-local #{VERSION}"
+        else BootCommand.run_named(ctx, cmd, args)
+        end
+      end
+
+      private
+
+      def help
+        puts <<~HELP
+          ask-local - Stable named .localhost URLs for Ruby development.
+
+          Usage:
+            ask-local                        Infer name, boot app -> https://<app>.localhost
+            ask-local run [cmd]              Same, with explicit command
+            ask-local <name> <cmd>           Run with explicit name
+            ask-local get <name>             Print URL for a service
+            ask-local alias <name> <port>    Static route (e.g. Docker)
+            ask-local list                   Show active routes (+ backend liveness)
+            ask-local status                 Show effective naming context here
+            ask-local open [name]            Open the app URL in a browser
+            ask-local doctor                 Check proxy, routes, DNS, CA trust
+            ask-local trust                  Add local CA to trust store
+            ask-local clean                  Remove state and hosts entries
+            ask-local prune                  Remove stale routes
+            ask-local proxy start|stop       Control the proxy
+            ask-local service install|status|uninstall   OS startup service
+            ask-local hosts sync|clean       Manage /etc/hosts entries
+            ask-local kamal <variant>        Preview-deploy snippet for Kamal
+            ask-local stop                   Stop this app's backend + routes
+            ask-local restart                Touch tmp/restart.txt
+            ask-local 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)
+          Env: ASK_LOCAL_NAME/SERVICE/VARIANT/TLD/PORT/STATE_DIR, ASK_LOCAL_BRANCH=1
+        HELP
+      end
+
+      # Backwards-compatible access for tests written against the old
+      # monolith: CLI.new.send(:inject_port_flags / :procfile_command).
+      def inject_port_flags(command, port)
+        BootCommand.inject_port_flags(command, port)
+      end
+
+      def procfile_command(process = nil)
+        BootCommand.procfile_command(process)
+      end
+    end
+  end
+end

data/lib/ask/local/config.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Ask
+  module Local
+    # Optional ask-local.json in the app directory.
+    #
+    #   { "name": "myapp" }
+    #   { "name": "myapp", "service": "api", "variant": "demo",
+    #     "tlds": ["localhost"], "appPort": 3000 }
+    #
+    # Monorepo roots may add an "apps" map keyed by path relative to the
+    # config dir; top-level fields apply only in single-app mode.
+    class Config
+      FILENAME = "ask-local.json"
+      TOP_KEYS = %w[name service variant tlds appPort proxy apps].freeze
+      APP_KEYS = %w[name service variant tlds appPort proxy].freeze
+
+      attr_reader :data, :dir
+
+      def self.load(dir = Dir.pwd)
+        path = File.join(dir, FILENAME)
+        return nil unless File.file?(path)
+
+        parsed = JSON.parse(File.read(path))
+        raise ConfigError, "#{path} must be a JSON object" unless parsed.is_a?(Hash)
+
+        new(parsed, dir, path)
+      rescue JSON::ParserError => e
+        raise ConfigError, "Invalid JSON in #{path}: #{e.message}"
+      end
+
+      def initialize(data, dir, path = FILENAME)
+        @data = data
+        @dir = dir
+        @path = path
+        validate!
+      end
+
+      def app_config(package_dir = dir)
+        return slice(APP_KEYS) unless data["apps"].is_a?(Hash)
+
+        rel = relative(package_dir)
+        return {} if rel.nil? || rel.start_with?("..")
+
+        candidate = rel
+        loop do
+          hit = data["apps"][candidate]
+          return hit.select { |k, _| APP_KEYS.include?(k) } if hit.is_a?(Hash)
+
+          parent = File.dirname(candidate)
+          break if parent == "." || parent == candidate
+
+          candidate = parent
+        end
+        {}
+      end
+
+      def [](key)
+        data[key]
+      end
+
+      private
+
+      def slice(keys)
+        data.select { |k, _| keys.include?(k) }
+      end
+
+      def relative(package_dir)
+        require "pathname"
+        Pathname.new(File.expand_path(package_dir))
+          .relative_path_from(Pathname.new(File.expand_path(dir))).to_s
+      rescue ArgumentError
+        nil
+      end
+
+      def validate!
+        data.each_key do |key|
+          warn "Warning: Unknown key #{key.inspect} in #{@path}. Known keys: #{TOP_KEYS.join(", ")}" unless TOP_KEYS.include?(key)
+        end
+        validate_app_fields(data, "top level")
+        if data["apps"]
+          raise ConfigError, %("apps" in #{@path} must be an object) unless data["apps"].is_a?(Hash)
+
+          data["apps"].each do |name, entry|
+            raise ConfigError, %("apps.#{name}" in #{@path} must be an object) unless entry.is_a?(Hash)
+
+            validate_app_fields(entry, "apps.#{name}")
+          end
+        end
+      end
+
+      def validate_app_fields(fields, prefix)
+        if fields["appPort"] && !(fields["appPort"].is_a?(Integer) && fields["appPort"].between?(1, 65_535))
+          raise ConfigError, %("#{prefix}.appPort" in #{@path} must be an integer 1-65535)
+        end
+        if fields.key?("proxy") && ![true, false].include?(fields["proxy"])
+          raise ConfigError, %("#{prefix}.proxy" in #{@path} must be a boolean)
+        end
+        %w[name service variant].each do |key|
+          next unless fields.key?(key)
+          next if fields[key].is_a?(String) && !fields[key].strip.empty?
+
+          raise ConfigError, %("#{prefix}.#{key}" in #{@path} must be a non-empty string)
+        end
+        if fields["tlds"] && !(fields["tlds"].is_a?(Array) && fields["tlds"].all? { |t| t.is_a?(String) })
+          raise ConfigError, %("#{prefix}.tlds" in #{@path} must be an array of strings)
+        end
+      end
+    end
+  end
+end

data/lib/ask/local/doctor.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+module Ask
+  module Local
+    # Read-only health checks: proxy, routes, DNS, CA trust.
+    # Never changes state; safe for agents to call any time.
+    module Doctor
+      Check = Struct.new(:name, :ok, :message, keyword_init: true)
+
+      module_function
+
+      def run(store:, port: nil, tls: nil)
+        checks = []
+        port ||= ProxyControl.proxy_port(store)
+        tls = ProxyControl.proxy_tls(store) if tls.nil?
+
+        checks << check_state_dir(store)
+        checks << check_disk(store)
+        checks << check_proxy(port, tls: tls)
+        checks << check_routes(store)
+        checks << check_dns(store)
+        checks << check_ca
+        checks
+      end
+
+      # ENOSPC on the state dir looks like our bug (socket bind fails,
+      # route writes vanish). Warn well before that: 100MB is already
+      # unreasonable for route files plus a rotated proxy log.
+      DISK_WARN_BYTES = 100 * 1024 * 1024
+
+      def check_disk(store)
+        used = Log.disk_usage(store.dir)
+        if used > DISK_WARN_BYTES
+          Check.new(name: "disk", ok: false,
+            message: "state dir uses #{Log.human_bytes(used)} — " \
+              "check #{File.join(store.dir, "proxy.log*")} for runaway logging")
+        else
+          Check.new(name: "disk", ok: true,
+            message: "state dir uses #{Log.human_bytes(used)}")
+        end
+      end
+
+      # Root-owned state files lock the unprivileged CLI out of its own
+      # state — the failure then looks like corruption, not permissions.
+      # Say so plainly.
+      def check_state_dir(store)
+        dir = store.dir
+        begin
+          FileUtils.mkdir_p(dir) unless File.directory?(dir)
+          probe = File.join(dir, ".writability-probe")
+          File.write(probe, "1")
+          File.unlink(probe)
+          Check.new(name: "state", ok: true, message: "#{dir} writable")
+        rescue SystemCallError => e
+          Check.new(name: "state", ok: false,
+            message: "#{dir} not writable (#{e.message}) — " \
+              "if a root proxy wrote here, run: sudo chown -R $USER #{dir}")
+        end
+      end
+
+      def check_proxy(port, tls:)
+        if port.nil?
+          return Check.new(name: "proxy", ok: false,
+            message: "not running — run: ask-local proxy start")
+        end
+        unless ProxyControl.listening?(port)
+          return Check.new(name: "proxy", ok: false,
+            message: "port #{port} not listening — run: ask-local proxy start")
+        end
+        if ProxyControl.ours?(port, tls: tls)
+          Check.new(name: "proxy", ok: true, message: "listening on port #{port}")
+        else
+          Check.new(name: "proxy", ok: false,
+            message: "port #{port} is in use by another process")
+        end
+      end
+
+      def check_routes(store)
+        routes = store.load_routes
+        if routes.empty?
+          Check.new(name: "routes", ok: true, message: "no active routes")
+        else
+          stale = store.load_routes_raw.length - routes.length
+          msg = "#{routes.length} active route(s)"
+          msg += " (#{stale} stale pruned)" if stale.positive?
+          Check.new(name: "routes", ok: true, message: msg)
+        end
+      end
+
+      def check_dns(store)
+        hostnames = store.load_routes.map { |r| r["hostname"] }
+        return Check.new(name: "dns", ok: true, message: "no routes to resolve") if hostnames.empty?
+
+        missing = Hosts.unresolved(hostnames)
+        if missing.empty?
+          Check.new(name: "dns", ok: true, message: "all #{hostnames.length} hostname(s) resolve")
+        else
+          Check.new(name: "dns", ok: false,
+            message: "#{missing.join(", ")} do not resolve — run: ask-local hosts sync")
+        end
+      end
+
+      def check_ca
+        dir = Certs.state_dir
+        paths = Certs.ca_paths(dir)
+        unless File.file?(paths[:cert])
+          return Check.new(name: "ca", ok: false, message: "no CA yet — run: ask-local trust")
+        end
+        if Certs.trusted?(dir)
+          Check.new(name: "ca", ok: true, message: "CA trusted")
+        else
+          Check.new(name: "ca", ok: false, message: "CA not trusted — run: ask-local trust")
+        end
+      end
+
+      def print(checks, out: $stdout, json: false)
+        if json
+          require "json"
+          out.puts JSON.generate({
+            checks: checks.map { |c| { name: c.name, ok: c.ok, message: c.message } },
+            failed: checks.count { |c| !c.ok }
+          })
+          return checks.count { |c| !c.ok }
+        end
+        failed = 0
+        checks.each do |c|
+          mark = c.ok ? "ok" : "FAIL"
+          failed += 1 unless c.ok
+          out.puts "  [#{mark}] #{c.name}: #{c.message}"
+        end
+        failed
+      end
+    end
+  end
+end

data/lib/ask/local/errors.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Ask
+  module Local
+    class Error < StandardError; end
+    class ConfigError < Error; end
+    class RouteConflictError < Error
+      attr_reader :hostname, :existing_pid
+
+      def initialize(hostname, existing_pid)
+        @hostname = hostname
+        @existing_pid = existing_pid
+        super("\"#{hostname}\" is already registered by a running process " \
+              "(PID #{existing_pid}). Use --force to override.")
+      end
+    end
+    class ProxyNotRunningError < Error; end
+    class CertError < Error; end
+  end
+end