ask-local 0.1.0 → 0.2.0

data/lib/ask/local/resolver.rb

@@ -2,124 +2,92 @@
 
 module Ask
   module Local
-    # Resolve the effective {app, service, variant, tlds} for a directory.
-    #
-    # Precedence per axis: CLI flag > ENV > ask-local.json > inference.
-    # Variant adds linked-worktree branch and opt-in current branch.
+    # Resolve hostnames from config/local.yml — the ONLY source of truth.
+    # No inference, no Procfile fallback, no ENV for naming. If the file
+    # is missing, resolve raises ConfigError telling the user to run
+    # `ask-local init`.
     module Resolver
       module_function
 
-      Result = Struct.new(:app, :service, :variant, :tlds, :sources, keyword_init: true)
+      Result = Struct.new(:app, :tld, :host, :processes, :secrets,
+        :sources, :variant, keyword_init: true)
 
-      def resolve(dir = Dir.pwd, name: nil, service: nil, variant: nil,
-        tlds: nil, use_branch: false)
-        config, config_dir = find_config(dir)
-        app_cfg = config ? config.app_config(dir) : {}
-        config_source = config_dir ? "ask-local.json (#{relative_label(config_dir, dir)})" : "ask-local.json"
+      def resolve(dir = Dir.pwd, variant: nil, tld: nil, host: nil)
+        config = Config.load(dir, variant: variant)
+        unless config
+          raise ConfigError, Config.missing_message(dir)
+        end
 
-        app, app_source = first_present(
-          [name, "flag"],
-          [ENV["ASK_LOCAL_NAME"], "ASK_LOCAL_NAME"],
-          [app_cfg["name"], config_source],
-          [Inference.infer(dir), :infer]
-        )
-        app, app_source = app_source == :infer ? app : [app, app_source]
+        service = config.service
+        proxy = config.proxy_config
+        processes = config.processes
 
-        service, service_source = first_present(
-          [service, "flag"],
-          [ENV["ASK_LOCAL_SERVICE"], "ASK_LOCAL_SERVICE"],
-          [app_cfg["service"], config_source]
-        )
+        variant_name = (variant || ENV["ASK_LOCAL_VARIANT"])&.strip
+        variant_name = nil if variant_name&.empty?
 
-        variant_value, variant_source = if !variant.nil? || ENV["ASK_LOCAL_VARIANT"] || app_cfg["variant"]
-          first_present(
-            [variant, "flag"],
-            [ENV["ASK_LOCAL_VARIANT"], "ASK_LOCAL_VARIANT"],
-            [app_cfg["variant"], config_source]
-          )
+        # host or tld: config proxy.host wins over proxy.tld; flags override.
+        if host || proxy["host"]
+          effective_host = (host || proxy["host"]).to_s.strip.downcase
+          effective_tld = nil
         else
-          Variant.resolve(dir, use_branch: use_branch) || [nil, nil]
+          effective_tld = (tld || proxy["tld"] || Hostname::DEFAULT_TLD).to_s.strip.downcase
+          effective_tld = effective_tld.gsub(/\A\./, "")
+          unless Sanitize.valid_tld?(effective_tld)
+            raise ConfigError, "Invalid tld #{effective_tld.inspect} in #{config.path} proxy.tld"
+          end
+          effective_host = nil
         end
 
-        tld_list = parse_tlds(tlds) || parse_tlds(ENV["ASK_LOCAL_TLD"]) ||
-          Array(app_cfg["tlds"]) || [Hostname::DEFAULT_TLD]
-        tld_list = [Hostname::DEFAULT_TLD] if tld_list.empty?
-        tld_list.each do |tld|
-          raise ConfigError, "Invalid TLD #{tld.inspect}" unless Sanitize.valid_tld?(tld.downcase)
-        end
-        tld_list = tld_list.map(&:downcase).uniq
+        sources = {
+          app: config.path.to_s,
+          tld: proxy["tld"] ? "#{config.path} proxy.tld" : "default (localhost)",
+          host: proxy["host"] ? "#{config.path} proxy.host" : nil,
+          variant: variant_name ? "config/local.#{variant_name}.yml" : nil
+        }
 
         Result.new(
-          app: Sanitize.hostname_label(app),
-          service: service && Sanitize.hostname_label(service),
-          variant: variant_value && Sanitize.hostname_label(variant_value),
-          tlds: tld_list,
-          sources: { app: app_source, service: service_source, variant: variant_source }
+          app: Sanitize.hostname_label(service),
+          tld: effective_tld,
+          host: effective_host,
+          processes: processes,
+          secrets: config.secrets,
+          sources: sources,
+          variant: variant_name
         )
       end
 
