gemstack-dev 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 29f4e62e1d5a456f9baa82311bd2940b5991b51ecb4e977f2cf20103040f6b43
+  data.tar.gz: 26d9a84c3052e370f59f34d24e4b9e9fec4adcb97c9827c352dc073b8661c107
+SHA512:
+  metadata.gz: 9a67351093cf50e23c12baa5f45445227f764bc0a7ab2463fa5716ff397c240838d840a35979844362eb12c33f721ab67a49daffe81dedd530190268ce355898
+  data.tar.gz: 40eb97dce3d3c0de4e67d1de381c61e0677e625f81f23387e603800aa1764b7a60eee72f08a42f41660a66b199e00ce67401253a20c72b70461276f0a510a1ad

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 0.1.0
+
+First release. See the [GemStack changelog](https://github.com/gemstack-rb/gemstack/blob/main/CHANGELOG.md).

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shoaib Malik
+
+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,24 @@
+# gemstack-dev
+
+GemStack development server: single-origin gateway and process supervisor.
+
+Part of [GemStack](https://github.com/gemstack-rb/gemstack), a modular Ruby API framework for Next.js
+applications. All GemStack gems are developed together in that repository and released with the same
+version.
+
+## Installation
+
+Installed with the `gemstack` gem; you rarely need to add it yourself.
+
+## Documentation
+
+- [Guide](https://github.com/gemstack-rb/gemstack/blob/main/docs/development.md)
+- [All guides](https://github.com/gemstack-rb/gemstack/tree/main/docs) ·
+  [Architecture](https://github.com/gemstack-rb/gemstack/blob/main/ARCHITECTURE.md)
+
+Source, issues and pull requests: [gemstack-rb/gemstack](https://github.com/gemstack-rb/gemstack)
+(this gem lives in `gems/gemstack-dev`).
+
+## License
+
+MIT — see [LICENSE.txt](LICENSE.txt).

data/lib/gemstack/dev/file_watcher.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module GemStack
+  module Dev
+    # Detects changes (edits, additions, deletions) in a set of glob patterns.
+    # Polling keeps it dependency-free and reliable across editors, containers
+    # and network filesystems; it is only used in development.
+    #
+    # Modification times are the cheap first check; a file whose mtime changed
+    # only counts as changed if its content digest changed too. Tools that
+    # rewrite files with identical content — Bundler 4 rewrites Gemfile.lock on
+    # every `bundle exec` — therefore don't trigger reloads or restarts.
+    class FileWatcher
+      Entry = Struct.new(:mtime, :bytes, :digest)
+
+      def initialize(patterns, root: Dir.pwd, exclude: [])
+        @patterns = Array(patterns)
+        @exclude = Array(exclude)
+        @root = root.to_s
+        @entries = scan({})
+      end
+
+      # True once per change: the new state becomes the baseline.
+      def changed?
+        current = scan(@entries)
+        changed = current.keys != @entries.keys ||
+                  current.any? { |path, entry| entry.digest != @entries[path].digest }
+        @entries = current
+        changed
+      end
+
+      def files
+        found = Dir.glob(@patterns, base: @root)
+        found.reject! { |file| @exclude.any? { |pattern| File.fnmatch?(pattern, file, File::FNM_PATHNAME) } }
+        found.sort
+      end
+
+      private
+
+      # Reuses the previous digest when mtime and size are unchanged.
+      def scan(previous)
+        files.each_with_object({}) do |file, entries|
+          path = File.join(@root, file)
+          stat = File.stat(path)
+          next if stat.directory?
+
+          old = previous[file]
+          same = old && old.mtime == stat.mtime && old.bytes == stat.size
+          entries[file] = Entry.new(stat.mtime, stat.size, same ? old.digest : Digest::SHA256.file(path).hexdigest)
+        rescue Errno::ENOENT
+          next
+        end
+      end
+    end
+  end
+end

data/lib/gemstack/dev/gateway.rb

@@ -0,0 +1,220 @@
+# frozen_string_literal: true
+
+require "socket"
+require "json"
+
+module GemStack
+  module Dev
+    # The development gateway: one public origin in front of Next.js and the
+    # Ruby API (DECISIONS D-008).
+    #
+    # For each connection it reads only the request line and headers, picks
+    # an upstream by path (api_path → API, everything else → frontend), adds
+    # X-Forwarded-* headers and then copies raw bytes in both directions.
+    # Because it never interprets bodies, streaming responses, Server-Sent
+    # Events and WebSocket upgrades (Next.js HMR, realtime) just work.
+    #
+    # Each request gets its own upstream connection (`Connection: close`
+    # upstream), so routing stays correct per request without parsing
+    # response framing. That trade-off is fine on localhost and is the reason
+    # this gateway is for development only.
+    class Gateway
+      Upstream = Struct.new(:name, :host, :port, :label) do
+        def to_s = "#{host}:#{port}"
+      end
+
+      MAX_HEAD = 64 * 1024
+      CONNECT_TIMEOUT = 2
+      HOP_BY_HOP = %w[connection keep-alive proxy-connection].freeze
+      FORWARDED = %w[x-forwarded-for x-forwarded-proto x-forwarded-host x-forwarded-port].freeze
+
+      attr_reader :port
+      attr_accessor :api, :frontend
+
+      def initialize(port:, api_path:, api:, frontend: nil, bind: %w[127.0.0.1 ::1], on_error: nil)
+        @port = port
+        @api_path = api_path.to_s.chomp("/")
+        @api = api
+        @frontend = frontend
+        @bind = Array(bind)
+        @on_error = on_error
+        @servers = []
+        @threads = []
+      end
+
+      def start
+        @bind.each do |host|
+          server = listen(host)
+          next unless server
+
+          @port = server.addr[1] if @port.zero? # port 0: let the OS choose (tests)
+          @servers << server
+        end
+        raise Error, "could not listen on any of #{@bind.join(", ")}" if @servers.empty?
+
+        @threads = @servers.map { |server| Thread.new { accept_loop(server) } }
+        self
+      end
+
+      def stop
+        @servers.each { |server| server.close unless server.closed? }
+        @threads.each { |thread| thread.join(1) }
+        @servers.clear
+      end
+
+      def api_request?(path)
+        return true if @api_path.empty?
+
+        path == @api_path || path.start_with?("#{@api_path}/")
+      end
+
+      private
+
+      def listen(host)
+        TCPServer.new(host, @port)
+      rescue Errno::EADDRINUSE
+        stop
+        raise Error,
+              "port #{@port} is already in use on #{host}. Stop the other process or run PORT=#{@port + 1} gemstack dev"
+      rescue Errno::EADDRNOTAVAIL, Errno::EAFNOSUPPORT, SocketError
+        nil # e.g. no IPv6 loopback on this machine
+      end
+
+      def accept_loop(server)
+        loop do
+          client = server.accept
+          Thread.new(client) { |socket| handle(socket) }
+        end
+      rescue IOError, Errno::EBADF, Errno::EINVAL
+        nil # server closed
+      end
+
+      def handle(client)
+        head, rest = read_head(client)
+        return unless head
+
+        request_line, *header_lines = head.split("\r\n")
+        _method, target, = request_line.split(" ", 3)
+        return respond(client, 400, "text/plain", "Bad Request") unless target
+
+        path = target.sub(%r{\Ahttps?://[^/]+}i, "").split("?", 2).first
+        api = api_request?(path)
+        upstream = api ? @api : @frontend
+        return unavailable(client, api, header_lines, nil) unless upstream
+
+        server = connect(upstream)
+        return unavailable(client, api, header_lines, upstream) unless server
+
+        server.write("#{request_line}\r\n#{rewrite(header_lines, client).join("\r\n")}\r\n\r\n")
+        server.write(rest) unless rest.empty?
+        relay(client, server)
+      rescue IOError, SystemCallError
+        nil # client or upstream went away
+      rescue StandardError => e
+        @on_error&.call(e)
+      ensure
+        [client, server].each { |socket| socket&.close unless socket&.closed? }
+      end
+
+      def read_head(client)
+        buffer = String.new(encoding: Encoding::BINARY)
+        until (index = buffer.index("\r\n\r\n"))
+          return nil if buffer.bytesize > MAX_HEAD
+
+          buffer << client.readpartial(16 * 1024)
+        end
+        [buffer.byteslice(0, index), buffer.byteslice(index + 4, buffer.bytesize)]
+      rescue IOError, SystemCallError # EOFError is an IOError
+        nil
+      end
+
+      def rewrite(lines, client)
+        upgrade = upgrade?(lines)
+        host = nil
+        kept = lines.reject do |line|
+          name = line[/\A[^:]+/].to_s.strip.downcase
+          host = line.split(":", 2).last.strip if name == "host"
+          FORWARDED.include?(name) || (!upgrade && HOP_BY_HOP.include?(name))
+        end
+        kept << "Connection: close" unless upgrade
+        kept << "X-Forwarded-For: #{client_ip(client)}"
+        kept << "X-Forwarded-Proto: http"
+        kept << "X-Forwarded-Host: #{host}" if host
+        kept << "X-Forwarded-Port: #{@port}"
+      end
+
+      def upgrade?(lines)
+        connection = lines.find { |l| l.match?(/\Aconnection\s*:/i) }
+        connection&.match?(/upgrade/i) && lines.any? { |l| l.match?(/\Aupgrade\s*:/i) }
+      end
+
+      def client_ip(client)
+        client.remote_address.ip_address
+      rescue StandardError
+        "127.0.0.1"
+      end
+
+      def connect(upstream)
+        Socket.tcp(upstream.host, upstream.port, connect_timeout: CONNECT_TIMEOUT)
+      rescue SystemCallError, SocketError, IOError
+        nil
+      end
+
+      # Upstream → client on this thread; client → upstream on a helper
+      # thread. The exchange ends when the upstream closes (after its
+      # response, or when a WebSocket/stream ends).
+      def relay(client, server)
+        pump = Thread.new do
+          IO.copy_stream(client, server)
+          server.close_write
+        rescue IOError, SystemCallError
+          nil
+        end
+        IO.copy_stream(server, client)
+      rescue IOError, SystemCallError
+        nil
+      ensure
+        pump&.kill
+      end
+
+      def unavailable(client, api, header_lines, upstream)
+        name = api ? "Ruby API" : "Next.js"
+        state = upstream ? "is starting or not running" : "is not configured"
+        message = "#{name} #{state}. Check the terminal running `gemstack dev`."
+        if api
+          body = JSON.generate(error: { code: "upstream_unavailable", message: message })
+          respond(client, 503, "application/json", body)
+        elsif header_lines.any? { |l| l.match?(%r{\Aaccept\s*:.*text/html}i) }
+          respond(client, 503, "text/html; charset=utf-8", waiting_page(name, message, refresh: !upstream.nil?))
+        else
+          respond(client, 503, "text/plain", message)
+        end
+      end
+
+      def respond(client, status, type, body)
+        reason = { 400 => "Bad Request", 503 => "Service Unavailable" }.fetch(status, "Error")
+        client.write("HTTP/1.1 #{status} #{reason}\r\ncontent-type: #{type}\r\ncontent-length: #{body.bytesize}\r\n" \
+                     "cache-control: no-store\r\nretry-after: 1\r\nconnection: close\r\n\r\n#{body}")
+      end
+
+      def waiting_page(name, message, refresh:)
+        <<~HTML
+          <!doctype html>
+          <html lang="en"><head><meta charset="utf-8"><title>GemStack · #{name}</title>
+          #{'<meta http-equiv="refresh" content="1">' if refresh}
+          <meta name="viewport" content="width=device-width, initial-scale=1">
+          <style>
+            body{font:16px/1.5 system-ui,sans-serif;display:grid;place-items:center;min-height:100vh;margin:0;
+                 background:#0b0d12;color:#e6e8ee}
+            main{max-width:32rem;padding:2rem;text-align:center}
+            .dot{display:inline-block;width:.6rem;height:.6rem;border-radius:50%;background:#f5b041;
+                 margin-right:.5rem;animation:p 1s infinite alternate}
+            @keyframes p{to{opacity:.3}} code{background:#1c2030;padding:.1rem .35rem;border-radius:4px}
+          </style></head>
+          <body><main><h1>GemStack</h1><p><span class="dot"></span>#{message.sub(/`([^`]+)`/, '<code>\1</code>')}</p>
+          <p style="color:#8a90a2">#{"This page refreshes automatically." if refresh}</p></main></body></html>
+        HTML
+      end
+    end
+  end
+end

data/lib/gemstack/dev/managed_process.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module GemStack
+  module Dev
+    # A child process whose output is streamed, line by line, to a Terminal.
+    # Each child runs in its own process group so stopping it also stops
+    # anything it spawned (e.g. npm → node).
+    class ManagedProcess
+      attr_reader :name, :command, :pid, :status
+
+      def initialize(name, command, terminal:, env: {}, chdir: Dir.pwd)
+        @name = name
+        @command = Array(command)
+        @terminal = terminal
+        @env = env
+        @chdir = chdir.to_s
+        @pid = nil
+        @status = nil
+      end
+
+      def start
+        reader, writer = IO.pipe
+        @status = nil
+        @pid = Process.spawn(@env, *@command, chdir: @chdir, out: writer, err: writer, in: File::NULL,
+                                              pgroup: true)
+        writer.close
+        @output = Thread.new do
+          reader.each_line { |line| @terminal.line(@name, line) }
+        rescue IOError
+          nil
+        ensure
+          reader.close
+        end
+        self
+      rescue SystemCallError => e
+        writer&.close
+        reader&.close
+        @terminal.line(@name, "could not start `#{@command.join(" ")}`: #{e.message}")
+        @status = :failed_to_start
+        self
+      end
+
+      # Non-blocking. Records the exit status once the process has exited.
+      def running?
+        return false unless @pid
+        return false if @status
+
+        done = Process.waitpid2(@pid, Process::WNOHANG)
+        return true unless done
+
+        @status = done[1]
+        false
+      rescue Errno::ECHILD
+        @status ||= :unknown
+        false
+      end
+
+      def exited? = !@status.nil?
+
+      def stop(timeout: 5)
+        return unless running?
+
+        signal("TERM")
+        deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
+        sleep 0.05 while running? && Process.clock_gettime(Process::CLOCK_MONOTONIC) < deadline
+        signal("KILL") if running?
+        running?
+        @output&.join(1)
+      end
+
+      def restart
+        stop
+        start
+      end
+
+      def describe_status
+        case @status
+        when Process::Status then @status.signaled? ? "signal #{@status.termsig}" : "status #{@status.exitstatus}"
+        else @status.to_s
+        end
+      end
+
+      private
+
+      def signal(name)
+        Process.kill(name, -@pid)
+      rescue Errno::ESRCH, Errno::EPERM
+        begin
+          Process.kill(name, @pid)
+        rescue Errno::ESRCH, Errno::EPERM
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/gemstack/dev/ports.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require "socket"
+
+module GemStack
+  module Dev
+    module Ports
+      module_function
+
+      # An unused TCP port on host, chosen by the OS.
+      def free(host = "127.0.0.1")
+        server = TCPServer.new(host, 0)
+        server.addr[1]
+      ensure
+        server&.close
+      end
+
+      def open?(host, port, timeout: 0.5)
+        Socket.tcp(host, port, connect_timeout: timeout).close
+        true
+      rescue SystemCallError, SocketError, IOError
+        false
+      end
+    end
+  end
+end

data/lib/gemstack/dev/supervisor.rb

@@ -0,0 +1,252 @@
+# frozen_string_literal: true
+
+module GemStack
+  module Dev
+    # Runs `gemstack dev`: the gateway on the public port, the Ruby API and
+    # Next.js on private ports chosen automatically, prefixed output, restarts
+    # of the API when configuration changes, and a clean shutdown on Ctrl-C.
+    class Supervisor
+      LOOPBACK = "127.0.0.1"
+      TICK = 0.25
+
+      attr_reader :gateway, :processes
+
+      def initialize(root:, config: GemStack.config, terminal: Terminal.new, env: ENV)
+        @root = Pathname.new(root)
+        @config = config
+        @dev = config.dev
+        @terminal = terminal
+        @env = env
+        @processes = {}
+        @stopping = false
+      end
+
+      def run
+        prepare_frontend if frontend?
+        start
+        install_signal_handlers
+        loop_until_stopped
+      ensure
+        shutdown
+      end
+
+      def start
+        @started_at = monotonic
+        api_port = Ports.free(LOOPBACK)
+        web_port = Ports.free(LOOPBACK) if frontend?
+        @gateway = Gateway.new(
+          port: @dev.port, bind: @dev.bind, api_path: @config.http.api_path,
+          api: Gateway::Upstream.new(:api, LOOPBACK, api_port, "Ruby API"),
+          frontend: web_port && Gateway::Upstream.new(:next, LOOPBACK, web_port, "Next.js"),
+          on_error: ->(e) { @terminal.line("gateway", "#{e.class}: #{e.message}") }
+        ).start
+
+        start_processes(api_port, web_port)
+        @restart_watcher = FileWatcher.new(@dev.restart_on, root: @root, exclude: @dev.restart_exclude)
+        @recovery_watcher = FileWatcher.new(["app/**/*", "config/**/*", "Gemfile.lock"], root: @root)
+        @jobs_watcher = FileWatcher.new(["app/**/*.rb", "db/migrations/*.rb"], root: @root) if @dev.jobs_command
+        start_jobs if jobs_enabled?
+        if web_port && @dev.contract_command
+          @contract_watcher = FileWatcher.new(@dev.contract_watch, root: @root)
+          @contract_pending = true # generate once at startup
+        end
+        banner
+        watch_readiness
+        self
+      end
+
+      def start_processes(api_port, web_port)
+        @processes[:api] = spawn("api", @dev.api_command, @root, api_env(api_port))
+        @processes[:next] = spawn("next", frontend_command(web_port), frontend_dir, frontend_env(api_port)) if web_port
+      end
+
+      def spawn(name, command, dir, env)
+        ManagedProcess.new(name, command, terminal: @terminal, chdir: dir, env: env).start
+      end
+
+      def stop!
+        @stopping = true
+      end
+
+      def shutdown
+        return if @shut_down
+
+        @shut_down = true
+        @terminal.puts
+        @terminal.line("gemstack", "shutting down…")
+        @processes.values.map { |process| Thread.new { process.stop } }.each(&:join)
+        @gateway&.stop
+      end
+
+      private
+
+      def frontend? = frontend_dir.join("package.json").file?
+      def frontend_dir = @root.join(@dev.frontend_dir)
+
+      def api_env(port)
+        {
+          "GEMSTACK_ENV" => @env.fetch("GEMSTACK_ENV", "development"),
+          "GEMSTACK_API_HOST" => LOOPBACK,
+          "GEMSTACK_API_PORT" => port.to_s,
+          "GEMSTACK_LOG_COLOR" => @terminal.color ? "1" : "0",
+          "PORT" => nil # the public port belongs to the gateway
+        }
+      end
+
+      def frontend_env(api_port)
+        {
+          "GEMSTACK_API_URL" => "http://#{LOOPBACK}:#{api_port}",
+          "NEXT_PUBLIC_GEMSTACK_API_PATH" => @config.http.api_path,
+          "FORCE_COLOR" => @terminal.color ? "1" : nil,
+          "PORT" => nil
+        }
+      end
+
+      def frontend_command(port)
+        return Array(@dev.frontend_command) + ["--port", port.to_s] if @dev.frontend_command
+
+        [frontend_dir.join("node_modules/.bin/next").to_s, "dev", "--hostname", LOOPBACK, "--port", port.to_s]
+      end
+
+      # Installs frontend dependencies on first run so `gemstack new && gemstack dev`
+      # works even with --skip-install.
+      def prepare_frontend
+        return if frontend_dir.join("node_modules/.bin/next").exist?
+
+        manager = package_manager
+        @terminal.line("gemstack", "installing frontend dependencies with #{manager} (first run)…")
+        installer = ManagedProcess.new(manager, [manager, "install"], terminal: @terminal, chdir: frontend_dir).start
+        sleep 0.1 while installer.running?
+        return if installer.status.is_a?(Process::Status) && installer.status.success?
+
+        raise Error, "#{manager} install failed (#{installer.describe_status}) in #{frontend_dir}"
+      end
+
+      def package_manager
+        {
+          "pnpm-lock.yaml" => "pnpm", "yarn.lock" => "yarn", "bun.lockb" => "bun", "bun.lock" => "bun"
+        }.each { |lock, manager| return manager if frontend_dir.join(lock).exist? }
+        "npm"
+      end
+
+      def banner
+        url = "http://localhost:#{@gateway.port}"
+        t = @terminal
+        t.puts
+        t.puts("  #{t.bold("GemStack")} #{t.dim("v#{GemStack::VERSION} · #{@env.fetch("GEMSTACK_ENV",
+                                                                                      "development")}")}")
+        t.puts
+        split = t.dim("(#{@config.http.api_path}/* → Ruby, everything else → Next.js)")
+        t.puts("  #{t.green("✓")} Gateway    #{url}  #{split}")
+        t.puts("  #{t.yellow("…")} Ruby API   #{t.dim("starting on #{@gateway.api} (internal)")}")
+        if @gateway.frontend
+          t.puts("  #{t.yellow("…")} Next.js    #{t.dim("starting on #{@gateway.frontend} (internal)")}")
+        else
+          t.puts("  #{t.dim("-")} Next.js    #{t.dim("no #{@dev.frontend_dir}/package.json — API only")}")
+        end
+        t.puts
+        t.puts("  Application: #{t.bold(url)}")
+        t.puts
+      end
+
+      def watch_readiness
+        [@gateway.api, @gateway.frontend].compact.each do |upstream|
+          Thread.new do
+            until @stopping
+              if Ports.open?(upstream.host, upstream.port)
+                seconds = (monotonic - @started_at).round(1)
+                @terminal.line("gemstack", "#{@terminal.green("✓")} #{upstream.label} ready (#{seconds}s)")
+                break
+              end
+              sleep TICK
+            end
+          end
+        end
+      end
+
+      def install_signal_handlers
+        %w[INT TERM].each { |signal| trap(signal) { @stopping = true } }
+      end
+
+      def loop_until_stopped
+        until @stopping
+          sleep TICK
+          supervise
+        end
+      end
+
+      def supervise
+        api = @processes[:api]
+        if @restart_watcher.changed?
+          restart_api("configuration changed")
+        elsif !api.running? && api.exited?
+          report_exit(api)
+          restart_api("files changed") if @recovery_watcher.changed?
+        end
+        web = @processes[:next]
+        report_exit(web) if web && !web.running? && web.exited?
+        supervise_contract
+        supervise_jobs
+      end
+
+      # A worker only makes sense with the PostgreSQL queue and its table.
+      def jobs_enabled?
+        return false unless @dev.jobs_command && defined?(GemStack::Jobs) && @config.respond_to?(:jobs)
+        return false unless @config.jobs.adapter.to_s == "postgres"
+
+        Dir.glob(@root.join("db/migrations/*_create_gemstack_jobs.rb").to_s).any?
+      end
+
+      def start_jobs
+        @processes[:jobs] = spawn("jobs", @dev.jobs_command, @root, { "GEMSTACK_ENV" => "development" })
+      end
+
+      # The worker doesn't reload code, so restart it when app/ changes
+      # (it finishes running jobs first), and start it once the jobs table exists.
+      def supervise_jobs
+        return unless @jobs_watcher&.changed?
+
+        jobs = @processes[:jobs]
+        if jobs&.running?
+          @terminal.line("gemstack", "app changed — restarting job worker")
+          jobs.restart
+        elsif jobs_enabled?
+          start_jobs
+        end
+      end
+
+      # One contract run at a time; changes during a run queue exactly one more.
+      def supervise_contract
+        return unless @contract_watcher
+
+        @contract_pending = true if @contract_watcher.changed?
+        running = @processes[:contract]&.running?
+        return if running || !@contract_pending
+
+        @contract_pending = false
+        @processes[:contract] = spawn("contract", @dev.contract_command, @root, { "GEMSTACK_ENV" => "development" })
+      end
+
+      # Both watchers overlap (config/), so re-baseline both after a restart
+      # to avoid restarting twice for a single change.
+      def restart_api(reason)
+        @terminal.line("gemstack", "#{reason} — restarting Ruby API")
+        @processes[:api].restart
+        @restart_watcher.changed?
+        @recovery_watcher.changed?
+        @reported_exit = nil
+      end
+
+      def report_exit(process)
+        key = [process.name, process.pid]
+        return if @reported_exit&.include?(key)
+
+        (@reported_exit ||= []) << key
+        hint = process.name == "api" ? " — fix the error; it restarts when you save a file" : ""
+        @terminal.line("gemstack", @terminal.red("#{process.name} exited (#{process.describe_status})#{hint}"))
+      end
+
+      def monotonic = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+  end
+end

data/lib/gemstack/dev/terminal.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module GemStack
+  module Dev
+    # Serialised, prefixed, coloured output for multiple processes:
+    #
+    #   api     │ 12:00:01.120 INFO  GET /api/health status=200 ms=0.4
+    #   next    │ ✓ Compiled / in 812ms
+    class Terminal
+      COLORS = { "api" => 35, "next" => 36, "gateway" => 33, "gemstack" => 32, "jobs" => 34 }.freeze
+      WIDTH = 8
+
+      def initialize(io = $stdout, color: io.respond_to?(:tty?) && io.tty?)
+        @io = io
+        @io.sync = true if @io.respond_to?(:sync=) # output may be a pipe or file
+        @color = color
+        @mutex = Mutex.new
+      end
+
+      attr_reader :color
+
+      def line(name, text)
+        prefix = paint(name.ljust(WIDTH), COLORS.fetch(name, 37))
+        text = text.to_s.chomp
+        @mutex.synchronize { @io.puts("#{prefix}│ #{text}") }
+      end
+
+      def puts(text = "")
+        @mutex.synchronize { @io.puts(text) }
+      end
+
+      def paint(text, code) = @color ? "\e[#{code}m#{text}\e[0m" : text
+      def bold(text) = @color ? "\e[1m#{text}\e[0m" : text
+      def dim(text) = paint(text, 90)
+      def green(text) = paint(text, 32)
+      def red(text) = paint(text, 31)
+      def yellow(text) = paint(text, 33)
+    end
+  end
+end

data/lib/gemstack/dev.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require "gemstack/core"
+
+module GemStack
+  # Development tooling: the single-origin gateway and the process
+  # supervisor behind `gemstack dev` (ARCHITECTURE §5). Nothing here is
+  # loaded in production unless explicitly required.
+  module Dev
+    autoload :FileWatcher, "gemstack/dev/file_watcher"
+    autoload :Gateway, "gemstack/dev/gateway"
+    autoload :ManagedProcess, "gemstack/dev/managed_process"
+    autoload :Ports, "gemstack/dev/ports"
+    autoload :Supervisor, "gemstack/dev/supervisor"
+    autoload :Terminal, "gemstack/dev/terminal"
+
+    class Config < Settings
+      # The single public port.
+      setting :port, default: -> { Integer(ENV.fetch("PORT", 3000)) }
+      # Interfaces the gateway listens on. Both loopback families, because
+      # browsers may resolve "localhost" to either.
+      setting :bind, default: %w[127.0.0.1 ::1]
+      setting :frontend_dir, default: "frontend"
+      setting :api_command, default: %w[bundle exec puma -C config/puma.rb]
+      # nil = run the frontend's own `next` binary in dev mode.
+      setting :frontend_command, default: nil
+      # Changes here restart the Ruby process. app/ and config/routes.rb are
+      # reloaded in-process instead and don't need a restart.
+      setting :restart_on, default: ["config/**/*.rb", "Gemfile.lock", ".env*"]
+      setting :restart_exclude, default: ["config/routes.rb"]
+      # Regenerates TypeScript types/clients when backend code changes
+      # (only when the app has a frontend). nil disables.
+      setting :contract_command, default: %w[bundle exec gemstack contract --quiet]
+      setting :contract_watch, default: ["app/**/*.rb", "config/routes.rb"]
+      # Background job worker, run when the app uses the :postgres job
+      # adapter and has the gemstack_jobs migration. Restarted when app/ changes.
+      setting :jobs_command, default: %w[bundle exec gemstack jobs]
+    end
+  end
+
+  Config.namespace(:dev, Dev::Config)
+end

metadata

@@ -0,0 +1,68 @@
+--- !ruby/object:Gem::Specification
+name: gemstack-dev
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Shoaib Malik
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: gemstack-core
+  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
+email:
+- gemstack26@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/gemstack/dev.rb
+- lib/gemstack/dev/file_watcher.rb
+- lib/gemstack/dev/gateway.rb
+- lib/gemstack/dev/managed_process.rb
+- lib/gemstack/dev/ports.rb
+- lib/gemstack/dev/supervisor.rb
+- lib/gemstack/dev/terminal.rb
+homepage: https://github.com/gemstack-rb/gemstack
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+  source_code_uri: https://github.com/gemstack-rb/gemstack/tree/main/gems/gemstack-dev
+  changelog_uri: https://github.com/gemstack-rb/gemstack/blob/main/gems/gemstack-dev/CHANGELOG.md
+  bug_tracker_uri: https://github.com/gemstack-rb/gemstack/issues
+  documentation_uri: https://github.com/gemstack-rb/gemstack/tree/main/docs
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '4.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.20
+specification_version: 4
+summary: 'GemStack development server: single-origin gateway and process supervisor'
+test_files: []