ask-local 0.1.0 → 0.2.0

data/lib/ask/local/config.rb

@@ -1,60 +1,174 @@
 # frozen_string_literal: true
 
-require "json"
+require "erb"
+require "yaml"
 
 module Ask
   module Local
-    # Optional ask-local.json in the app directory.
+    # Mandatory config/local.yml — the ONLY source of truth for this app.
     #
-    #   { "name": "myapp" }
-    #   { "name": "myapp", "service": "api", "variant": "demo",
-    #     "tlds": ["localhost"], "appPort": 3000 }
+    # Replaces the old optional JSON / inference / Procfile path with a
+    # single file. Kamal patterns borrowed: YAML rendered through ERB,
+    # validated against an example schema with context-pathed errors,
+    # x- extensions ignored, deep overlay for variants (Kamal
+    # destinations), env clear/secret split reading config/local.secrets.
     #
-    # Monorepo roots may add an "apps" map keyed by path relative to the
-    # config dir; top-level fields apply only in single-app mode.
+    # Shape:
+    #
+    #   service: myrr-chat
+    #
+    #   proxy:
+    #     tld: localhost
+    #     # host: myrr-chat.local.example.com
+    #
+    #   processes:
+    #     web:
+    #       cmd: bin/rails server -p $PORT
+    #       proxy: true
+    #       healthcheck: { path: /up, timeout: 30 }
+    #     worker:
+    #       cmd: bin/jobs
+    #       proxy: false
+    #
+    #   env:
+    #     clear:
+    #       RAILS_ENV: development
+    #     secret:
+    #       - RAILS_MASTER_KEY
+    #
+    # Variant overlays: config/local.<variant>.yml deep-merged on top
+    # (like Kamal's deploy.<destination>.yml). The `variant:` key in the
+    # base file is not used — variants are files.
     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
+      FILENAME = "local.yml"
+      RELATIVE_DIR = "config"
+      RELATIVE_PATH = File.join(RELATIVE_DIR, FILENAME)
+      SECRETS_PATH = File.join(RELATIVE_DIR, "local.secrets")
+
+      # Example schema: shapes the validator (types, required keys, array
+      # element types). Unknown keys raise with the context path; keys
+      # starting with "x-" are extensions and ignored (Kamal convention).
+      EXAMPLE = {
+        "service" => "myapp",
+        "proxy" => {
+          "tld" => "localhost",
+          "host" => "myapp.local.example.com"
+        },
+        "processes" => {
+          "web" => {
+            "cmd" => "bin/rails server -p $PORT",
+            "proxy" => true,
+            "healthcheck" => { "path" => "/up", "timeout" => 30 }
+          }
+        },
+        "env" => {
+          "clear" => { "RAILS_ENV" => "development" },
+          "secret" => ["RAILS_MASTER_KEY"]
+        }
+      }.freeze
+
+      REQUIRED_TOP = %w[service].freeze
+
+      attr_reader :data, :dir, :path
+
+      # Load config/local.yml for the app rooted at dir (walks up for the
+      # nearest config/local.yml, so running from a subdirectory works).
+      # Raises ConfigError when missing (mandatory) or invalid. The variant
+      # overlay (config/local.<variant>.yml) is deep-merged on top when
+      # ASK_LOCAL_VARIANT or the explicit variant arg is set.
+      def self.load(dir = Dir.pwd, variant: nil, overlay: nil)
+        variant ||= ENV["ASK_LOCAL_VARIANT"]
+        overlay ||= ENV["ASK_LOCAL_OVERLAY"]
+        root, config_path = find_root(dir)
+        unless root
+          return nil
+        end
+
+        data = load_yaml(config_path)
+        if variant && !variant.to_s.strip.empty?
+          overlay_path = File.join(root, RELATIVE_DIR, "local.#{variant.strip}.yml")
+          if File.file?(overlay_path)
+            overlay_data = load_yaml(overlay_path)
+            data = deep_merge(data, overlay_data)
+          end
+        end
+        if overlay && File.file?(overlay)
+          overlay_data = load_yaml(overlay)
+          data = deep_merge(data, overlay_data)
+        end
 
-      attr_reader :data, :dir
+        new(data, root, config_path)
+      end
 
-      def self.load(dir = Dir.pwd)
-        path = File.join(dir, FILENAME)
-        return nil unless File.file?(path)
+      def self.load_yaml(path)
+        template = File.read(path)
+        rendered = ERB.new(template, trim_mode: "-").result
+        return {} if rendered.strip.empty?
 
-        parsed = JSON.parse(File.read(path))
-        raise ConfigError, "#{path} must be a JSON object" unless parsed.is_a?(Hash)
+        parsed = YAML.safe_load(rendered, aliases: true)
+        raise ConfigError, "#{path} must be a YAML mapping" unless parsed.is_a?(Hash)
 