-      def hostnames(result)
-        Hostname.build(app: result.app, service: result.service,
-          variant: result.variant, tlds: result.tlds)
-      end
+      # Hostname for one process: primary (first proxy:true) is bare;
+      # others are proc.app.tld; proxy:false have none.
+      def hostname_for(result, proc_name)
+        entry = result.processes[proc_name]
+        return nil unless entry
+        return nil if entry["proxy"] == false
 
-      # Walk up for the nearest ask-local.json; a root with an "apps" map
-      # covers subdirectories (monorepo). A nearer config without a match
-      # does not block a farther one with an apps entry.
-      def find_config(dir)
-        current = File.expand_path(dir)
-        fallback = nil
-        loop do
-          begin
-            loaded = Config.load(current)
-            if loaded
-              if loaded.data["apps"].is_a?(Hash)
-                return [loaded, current]
-              else
-                fallback ||= [loaded, current]
-              end
-            end
-          rescue ConfigError
-            nil
-          end
-          parent = File.dirname(current)
-          break if parent == current
+        base = result.host ? result.host : "#{result.app}.#{result.tld}"
+        proc_name.to_s == primary_proc(result) ? base : "#{proc_name}.#{base}"
+      end
 
-          current = parent
-        end
-        fallback || [nil, nil]
+      def primary_proc(result)
+        result.processes.find { |_, v| v["proxy"] != false }&.first
       end
 
-      def relative_label(config_dir, dir)
-        return "." if File.expand_path(config_dir) == File.expand_path(dir)
+      # All HTTP hostnames (for route registration / doctor).
+      def hostnames(result)
+        result.processes.filter_map { |name, entry|
+          next if entry["proxy"] == false
 
-        require "pathname"
-        Pathname.new(File.expand_path(dir))
-          .relative_path_from(Pathname.new(File.expand_path(config_dir))).to_s
-      rescue ArgumentError
-        "."
+          hostname_for(result, name)
+        }
       end
 
-      # NOTE: no `private` keyword here — it would cancel
-      # `module_function` mode (see Variant for details).
-      def first_present(*pairs)
-        pairs.each do |value, source|
-          if source == :infer
-            inferred, from = value
-            return [inferred, from] unless inferred.nil? || inferred.to_s.empty?
-          elsif !value.nil? && !value.to_s.strip.empty?
-            return [value.to_s.strip, source]
-          end
-        end
-        [nil, nil]
+      def url_for(result, proc_name, port:, tls:)
+        host = hostname_for(result, proc_name)
+        host && Hostname.url(host, port: port, tls: tls)
       end
 
-      def parse_tlds(value)
-        return nil if value.nil?
-        return value.map(&:to_s) if value.is_a?(Array)
-
-        parts = value.to_s.split(",").map(&:strip).reject(&:empty?)
-        parts.empty? ? nil : parts
+      # Effective URL list for display (status): primary bare, others prefixed.
+      def urls(result, port:, tls:)
+        hostnames(result).map { |h| Hostname.url(h, port: port, tls: tls) }
       end
     end
   end

data/lib/ask/local/runner.rb

@@ -91,9 +91,10 @@ module Ask
       end
 
       # Run an arbitrary command with PORT + ASK_LOCAL_URL. Returns App.
-      def boot_run(name:, hostname:, url:, dir:, command:, port: nil, force: false)
+      def boot_run(name:, hostname:, url:, dir:, command:, port: nil, force: false,
+        rails_dev_host: nil)
         port ||= Ports.find_free
-        env = child_env(dir, url: url, port: port)
+        env = child_env(dir, url: url, port: port, rails_dev_host: rails_dev_host)
         pid = with_clean_env { spawn(env, *command, chdir: dir) }
         Process.detach(pid)
         target = "127.0.0.1:#{port}"
@@ -103,12 +104,16 @@ module Ask
           target: target, kind: "tcp", command: command)
       end
 
-      def child_env(dir, url:, port:)
+      def child_env(dir, url:, port:, rails_dev_host: nil)
         env = { "ASK_LOCAL_URL" => url }
         env["PORT"] = port.to_s if port
         env["HOST"] = "127.0.0.1"
         ca = File.join(Certs.state_dir, "ca.pem")
         env["NODE_EXTRA_CA_CERTS"] = ca if File.file?(ca)
+        # Rails blocks unknown Host headers in development. Allow the
+        # proxied hostname so Rails apps boot behind ask-local with zero
+        # config — this replaces the ask-local-rails hosts patch.
+        env["RAILS_DEVELOPMENT_HOSTS"] = rails_dev_host if rails_dev_host
         env
       end
 

