ask-local 0.1.0

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

@@ -0,0 +1,255 @@
+# frozen_string_literal: true
+
+module Ask
+  module Local
+    class CLI
+      # Boot commands: bare `ask-local`, `run`, and `<name> <cmd>`.
+      # Owns managed/run boot orchestration, Procfile resolution, and the
+      # foreground supervision loop.
+      module BootCommand
+        # Frameworks that ignore $PORT get explicit flags (portless lesson:
+        # Vite/Astro/Expo need --port; Jekyll/Middleman/Bridgetown do too).
+        # Only injects when the user hasn't already set a port.
+        PORT_IGNORING = %w[jekyll middleman bridgetown].freeze
+
+        module_function
+
+        def run_inferred(ctx, args)
+          opts = ctx.parse_flags(args, %i[name service variant tld branch proc force])
+          resolved = Resolver.resolve(Dir.pwd, name: opts[:name],
+            service: opts[:service], variant: opts[:variant],
+            tlds: opts[:tld], use_branch: opts[:branch])
+          hostnames = Resolver.hostnames(resolved)
+          ensure_proxy!(ctx)
+          framework = Framework.detect(Dir.pwd)
+          runner = Runner.new(store: ctx.store)
+          if Framework.managed?(framework) && opts[:rest].empty?
+            boot_managed(ctx, runner, resolved, hostnames, opts)
+          else
+            command = opts[:rest].empty? ? default_command(framework, opts[:proc]) : opts[:rest]
+            boot_run(ctx, runner, resolved, hostnames, command, opts)
+          end
+        end
+
+        def run_explicit(ctx, args)
+          opts = ctx.parse_flags(args, %i[name service variant tld branch proc force])
+          resolved = Resolver.resolve(Dir.pwd, name: opts[:name],
+            service: opts[:service], variant: opts[:variant],
+            tlds: opts[:tld], use_branch: opts[:branch])
+          hostnames = Resolver.hostnames(resolved)
+          ensure_proxy!(ctx)
+          framework = Framework.detect(Dir.pwd)
+          command = opts[:rest].empty? ? default_command(framework, opts[:proc]) : opts[:rest]
+          boot_run(ctx, Runner.new(store: ctx.store), resolved, hostnames, command, opts)
+        end
+
+        def run_named(ctx, name, args)
+          opts = ctx.parse_flags(args, %i[force app_port])
+          resolved = Resolver.resolve(Dir.pwd, name: name)
+          hostnames = Resolver.hostnames(resolved)
+          ensure_proxy!(ctx)
+          if opts[:rest].empty?
+            $stderr.puts "Error: no command given for #{name}."
+            exit 1
+          end
+          boot_run(ctx, Runner.new(store: ctx.store), resolved, hostnames, opts[:rest], opts)
+        end
+
+        def boot_managed(ctx, runner, resolved, hostnames, opts)
+          primary = hostnames.first
+          url = Hostname.url(primary, port: ctx.proxy_port, tls: ctx.proxy_tls)
+          puts "ask-local"
+          puts "-- #{hostnames.join(", ")}"
+          app = runner.boot_managed(name: resolved.app, hostname: primary,
+            url: url, dir: Dir.pwd, force: opts[:force])
+          register_all(ctx, hostnames, app, force: opts[:force], spec: { "dir" => File.expand_path(Dir.pwd) })
+          puts "\n  -> #{url}\n"
+          ctx.report_unresolved(hostnames)
+          trap_cleanup(ctx, hostnames)
+          supervise_backend(ctx, hostnames, app)
+        end
+
+        def boot_run(ctx, runner, resolved, hostnames, command, opts)
+          primary = hostnames.first
+          url = Hostname.url(primary, port: ctx.proxy_port, tls: ctx.proxy_tls)
+          puts "ask-local"
+          puts "-- #{hostnames.join(", ")}"
+          port = opts[:app_port] || Ports.find_free
+          command = inject_port_flags(command, port)
+          app = runner.boot_run(name: resolved.app, hostname: primary, url: url,
+            dir: Dir.pwd, command: command, port: port, force: opts[:force])
+          register_all(ctx, hostnames, app, force: opts[:force])
+          puts "\n  -> #{url}\n"
+          puts "Running: PORT=#{app.target.split(":").last} ASK_LOCAL_URL=#{url} #{command.join(" ")}"
+          ctx.report_unresolved(hostnames)
+          trap_cleanup(ctx, hostnames)
+          supervise_backend(ctx, hostnames, app)
+        end
+
+        # Foreground loop: exit (cleaning up) when the backend dies, so a
+        # crashed app never leaves a stale route behind. Backends are
+        # spawned detached (so Ctrl+C in the CLI never SIGINTs the app),
+        # which rules out Process.wait — detached children are already
+        # reaped. Poll liveness at 2Hz: prompt enough for crash cleanup
+        # without spinning.
+        def supervise_backend(ctx, hostnames, app)
+          until !ProxyControl.pid_alive?(app.pid)
+            sleep 0.5
+          end
+          puts "\nBackend exited — cleaning up."
+          cleanup_routes(ctx, hostnames)
+          exit 0
+        end
+
+        def inject_port_flags(command, port)
+          return command if command.empty?
+          return command if command.any? { |a| a.match?(/\A(-p|--port)(=|\z)/) }
+          # A literal $PORT already present (e.g. Procfile `web: x --port $PORT`,
+          # foreman --port passthrough): injecting again would double-set it.
+          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
+
+          flags = ["--port", port.to_s, "--host", "127.0.0.1"]
+          flags.concat(jekyll_livereload_flags(port)) if jekyll_command?(command)
+          command + flags
+        end
+
+        # Jekyll's livereload runs its own server on a second port
+        # (default 35729) serving the livereload.js WebSocket. It cannot go
+        # through the proxy (one route = one backend), so pin it next to the
+        # main port and document the direct URL. Only when the app enables
+        # livereload in _config.yml; explicit user flags always win.
+        JEKYLL_LIVERELOAD_DEFAULT_PORT = 35_729
+
+        def jekyll_command?(command)
+          command.any? { |a| File.basename(a.to_s) == "jekyll" }
+        end
+
+        def jekyll_livereload_flags(port)
+          return [] unless File.file?("_config.yml")
+          return [] unless File.read("_config.yml").match?(/^\s*livereload:\s*true/i)
+          return [] if port + 1 > Ports::MAX_PORT
+
+          ["--livereload-port", (port + 1).to_s]
+        rescue SystemCallError
+          []
+        end
+
+        def default_command(framework, proc_name = nil)
+          case framework
+          when :procfile
+            procfile_command(proc_name) || raise(Error,
+              proc_name ? "Procfile has no '#{proc_name}' process, or its line is " \
+                "compound (&&, ||, |, ;) — ask-local cannot inject PORT safely. " \
+                "Run explicitly instead: ask-local run -- <command>" :
+                "Procfile.dev first line is compound (&&, ||, |, ;) or unreadable — " \
+                "ask-local cannot inject PORT safely. Run explicitly instead: " \
+                "ask-local run -- <command>")
+          when :jekyll then %w[bundle exec jekyll serve]
+          when :bridgetown then %w[bin/bridgetown start]
+          when :middleman then %w[bundle exec middleman server]
+          else raise(Error, "No command given and no bootable app detected. Usage: ask-local run -- <command>")
+          end
+        end
+
+        # First process by default; --proc <name> picks a specific line
+        # (the overmind `-P web` convention teams already use).
+        #
+        # Trust boundary: the Procfile line is repo code, so `sh -c` is
+        # safe here the way it would not be for user-supplied input.
+        def procfile_command(process = nil)
+          path = File.file?("Procfile.dev") ? "Procfile.dev" : "Procfile"
+          lines = File.readlines(path).map(&:strip).reject { |l| l.empty? || l.start_with?("#") }
+          chosen =
+            if process
+              lines.find { |l| l.start_with?("#{process}:") }
+            else
+              lines.first
+            end
+          return nil unless chosen
+
+          cmd = chosen.split(":", 2).last.to_s.strip
+          # Refuse compound lines we cannot safely inject PORT into.
+          return nil if cmd.match?(/&&|\|\||[|;]/)
+
+          ["sh", "-c", cmd]
+        end
+
+        def trap_cleanup(ctx, hostnames)
+          %w[INT TERM].each do |sig|
+            trap(sig) do
+              cleanup_routes(ctx, hostnames)
+              exit 0
+            end
+          end
+        end
+
+        # Primary hostname is registered by the runner; secondaries (extra
+        # TLDs) share the same backend. Every hostname gets a backend sidecar
+        # so `ask-local stop` finds the process from any of them, and the
+        # daemon supervisor needs the spec on every hostname.
+        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
+
+        # Foreground boot semantics (portless model): leaving = routes gone
+        # AND backend stopped. No orphans on Ctrl+C, TERM, or clean exit.
+        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 ensure_proxy!(ctx)
+          port = ctx.proxy_port
+          tls = ctx.proxy_tls
+          if ProxyControl.listening?(port)
+            if ProxyControl.ours?(port, tls: tls)
+              return
+            end
+
+            $stderr.puts "Error: port #{port} is in use by another process."
+          end
+
+          privileged = port < 1024 && !ProxyControl.root?
+          if privileged && !ctx.interactive?
+            $stderr.puts "Proxy is not running and no TTY is available for sudo."
+            $stderr.puts "Start it in a terminal: ask-local proxy start"
+            $stderr.puts "Or use an unprivileged port: ask-local proxy start -p 1355"
+            exit 1
+          end
+          puts "Starting proxy#{privileged ? " (will prompt for sudo to bind port #{port})" : ""}..."
+          ProxyControl.spawn_daemon(store: ctx.store, port: port, tls: tls, sudo: privileged)
+        rescue Errno::EACCES
+          $stderr.puts "Error: could not bind port #{port}. Try: ask-local proxy start -p 1355"
+          exit 1
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module Ask
+  module Local
+    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: ask-local 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
+end

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

@@ -0,0 +1,253 @@
+# frozen_string_literal: true
+
+module Ask
+  module Local
+    class CLI
+      # Route and app-lifecycle commands: get/alias/list/prune,
+      # stop/restart/log/status/open.
+      module RoutesCommand
+        module_function
+
+        # ask-local get <name> [--service x] [--variant y] [--tld z]
+        #
+        # Variant and TLDs are inherited from the CURRENT directory's
+        # context (worktree branch, ASK_LOCAL_* env, config) so cross-service
+        # wiring works inside a variant: from a fix-ui worktree,
+        # `get backend` -> https://fix-ui.backend.localhost.
+        def get(ctx, args)
+          name = args.first
+          raise Error, "Usage: ask-local get <name> [--service s] [--variant v] [--tld t]" unless name
+
+          opts = ctx.parse_flags(args[1..] || [], %i[service variant tld])
+          context = Resolver.resolve(Dir.pwd, service: opts[:service],
+            variant: opts[:variant], tlds: opts[:tld], use_branch: false)
+          hostnames = Hostname.build(
+            app: Sanitize.hostname_label(name),
+            service: context.service,
+            variant: context.variant,
+            tlds: context.tlds
+          )
+          puts Hostname.url(hostnames.first, port: ctx.proxy_port, tls: ctx.proxy_tls)
+        end
+
+        def list(ctx, args)
+          json = args.delete("--json")
+          routes = ctx.store.load_routes
+          port = ctx.proxy_port
+          tls = ctx.proxy_tls
+          entries = routes.map do |r|
+            { hostname: r["hostname"],
+              url: Hostname.url(r["hostname"], port: port, tls: tls),
+              target: r["target"], kind: r["kind"],
+              pid: r["pid"], supervised: !r["spec"].nil?,
+              alive: alive_state(ctx, r) }
+          end
+          if json
+            require "json"
+            puts JSON.generate({ routes: entries, proxy_port: port, tls: tls })
+            return
+          end
+          if entries.empty?
+            puts "No active routes."
+            puts "Start an app with: ask-local"
+            return
+          end
+          puts "\nActive routes:\n"
+          entries.each do |e|
+            puts "  #{e[:url]}  ->  #{e[:target]}  #{label_for(e)}"
+          end
+          puts
+        end
+
+        def alive_state(ctx, route)
+          if route["pid"] == 0
+            ctx.backend_alive?(route) ? "reachable" : "unreachable"
+          elsif ProxyControl.pid_alive?(route["pid"])
+            "running"
+          else
+            "owner-gone"
+          end
+        rescue StandardError
+          "unknown"
+        end
+
+        def label_for(entry)
+          if entry[:pid] == 0
+            "(alias, #{entry[:alive]})"
+          else
+            "(pid #{entry[:pid]}, #{entry[:alive]})"
+          end
+        end
+
+        # Backend liveness per route: agents can see at a glance whether
+        # the route points at something alive. Static aliases (pid 0)
+        # report the probe, not a process.
+        def route_label(ctx, route)
+          entry = { pid: route["pid"], alive: alive_state(ctx, route) }
+          label_for(entry)
+        end
+
+        def prune(ctx, _args)
+          stale = ctx.store.prune_stale
+          if stale.empty?
+            puts "No stale routes."
+          else
+            stale.each { |r| puts "Removed stale route #{r["hostname"]}" }
+          end
+        end
+
+        def alias_add(ctx, args)
+          if args.first == "--remove"
+            name = args[1] or raise Error, "Usage: ask-local alias --remove <name>"
+            hostname = alias_hostname(name)
+            ctx.store.remove_route(hostname)
+            puts "Removed alias #{hostname}."
+            return
+          end
+          name, port_or_url = args
+          raise Error, "Usage: ask-local alias <name> <port|url>" unless name && port_or_url
+
+          hostname = alias_hostname(name)
+          target = port_or_url.match?(/\A\d+\z/) ? "127.0.0.1:#{port_or_url}" : port_or_url
+          force = args.include?("--force")
+          ctx.store.add_route(hostname, target, 0, kind: "tcp", force: force)
+          puts "#{hostname} -> #{target}"
+        end
+
+        # A name containing dots is treated as a full hostname (any TLD);
+        # otherwise it is a label under the current TLD context
+        # (ASK_LOCAL_TLD first entry, else localhost).
+        def alias_hostname(name)
+          return Hostname.strip_port(name.downcase) if name.include?(".")
+
+          tld = ENV["ASK_LOCAL_TLD"]&.split(",")&.map(&:strip)&.reject(&:empty?)&.first
+          "#{Sanitize.hostname_label(name)}.#{tld || Hostname::DEFAULT_TLD}"
+        end
+
+        # Stop the app in the current directory (route + backend).
+        # Exit codes are machine-readable for agents: 0 stopped something,
+        # 2 no route here, 3 route existed but the backend was already gone.
+        def stop(ctx, _args, out: $stdout)
+          resolved = Resolver.resolve(Dir.pwd)
+          hostnames = Resolver.hostnames(resolved)
+          stopped = []
+          gone = []
+          hostnames.each do |hostname|
+            entry = ctx.store.find(hostname)
+            next unless entry
+
+            backend_pid = ctx.backend_pid_for(entry)
+            if backend_pid && ProxyControl.pid_alive?(backend_pid)
+              begin
+                Process.kill("TERM", backend_pid)
+                if ctx.wait_for_exit(backend_pid, timeout: 10)
+                  stopped << "#{hostname} (backend #{backend_pid})"
+                else
+                  stopped << "#{hostname} (backend #{backend_pid} still draining)"
+                end
+              rescue SystemCallError
+                gone << hostname
+              end
+            else
+              gone << hostname
+            end
+            ctx.store.remove_route(hostname)
+            FileUtils.rm_f(File.join(ctx.store.dir, "backend-#{hostname}.pid"))
+          end
+          if stopped.any?
+            stopped.each { |s| out.puts "Stopped #{s}." }
+            return 0
+          end
+          if gone.any?
+            out.puts "Route existed but the backend was already gone: #{gone.join(", ")}."
+            return 3
+          end
+
+          out.puts "No ask-local app running here."
+          2
+        end
+
+        # Touch tmp/restart.txt so a supervised managed app reboots.
+        def restart(_ctx, _args)
+          path = File.join(Dir.pwd, "tmp", "restart.txt")
+          require "fileutils"
+          FileUtils.mkdir_p(File.dirname(path))
+          FileUtils.touch(path)
+          puts "Touched #{path} — managed app restarts on next request."
+        end
+
+        # Tail the app log (default 50 lines); --follow streams.
+        def log(ctx, args)
+          follow = args.delete("--follow") || args.delete("-f")
+          lines = (args.first || 50).to_i
+          resolved = Resolver.resolve(Dir.pwd)
+          path = File.expand_path(File.join(Dir.pwd, "log", "ask-local-#{resolved.app}.log"))
+          unless File.file?(path)
+            puts "No log at #{path} yet."
+            return
+          end
+          if follow
+            exec("tail", "-F", "-n", lines.to_s, path)
+          else
+            puts File.readlines(path).last(lines).join
+          end
+        end
+
+        # Print the effective naming context for this directory: what
+        # `ask-local` would boot here and why. Answers "why did I get
+        # this URL" without booting anything. --json emits stable keys
+        # for agents instead of prose.
+        def status(_ctx, args)
+          json = args.delete("--json")
+          resolved = Resolver.resolve(Dir.pwd)
+          hostnames = Resolver.hostnames(resolved)
+          urls = hostnames.map do |h|
+            Hostname.url(h, port: ProxyControl.default_port(true), tls: true)
+          end
+          payload = {
+            app: resolved.app, app_source: resolved.sources[:app],
+            service: resolved.service, service_source: resolved.sources[:service],
+            variant: resolved.variant, variant_source: resolved.sources[:variant],
+            tlds: resolved.tlds, urls: urls,
+            framework: Framework.detect(Dir.pwd).to_s
+          }
+          if json
+            require "json"
+            puts JSON.generate(payload)
+            return
+          end
+          puts "app:       #{payload[:app]} (from #{payload[:app_source]})"
+          puts "service:   #{payload[:service] || "web (default, bare)"} (from #{payload[:service_source] || "default"})"
+          puts "variant:   #{payload[:variant] || "(none)"} (from #{payload[:variant_source] || "no worktree, branch, flag, or env"})"
+          puts "tlds:      #{payload[:tlds].join(", ")}"
+          puts "urls:"
+          urls.each { |u| puts "  #{u}" }
+          puts "framework: #{payload[:framework]}"
+        end
+
+        # Open the app URL in the default browser (macOS `open`).
+        def open(ctx, args)
+          name = args.first
+          url =
+            if name
+              opts = ctx.parse_flags(args[1..] || [], %i[service variant tld])
+              context = Resolver.resolve(Dir.pwd, service: opts[:service],
+                variant: opts[:variant], tlds: opts[:tld], use_branch: false)
+              hostnames = Hostname.build(app: Sanitize.hostname_label(name),
+                service: context.service, variant: context.variant, tlds: context.tlds)
+              Hostname.url(hostnames.first, port: ctx.proxy_port, tls: ctx.proxy_tls)
+            else
+              resolved = Resolver.resolve(Dir.pwd)
+              Hostname.url(Resolver.hostnames(resolved).first,
+                port: ctx.proxy_port, tls: ctx.proxy_tls)
+            end
+          case RUBY_PLATFORM
+          when /darwin/ then exec("open", url)
+          when /linux/ then exec("xdg-open", url)
+          else puts url
+          end
+        end
+      end
+    end
+  end
+end