-        new(parsed, dir, path)
-      rescue JSON::ParserError => e
-        raise ConfigError, "Invalid JSON in #{path}: #{e.message}"
+        parsed
+      rescue Psych::SyntaxError => e
+        raise ConfigError, "Invalid YAML in #{path}: #{e.message}"
       end
 
-      def initialize(data, dir, path = FILENAME)
+      def self.find_root(dir)
+        current = File.expand_path(dir)
+        loop do
+          candidate = File.join(current, RELATIVE_PATH)
+          return [current, candidate] if File.file?(candidate)
+
+          parent = File.dirname(current)
+          break if parent == current
+
+          current = parent
+        end
+        nil
+      end
+
+      def self.missing_message(dir)
+        "No #{RELATIVE_PATH} found from #{dir}. Run `ask-local init`."
+      end
+
+      def self.deep_merge(base, overlay)
+        base.merge(overlay) do |_, base_val, overlay_val|
+          if base_val.is_a?(Hash) && overlay_val.is_a?(Hash)
+            deep_merge(base_val, overlay_val)
+          else
+            overlay_val
+          end
+        end
+      end
+
+      def initialize(data, dir, path)
         @data = data
         @dir = dir
         @path = path
         validate!
       end
 
-      def app_config(package_dir = dir)
-        return slice(APP_KEYS) unless data["apps"].is_a?(Hash)
+      def service
+        data["service"].to_s
+      end
 
-        rel = relative(package_dir)
-        return {} if rel.nil? || rel.start_with?("..")
+      def proxy_config
+        data["proxy"] || {}
+      end
 
-        candidate = rel
-        loop do
-          hit = data["apps"][candidate]
-          return hit.select { |k, _| APP_KEYS.include?(k) } if hit.is_a?(Hash)
+      def processes
+        data["processes"] || {}
+      end
 
-          parent = File.dirname(candidate)
-          break if parent == "." || parent == candidate
+      def env_config
+        data["env"] || {}
+      end
 
-          candidate = parent
-        end
-        {}
+      # Secrets read from config/local.secrets (dotenv), gitignored.
+      # Only needed when env.secret lists keys; missing file is not an
+      # error until a listed secret is referenced.
+      def secrets
+        @secrets ||= load_secrets
       end
 
       def [](key)
@@ -63,49 +177,218 @@ module Ask
 
       private
 
