ask-local-rails 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6d9458eaa4ba6e80881586689b17a54398f3aa17a04b47d4ef0985eb5713129b
+  data.tar.gz: 71db3c0e17c54220ba5229404d94472b673f389576942eeade4c365da5477d28
+SHA512:
+  metadata.gz: 74ff28edb6caeb714ccfccb0c77970bbd22f9a4736f0cfc422a3ec29c63a611c6390cfdbf6d00cd02e588ff74d45bbe1a61f87f3140d006f69cae5f6b85c1e9d
+  data.tar.gz: 94b9d2cde3ab259e4f2dcaf6d38a55ff07ce4e83d88fe91884b37a45ba28b78615d912e3b3dce498aa301491b8969e06e55932be9967cdefc4f96ac0b5548d2a

data/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+## [0.1.0] — Unreleased
+
+### Added
+
+- Initial release: Railtie (host-authorization warning in development),
+  `ask_local:install` generator (hosts, Cable origins, Procfile `$PORT`
+  rewrite, initializer, `ask-local.json`), `Ask::Local::Rails` helpers
+  (`url`, `host`, `proxied?`, `host_patterns`, `cable_origins`), and the
+  `local_dev` agent skill.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kaka Ruto
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,54 @@
+# ask-local-rails
+
+[![Gem Version](https://badge.fury.io/rb/ask-local-rails.svg)](https://badge.fury.io/rb/ask-local-rails)
+
+Rails integration for [ask-local](https://github.com/ask-rb/ask-local).
+Railtie, install generator, and helpers wiring a Rails app into stable
+`https://<app>.localhost` URLs. Requires Rails 7.1+.
+
+## Installation
+
+```ruby
+gem "ask-local-rails"
+```
+
+```bash
+bundle install
+rails generate ask_local:install
+```
+
+The generator:
+
+- creates `config/initializers/ask_local.rb`
+- allows `.localhost` hosts + Cable origins in `development.rb`
+- rewrites hardcoded `-p 3000` to `-p $PORT` in `Procfile.dev`/`Procfile`
+  (compound lines it cannot classify are left alone with a warning)
+- creates an empty `ask-local.json` if missing
+
+## Helpers
+
+```ruby
+Ask::Local::Rails.url    # => "https://fix-ui.myapp.localhost" (or fallback)
+Ask::Local::Rails.host   # => "fix-ui.myapp.localhost"
+Ask::Local::Rails.proxied?  # => true when booted through ask-local
+```
+
+Use `url` for mailer hosts, OmniAuth callbacks, and webhook targets —
+never hardcode `localhost:3000`.
+
+## Agent skill
+
+Ships `local_dev` under `ask/skills/` (auto-discovered by ask-skills):
+boot via `ask-local`, wire via `ask-local get`, callbacks from
+`ASK_LOCAL_URL`, `doctor`/`list`/`prune` for troubleshooting.
+
+## Development
+
+```bash
+bundle install
+bundle exec rake test
+```
+
+## License
+
+MIT

data/lib/ask/local/rails/helpers.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Ask
+  module Local
+    # Helpers for app code that needs the stable local URL.
+    # Never hardcode localhost:3000 — read the injected env instead.
+    module Rails
+      module_function
+
+      # Full public URL, e.g. https://fix-ui.myapp.localhost
+      def url(fallback: "http://localhost:3000")
+        ENV["ASK_LOCAL_URL"] || fallback
+      end
+
+      # Bare hostname, e.g. fix-ui.myapp.localhost
+      def host(fallback: "localhost")
+        url(fallback: nil)&.sub(%r{\Ahttps?://}, "")&.split(":")&.first || fallback
+      end
+
+      # False outside ask-local (plain `rails s`).
+      def proxied?
+        !ENV["ASK_LOCAL_URL"].nil? && !ENV["ASK_LOCAL_URL"].empty?
+      end
+
+      # Host authorization patterns for config.hosts in development.
+      # TLDs default to ASK_LOCAL_TLD (comma separated) or "localhost",
+      # so custom-TLD setups work without regenerating config.
+      def host_patterns(tlds: nil)
+        tld_list(tlds).flat_map do |tld|
+          [/\A.+\.#{Regexp.escape(tld)}\z/, /\A#{Regexp.escape(tld)}\z/]
+        end
+      end
+
+      # Action Cable origin patterns for development.
+      def cable_origins(tlds: nil)
+        tld_list(tlds).map { |tld| %r{\Ahttps?://.+\.#{Regexp.escape(tld)}(:\d+)?\z} }
+      end
+
+      def tld_list(tlds)
+        list = tlds || ENV["ASK_LOCAL_TLD"]&.split(",")&.map(&:strip)
+        list = list.to_a.reject(&:nil?).map(&:to_s).reject(&:empty?)
+        list.empty? ? ["localhost"] : list.map(&:downcase).uniq
+      end
+    end
+  end
+end

data/lib/ask/local/rails/procfile_rewrite.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Ask
+  module Local
+    module Rails
+      # Rewrites hardcoded ports in Procfile lines to -p $PORT so the
+      # ask-local runner's injected PORT wins. Pure file logic, no Rails
+      # dependency, so it is unit-testable without a Rails app context.
+      module ProcfileRewrite
+        COMPOUND = /&&|\|\||[|;]/.freeze
+        HARDCODED_PORT = /(?:-p|--port)[=\s]+\d+/.freeze
+
+        module_function
+
+        # Returns true when the file changed. Yields (status, message)
+        # pairs for say_status. Compound lines it cannot classify are
+        # left alone with a warning — the portless lesson: never
+        # silently rewrite what you cannot parse.
+        def rewrite(path)
+          lines = File.readlines(path, chomp: true)
+          changed = false
+          skipped = []
+          updated = lines.map do |line|
+            stripped = line.strip
+            if stripped.empty? || stripped.start_with?("#") || !stripped.include?(":")
+              line
+            elsif stripped.match?(COMPOUND)
+              skipped << line
+              line
+            else
+              rewritten = line.gsub(HARDCODED_PORT, '-p $PORT')
+              changed ||= (rewritten != line)
+              rewritten
+            end
+          end
+          File.write(path, "#{updated.join("\n")}\n") if changed
+          if block_given?
+            skipped.each { |l| yield(:skip, "#{path}: compound line left alone: #{l.strip}") }
+            yield(:rewrite, path) if changed
+          end
+          changed
+        rescue SystemCallError
+          false
+        end
+      end
+    end
+  end
+end

data/lib/ask/local/rails/railtie.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Ask
+  module Local
+    module Rails
+      class Railtie < ::Rails::Railtie
+        # Warn at boot when Host Authorization would reject the .localhost
+        # origin the proxy serves. The generator normally adds the patterns;
+        # this catches apps that skipped it or run custom TLDs.
+        initializer "ask_local_rails.hosts" do |app|
+          next unless ::Rails.env.development?
+          next unless Ask::Local::Rails.proxied?
+
+          host = Ask::Local::Rails.host
+          begin
+            authorized = app.config.hosts.any? do |pattern|
+              pattern.is_a?(Regexp) ? host.match?(pattern) : pattern == host
+            end
+            unless authorized
+              ::Rails.logger&.warn(
+                "[ask-local] Host #{host} is not in config.hosts. " \
+                "Run: rails generate ask_local:install"
+              )
+            end
+          rescue StandardError
+            nil
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ask/local/rails/version.rb

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

data/lib/ask-local-rails.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require_relative "ask/local/rails/version"
+require_relative "ask/local/rails/helpers"
+require_relative "ask/local/rails/procfile_rewrite"
+require_relative "ask/local/rails/railtie" if defined?(::Rails::Railtie)
+
+module Ask
+  module Local
+    module Rails
+    end
+  end
+end

data/lib/generators/ask_local/install/install_generator.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module AskLocal
+  module Generators
+    class InstallGenerator < ::Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Wires a Rails app into ask-local: hosts, Cable origins, Procfile $PORT, initializer"
+
+      class_option :tld, type: :string, default: "localhost",
+        desc: "TLD ask-local serves this app under"
+
+      def create_initializer
+        template "initializer.rb", "config/initializers/ask_local.rb"
+      end
+
+      def patch_development_hosts
+        tld = options[:tld]
+        sentinel = "Ask::Local::Rails.host_patterns"
+        path = app_path("config/environments/development.rb")
+        return unless File.file?(path)
+
+        content = File.read(path)
+        return if content.include?(sentinel)
+
+        inject_into_file path,
+          "\n  # ask-local: allow stable .#{tld} URLs (https://<app>.#{tld}).\n" \
+          "  config.hosts.concat(Ask::Local::Rails.host_patterns(tlds: [#{tld.dump}]))\n",
+          after: "Rails.application.configure do\n"
+      end
+
+      def patch_action_cable
+        tld = options[:tld]
+        sentinel = "Ask::Local::Rails.cable_origins"
+        path = app_path("config/environments/development.rb")
+        return unless File.file?(path)
+
+        content = File.read(path)
+        return if content.include?(sentinel)
+
+        inject_into_file path,
+          "\n  # ask-local: allow Action Cable connections from .#{tld} origins.\n" \
+          "  config.action_cable.allowed_request_origins ||= []\n" \
+          "  config.action_cable.allowed_request_origins.concat(Ask::Local::Rails.cable_origins(tlds: [#{tld.dump}]))\n",
+          after: "Rails.application.configure do\n"
+      end
+
+      def rewrite_procfile_ports
+        %w[Procfile.dev Procfile].each do |file|
+          path = app_path(file)
+          next unless File.file?(path)
+
+          Ask::Local::Rails::ProcfileRewrite.rewrite(path) do |status, message|
+            say_status status, message, status == :rewrite ? :green : :yellow
+          end
+        end
+      end
+
+      def create_ask_local_config
+        return if File.file?(app_path("ask-local.json"))
+
+        create_file "ask-local.json", "{}\n"
+      end
+
+      private
+
+      # Generators may run with a destination_root different from the
+      # process cwd (test harnesses, custom destinations) — resolve file
+      # checks against destination_root, which is the app root in real
+      # Rails usage.
+      def app_path(relative)
+        File.expand_path(relative, destination_root)
+      end
+    end
+  end
+end

data/lib/generators/ask_local/install/templates/initializer.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+# ask-local integration for this Rails app.
+#
+# When booted through ask-local, the runner injects ASK_LOCAL_URL
+# (e.g. https://fix-ui.myapp.localhost). Use Ask::Local::Rails.url
+# anywhere the app must know its own address instead of hardcoding
+# localhost:3000:
+#
+#   # config/environments/development.rb
+#   config.action_mailer.default_url_options = {
+#     host: Ask::Local::Rails.host
+#   }
+#
+# Nothing to configure here — this file documents the integration.
+# See Ask::Local::Rails.host_patterns / .cable_origins for the entries
+# the install generator added to config/environments/development.rb.
+#
+# --- Asset dev servers (Vite-Ruby / Shakapacker) --------------------------
+# Run the dev server through ask-local as its own service and let Rails
+# assets point at it, avoiding mixed-content and cert juggling:
+#
+#   ask-local --service webpack -- bin/shakapacker-dev-server
+#     -> https://webpack.<app>.localhost
+#
+#   # config/environments/development.rb
+#   config.action_controller.asset_host =
+#     proc { |src| "//webpack.#{Ask::Local::Rails.host}" if src.start_with?("/packs") }
+#
+#   # config/shakapacker.yml (or vite.json): set dev_server.public to
+#   # webpack.<app>.localhost and https: false — the proxy terminates TLS.

metadata

@@ -0,0 +1,125 @@
+--- !ruby/object:Gem::Specification
+name: ask-local-rails
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Kaka Ruto
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+- !ruby/object:Gem::Dependency
+  name: ask-local
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.25'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.25'
+- !ruby/object:Gem::Dependency
+  name: mocha
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+description: 'Railtie, install generator, and helpers wiring a Rails app into ask-local''s
+  stable .localhost URLs: host authorization, Action Cable origins, Procfile $PORT
+  rewrite, and an agent skill for local development.'
+email:
+- kaka@myrrlabs.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/ask-local-rails.rb
+- lib/ask/local/rails/helpers.rb
+- lib/ask/local/rails/procfile_rewrite.rb
+- lib/ask/local/rails/railtie.rb
+- lib/ask/local/rails/version.rb
+- lib/generators/ask_local/install/install_generator.rb
+- lib/generators/ask_local/install/templates/initializer.rb
+homepage: https://github.com/ask-rb/ask-local-rails
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/ask-rb/ask-local-rails
+  source_code_uri: https://github.com/ask-rb/ask-local-rails
+  changelog_uri: https://github.com/ask-rb/ask-local-rails/blob/master/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.18
+specification_version: 4
+summary: Rails integration for ask-local
+test_files: []