data/lib/ask/local/version.rb

@@ -2,6 +2,6 @@
 
 module Ask
   module Local
-    VERSION = "0.1.0"
+    VERSION = "0.2.0"
   end
 end

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

@@ -1,81 +1,105 @@
 ---
 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.
+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), 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
+## One file, one command
+
+Every app declares `config/local.yml` — the single source of truth:
+
+```yaml
+service: myapp
+proxy:
+  tld: localhost
+processes:
+  web:
+    cmd: bundle exec puma -b tcp://127.0.0.1:$PORT config.ru
+    proxy: true          # gets https://myapp.localhost
+  worker:
+    cmd: bundle exec sidekiq
+    proxy: false         # background, supervised, no URL
+env:
+  clear:
+    RAILS_ENV: development
 ```
 
-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
+If the file is missing, ask-local prints `Run ask-local init`. Generate it
+with `ask-local init` (migrates an existing Procfile). Rails apps need
+no extra gem — the proxied hostname is allowed automatically via
+`RAILS_DEVELOPMENT_HOSTS`.
 
 ```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
+ask-local start          # setup if needed, then boot every process
+ask-local                # same as start
+ask-local stop           # stop this app's backend + routes
+ask-local status         # show service, processes, and URLs
+ask-local log [-f]       # tail the web process 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`.
+`$PORT` and `ASK_LOCAL_URL` are injected per process; HTTP processes get
+stable URLs, background ones are supervised without routes. A process
+that exits cleans up the whole tree.
 
 ## Cross-service wiring
 
 ```bash
 ask-local get backend            # -> https://backend.localhost
+ask-local get backend --variant demo
 ```
 
 Use `get` output for frontend-to-API URLs, Cable URLs, and webhook
 targets. Do not guess ports.
 
-## Variants (worktrees, branches, demos)
+## Variants are files
+
+A variant is a file overlay, Kamal-style: `config/local.<variant>.yml`
+deep-merges over `config/local.yml`. Select it with `ASK_LOCAL_VARIANT`
+or `--variant`. Worktrees get a branch prefix automatically.
+
+```bash
+ASK_LOCAL_VARIANT=fix-ui ask-local    # boots with config/local.fix-ui.yml merged
+```
+
+## First time on a machine
 
-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`.
+Run `ask-local start` — it does the one-shot CA trust, port 443, and
+hosts sync if anything is missing, then boots. Prefer `ask-local setup`
+for workstation setup without booting. If any command fails with a
+privileged-port error, do not work around it with `-p` — run
+`ask-local setup` instead. A `:port` suffix in a URL means someone
+explicitly opted into it.
 
 ## OAuth and webhooks
 
-Build callback URLs from `ASK_LOCAL_URL`:
+Build callback URLs from `ASK_LOCAL_URL` (injected into every HTTP
+process):
 
 ```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:
+domain you own instead — no code change, just config:
 
-```bash
-ask-local --tld local.example.com   # -> https://myapp.local.example.com
+```yaml
+proxy:
+  host: myapp.local.example.com   # instead of tld: localhost
 ```
 
 ## Troubleshooting
 
 ```bash
 ask-local doctor                 # read-only: proxy, routes, DNS, CA trust
-ask-local list                   # active routes
+ask-local list --json            # routes as stable JSON
 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.
+warns about TLS: `ask-local trust`.
 
 ## When NOT to use ask-local
 

data/lib/ask-local.rb

@@ -22,6 +22,7 @@ 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/procfile"
 require_relative "ask/local/cli/boot"
 require_relative "ask/local/cli/routes"
 require_relative "ask/local/cli/system"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ask-local
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Kaka Ruto
@@ -73,6 +73,7 @@ email:
 - kaka@myrrlabs.com
 executables:
 - ask-local
+- askl
 extensions: []
 extra_rdoc_files: []
 files:
@@ -80,6 +81,7 @@ files:
 - LICENSE
 - README.md
 - bin/ask-local
+- bin/askl
 - lib/ask-local.rb
 - lib/ask/local/certs.rb
 - lib/ask/local/cli.rb
@@ -97,6 +99,7 @@ files:
 - lib/ask/local/log.rb
 - lib/ask/local/ownership.rb
 - lib/ask/local/ports.rb
+- lib/ask/local/procfile.rb
 - lib/ask/local/proxy.rb
 - lib/ask/local/proxy_control.rb
 - lib/ask/local/resolver.rb