-      def slice(keys)
-        data.select { |k, _| keys.include?(k) }
+      def load_secrets
+        secrets_file = File.join(dir, SECRETS_PATH)
+        return {} unless File.file?(secrets_file)
+
+        parse_dotenv(File.read(secrets_file))
+      rescue SystemCallError
+        {}
+      end
+
+      def parse_dotenv(content)
+        result = {}
+        content.each_line do |line|
+          line = line.strip
+          next if line.empty? || line.start_with?("#")
+
+          if line.match(/\A([A-Za-z_][A-Za-z0-9_]*)=(.*)\z/)
+            result[Regexp.last_match(1)] = Regexp.last_match(2).strip.gsub(/\A["']|["']\z/, "")
+          end
+        end
+        result
       end
 
-      def relative(package_dir)
+      def app_config(package_dir = dir)
+        # Monorepo: walk up looking for config/local.yml with apps map.
+        # Falls back to top-level fields for non-monorepo usage.
+        return data unless data["apps"].is_a?(Hash)
         require "pathname"
-        Pathname.new(File.expand_path(package_dir))
-          .relative_path_from(Pathname.new(File.expand_path(dir))).to_s
-      rescue ArgumentError
-        nil
+        rel = begin
+          Pathname.new(File.expand_path(package_dir))
+            .relative_path_from(Pathname.new(File.expand_path(dir))).to_s
+        rescue ArgumentError
+          nil
+        end
+        return data unless rel
+        candidate = rel
+        loop do
+          entry = data["apps"][candidate]
+          return entry if entry.is_a?(Hash)
+          parent = File.dirname(candidate)
+          break if parent == "." || parent == candidate
+          candidate = parent
+        end
+        data
       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)
+        # Unknown top-level keys (outside example + x- extensions).
+        unknown = data.keys.map(&:to_s) - EXAMPLE.keys.map(&:to_s)
+        unknown.reject! { |k| k.start_with?("x-") }
+        unless unknown.empty?
+          raise ConfigError, "Unknown key(s) #{unknown.map(&:inspect).join(", ")} in #{@path}"
+        end
+        REQUIRED_TOP.each do |key|
+          raise ConfigError, %("#{key}" is required in #{@path}) if data[key].nil? || data[key].to_s.strip.empty?
+        end
+
+        Validator.new(data, EXAMPLE, context: @path).validate!
+
+        validate_service(data["service"], @path)
+        if data["proxy"]
+          validate_proxy(data["proxy"], "#{@path} proxy")
+        end
+        if data["processes"]
+          validate_processes(data["processes"], "#{@path} processes")
+        end
+        if data["env"]
+          validate_env(data["env"], "#{@path} env")
+        end
+      end
+
+      def validate_service(value, context)
+        unless value.is_a?(String) && !value.strip.empty?
+          raise ConfigError, "#{context}: service must be a non-empty string"
         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)
+      end
 
-          data["apps"].each do |name, entry|
-            raise ConfigError, %("apps.#{name}" in #{@path} must be an object) unless entry.is_a?(Hash)
+      def validate_proxy(value, context)
+        raise ConfigError, "#{context} must be a mapping" unless value.is_a?(Hash)
+
+        if value["host"] && !value["host"].is_a?(String)
+          raise ConfigError, "#{context}: host must be a string"
+        end
+        if value["tld"] && !value["tld"].is_a?(String)
+          raise ConfigError, "#{context}: tld must be a string"
+        end
+        if value.key?("host") && value.key?("tld")
+          raise ConfigError, "#{context}: specify one of host or tld, not both"
+        end
+        if value["tld"] && !Sanitize.valid_tld?(value["tld"].downcase)
+          raise ConfigError, "#{context}: invalid tld #{value["tld"].inspect}"
+        end
+      end
+
+      def validate_processes(value, context)
+        raise ConfigError, "#{context} must be a mapping" unless value.is_a?(Hash)
+        raise ConfigError, "#{context} must list at least one process" if value.empty?
+
+        value.each do |name, entry|
+          raise ConfigError, %("#{context}/#{name}" must be a mapping) unless entry.is_a?(Hash)
+
+          if entry["cmd"].nil? || entry["cmd"].to_s.strip.empty?
+            raise ConfigError, %("#{context}/#{name}" requires a non-empty cmd)
+          end
+          if entry.key?("proxy") && ![true, false].include?(entry["proxy"])
+            raise ConfigError, %("#{context}/#{name} proxy must be a boolean")
+          end
+          if entry["healthcheck"]
+            hc = entry["healthcheck"]
+            raise ConfigError, %("#{context}/#{name} healthcheck must be a mapping) unless hc.is_a?(Hash)
 
-            validate_app_fields(entry, "apps.#{name}")
+            if hc.key?("path") && !hc["path"].is_a?(String)
+              raise ConfigError, %("#{context}/#{name} healthcheck path must be a string)
+            end
+            if hc.key?("timeout") && !hc["timeout"].is_a?(Integer)
+              raise ConfigError, %("#{context}/#{name} healthcheck timeout must be an integer)
+            end
           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)
+      def validate_env(value, context)
+        raise ConfigError, "#{context} must be a mapping" unless value.is_a?(Hash)
+
+        if value["clear"] && !value["clear"].is_a?(Hash)
+          raise ConfigError, "#{context} clear must be a mapping"
+        end
+        if value["secret"] && !value["secret"].is_a?(Array)
+          raise ConfigError, "#{context} secret must be an array of strings"
         end
-        if fields.key?("proxy") && ![true, false].include?(fields["proxy"])
-          raise ConfigError, %("#{prefix}.proxy" in #{@path} must be a boolean)
+        if value["secret"] && !value["secret"].all? { |k| k.is_a?(String) }
+          raise ConfigError, "#{context} secret keys must be strings"
         end
-        %w[name service variant].each do |key|
-          next unless fields.key?(key)
-          next if fields[key].is_a?(String) && !fields[key].strip.empty?
+      end
 
-          raise ConfigError, %("#{prefix}.#{key}" in #{@path} must be a non-empty string)
+      # Generic schema validator with context-pathed errors (Kamal
+      # Validator pattern): walks the example shape, type-checks each
+      # present key, and reports the path where the mismatch was found.
+      class Validator
+        def initialize(config, example, context:)
+          @config = config
+          @example = example
+          @context = context
+          @stack = []
         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)
+
+        def validate!
+          validate_against_example!(@config, @example)
+        end
+
+        private
+
+        def validate_against_example!(config, example)
+          return unless example.is_a?(Hash) && config.is_a?(Hash)
+
+          # Only validate keys the config actually has; absent example
+          # keys are optional (Kamal ignores missing optional keys).
+          config.each do |key, value|
+            next if key.to_s.start_with?("x-")
+
+            with_context(key) do
+              example_value = example[key] || example[key.to_s]
+              next if example_value.nil? && !example.key?(key.to_s) && !example.key?(key)
+
+              validate_value!(value, example_value)
+            end
+          end
+        end
+
+        def validate_value!(value, example_value)
+          return if example_value == "..."
+
+          if example_value.is_a?(Hash) && value.is_a?(Hash)
+            validate_against_example!(value, example_value)
+          elsif example_value.is_a?(Array) && value.is_a?(Array)
+            validate_array_of!(value, example_value.first.class) unless example_value.empty?
+          elsif !example_value.nil?
+            expected = type_description(example_value.class)
+            unless value.is_a?(example_value.class) || (example_value.is_a?(String) && value.is_a?(String))
+              raise ConfigError, "#{current_context}: expected #{expected}, got #{value.class.name.downcase}"
+            end
+          end
+        end
+
+        def validate_array_of!(array, type)
+          array.each_with_index do |value, index|
+            with_context(index) do
+              unless value.is_a?(type)
+                raise ConfigError, "#{current_context}: expected #{type.name.downcase}, got #{value.class.name.downcase}"
+              end
+            end
+          end
+        end
+
+        def type_description(type)
+          if type == Integer || type == Array
+            "an #{type.name.downcase}"
+          elsif type == TrueClass || type == FalseClass
+            "a boolean"
+          else
+            "a #{type.name.downcase}"
+          end
+        end
+
+        def with_context(part)
+          @stack.push(part)
+          yield
+        ensure
+          @stack.pop
+        end
+
+        def current_context
+          ([@context] + @stack.map(&:to_s)).join("/")
         end
       end
     end

data/lib/ask/local/procfile.rb

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

data/lib/ask/local/proxy_control.rb

@@ -64,30 +64,51 @@ module Ask
       # where only one family answers the check must still succeed.
       # An explicit regression test pins this (health_test pinning
       # ensure_proxy's "is that ours" logic against future proxy changes).
+      #
+      # Probe order matters: plain HTTP first (our proxy byte-peeks and
+      # answers plain HTTP even on the TLS port), TLS second. A TLS-first
+      # handshake against a foreign plain-HTTP server blocks in connect
+      # waiting for a ServerHello that never comes — and connect used to
+      # sit outside the timeout, hanging ensure_proxy for over a minute.
+      #
+      # Speed: if the plain probe gets ANY HTTP response without our
+      # header, the server is definitively foreign — no TLS retry. The
+      # slow TLS retry only happens when plain yielded zero bytes
+      # (connection error, EOF, or timeout against a silent server).
       def ours?(port, tls:)
-        probe_ours(port, tls: tls, host: "127.0.0.1") ||
-          probe_ours(port, tls: tls, host: "::1")
+        ["127.0.0.1", "::1"].any? do |host|
+          case probe_once(port, tls: false, host: host)
+          when :ours then true
+          when :foreign then false
+          else tls ? probe_once(port, tls: true, host: host) == :ours : false
+          end
+        end
       end
 
-      def probe_ours(port, tls:, host:)
-        sock = TCPSocket.new(host, port)
-        if tls
-          ctx = OpenSSL::SSL::SSLContext.new
-          ctx.verify_mode = OpenSSL::SSL::VERIFY_NONE
-          sock = OpenSSL::SSL::SSLSocket.new(sock, ctx)
-          sock.connect
-        end
-        Timeout.timeout(3) do
+      # Three outcomes: :ours (our header present), :foreign (an HTTP
+      # response without it), :unknown (no response at all).
+      def probe_once(port, tls:, host:)
+        sock = nil
+        Timeout.timeout(5) do
+          sock = TCPSocket.new(host, port)
+          if tls
+            ctx = OpenSSL::SSL::SSLContext.new
+            ctx.verify_mode = OpenSSL::SSL::VERIFY_NONE
+            sock = OpenSSL::SSL::SSLSocket.new(sock, ctx)
+            sock.connect
+          end
           sock.write("GET / HTTP/1.1\r\nHost: ask-local-health.invalid\r\nConnection: close\r\n\r\n")
           head = +""
           while (chunk = sock.readpartial(4096))
             head << chunk
             break if head.include?("\r\n\r\n")
           end
-          head.downcase.include?("x-ask-local: 1")
+          return :unknown if head.empty?
+
+          return head.downcase.include?("x-ask-local: 1") ? :ours : :foreign
         end
       rescue SystemCallError, OpenSSL::SSL::SSLError, Timeout::Error, IOError, EOFError
-        false
+        :unknown
       ensure
         begin
           sock&.close
@@ -96,6 +117,10 @@ module Ask
         end
       end
 
+      def probe_ours(port, tls:, host:)
+        probe_once(port, tls: tls, host: host) == :ours
+      end
+
       def pid_alive?(pid)
         Process.kill(0, pid)
         true