gemstack-dev 0.2.4 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 412fcd1d46c05fd57427b4efabff65f5f318fde7de647b82cbcb34295537a21f
-  data.tar.gz: 3afd4a5159ce7d0f96b477504ca76eb114f794193d310d56100fbc455e153494
+  metadata.gz: fb88e004507f1d705767b95ed2c9ebd5f3359d222671380c7cf9a06699ad1f20
+  data.tar.gz: a23d9b91475eec43af979ebc888bd0973d04799cd93b5883f1bc9295684387d5
 SHA512:
-  metadata.gz: e5db3bda12111495f8b65df58ae790d407b3f53c2cf354add665751a7425b165ff9a0fb463e67c084082fbcc06c423a82fe04537a98d8383e56cf652e7d1b002
-  data.tar.gz: fd412202bbbde52eaafaeddf41865c33871ac93e72eefed74127c75ade41ed4b617c4c8d998b17d0d0bedb8def459ef9461507139076d71c5d8c68b00c62d843
+  metadata.gz: a1b7a5c31396f6261abe9359dd98d72acddcd322307ee53094ef118daa9c56334e5b43c61b5bff142a8f5fc0b7c895dcf542571dc36a173be131e4cdd43ea1b9
+  data.tar.gz: ab411641ae5b0c8b8e511ecab3820b3697c4fa95388af55fb94b5009b1fa76017da63cd99a92c80b962caca294d511e99aba7cdbf6b72b2ca8f70c742316f07c

data/CHANGELOG.md

@@ -1,25 +1,5 @@
 # Changelog
 
-## 0.2.4
+## 0.3.0
 
-See the [GemStack changelog](https://github.com/gemstack-rb/gemstack/blob/main/CHANGELOG.md).
-
-## 0.2.3
-
-See the [GemStack changelog](https://github.com/gemstack-rb/gemstack/blob/main/CHANGELOG.md).
-
-## 0.2.2
-
-See the [GemStack changelog](https://github.com/gemstack-rb/gemstack/blob/main/CHANGELOG.md).
-
-## 0.2.1
-
-See the [GemStack changelog](https://github.com/gemstack-rb/gemstack/blob/main/CHANGELOG.md).
-
-## 0.2.0
-
-See the [GemStack changelog](https://github.com/gemstack-rb/gemstack/blob/main/CHANGELOG.md).
-
-## 0.1.0
-
-First release. See the [GemStack changelog](https://github.com/gemstack-rb/gemstack/blob/main/CHANGELOG.md).
+Merged into the gemstack gem; this version is a transition shim. See the [GemStack changelog](https://github.com/gemstack-rb/gemstack/blob/main/CHANGELOG.md).

data/README.md

@@ -1,23 +1,13 @@
 # gemstack-dev
 
-GemStack development server: single-origin gateway and process supervisor.
+**Merged into [`gemstack`](https://rubygems.org/gems/gemstack) in GemStack 0.3.0.**
 
-Part of [GemStack](https://github.com/gemstack-rb/gemstack), a modular Ruby API framework for Next.js
-applications by [Adware Technologies](https://www.adwaretech.com). All GemStack gems are developed together in that repository and released with the same
-version.
+This version is a transition shim: it depends on `gemstack` and loads `gemstack/dev`, so
+Gemfiles that still list `gemstack-dev` keep working. To finish upgrading, remove `gem "gemstack-dev"`
+from your Gemfile (it's loaded by `require "gemstack"`).
 
-## 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`).
+GemStack is a modular Ruby API framework for Next.js applications by
+[Adware Technologies](https://www.adwaretech.com) — [gemstack-rb/gemstack](https://github.com/gemstack-rb/gemstack).
 
 ## License
 

data/lib/gemstack-dev.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+# gemstack-dev is part of the gemstack gem since 0.3.0. This shim keeps Gemfiles
+# that still list gemstack-dev working; remove the line from your Gemfile.
+require "gemstack/dev"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: gemstack-dev
 version: !ruby/object:Gem::Version
-  version: 0.2.4
+  version: 0.3.0
 platform: ruby
 authors:
 - Adware Technologies
@@ -11,19 +11,28 @@ cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: gemstack-core
+  name: gemstack
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '='
+    - - ">="
       - !ruby/object:Gem::Version
-        version: 0.2.4
+        version: 0.3.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '1.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '='
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.3.0
+    - - "<"
       - !ruby/object:Gem::Version
-        version: 0.2.4
+        version: '1.0'
+description: Since GemStack 0.3.0, gemstack-dev is part of the gemstack gem. This
+  version only depends on gemstack and loads gemstack/dev, so Gemfiles that still
+  list it keep working.
 email:
 - gemstack26@gmail.com
 executables: []
@@ -33,23 +42,18 @@ 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
-- lib/gemstack/dev/toolchain.rb
+- lib/gemstack-dev.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
+  source_code_uri: https://github.com/gemstack-rb/gemstack
+  changelog_uri: https://github.com/gemstack-rb/gemstack/blob/main/CHANGELOG.md
   bug_tracker_uri: https://github.com/gemstack-rb/gemstack/issues
   documentation_uri: https://github.com/gemstack-rb/gemstack/tree/main/docs
+post_install_message: gemstack-dev is now part of the gemstack gem. Remove `gem "gemstack-dev"`
+  from your Gemfile (it's loaded by `require "gemstack"`).
 rdoc_options: []
 require_paths:
 - lib
@@ -66,5 +70,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 4.0.20
 specification_version: 4
-summary: 'GemStack development server: single-origin gateway and process supervisor'
+summary: Merged into the gemstack gem — remove gemstack-dev from your Gemfile
 test_files: []

data/lib/gemstack/dev/file_watcher.rb

@@ -1,58 +0,0 @@
-# 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

@@ -1,220 +0,0 @@
-# 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

@@ -1,96 +0,0 @@
-# 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

@@ -1,26 +0,0 @@
-# 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

@@ -1,267 +0,0 @@
-# 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
-        if frontend?
-          check_node!
-          prepare_frontend
-        end
-        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
-
-      # Next.js exits at once on an old Node.js with a line that's easy to miss
-      # among the other output; say it up front, with the command that fixes it.
-      def check_node!(node = Toolchain.node)
-        return if node && Toolchain.node_ok?(node[:version])
-
-        wanted = [@root.join(".node-version"), @root.join(".nvmrc")].find(&:file?)&.read&.strip
-        wanted = Toolchain::LTS_NODE if wanted.nil? || wanted.empty?
-        found = node ? "Node.js #{node[:version]} (#{node[:path]})" : "no `node` on the PATH"
-        raise Error, "Next.js needs Node.js #{Toolchain::MIN_NODE.join(".")} or newer; found #{found}.\n  " \
-                     "→ #{Toolchain.node_hint(wanted, Toolchain.node_manager(node&.fetch(:path)))}"
-      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 database queue and its table.
-      def jobs_enabled?
-        return false unless @dev.jobs_command && defined?(GemStack::Jobs) && @config.respond_to?(:jobs)
-        return false unless %w[database postgres].include?(@config.jobs.adapter.to_s)
-
-        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

@@ -1,40 +0,0 @@
-# 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/toolchain.rb

@@ -1,86 +0,0 @@
-# frozen_string_literal: true
-
-require "open3"
-require "rbconfig"
-
-module GemStack
-  module Dev
-    # The Ruby and Node.js a developer runs, and how to change them — for
-    # whichever version manager installed them (rbenv, rvm, asdf, mise,
-    # chruby, nvm, fnm, nodenv, Volta, Homebrew…). GemStack pins versions in
-    # files every manager reads (.ruby-version, .node-version, .nvmrc,
-    # .tool-versions) and never assumes one manager (DECISIONS D-066).
-    module Toolchain
-      MIN_RUBY = "3.3"
-      MIN_NODE = [20, 9].freeze # Next.js 16
-      LTS_NODE = "22"
-
-      # [pattern in the executable's path, manager name]; the first match wins.
-      RUBY_MANAGERS = [
-        [%r{/\.rbenv/}, :rbenv], [%r{/\.rvm/|/rvm/rubies/}, :rvm], [%r{/\.asdf/|/asdf/installs/}, :asdf],
-        [%r{/mise/installs/|/\.local/share/mise/}, :mise], [%r{/\.rubies/|/opt/rubies/}, :chruby],
-        [%r{/(?:opt/)?homebrew/|/usr/local/Cellar/}, :homebrew]
-      ].freeze
-      NODE_MANAGERS = [
-        [%r{/\.nvm/}, :nvm], [%r{/fnm/|/\.fnm/|fnm_multishells}, :fnm], [%r{/\.nodenv/}, :nodenv],
-        [%r{/\.asdf/|/asdf/installs/}, :asdf], [%r{/mise/installs/|/\.local/share/mise/}, :mise],
-        [%r{/\.volta/}, :volta], [%r{/(?:opt/)?homebrew/|/usr/local/Cellar/}, :homebrew]
-      ].freeze
-
-      module_function
-
-      def ruby_manager(path = RbConfig.ruby) = detect(RUBY_MANAGERS, path)
-      def node_manager(path) = path && detect(NODE_MANAGERS, path)
-
-      def detect(managers, path)
-        managers.find { |pattern, _| path.to_s.match?(pattern) }&.last
-      end
-
-      # How to install and select a Ruby, with the manager in use.
-      def ruby_hint(version, manager = ruby_manager)
-        {
-          rbenv: "rbenv install #{version} && rbenv local #{version}",
-          rvm: "rvm install #{version} && rvm use #{version}",
-          asdf: "asdf install ruby #{version} && asdf set ruby #{version}",
-          mise: "mise use ruby@#{version}",
-          chruby: "ruby-install ruby #{version}, then: chruby #{version}",
-          homebrew: "brew upgrade ruby (or install #{version} with rbenv, rvm, asdf or mise)"
-        }.fetch(manager, "install Ruby #{version} (e.g. with rbenv, rvm, asdf or mise) and make it the active Ruby")
-      end
-
-      # How to install and select a Node.js, with the manager in use.
-      def node_hint(version, manager)
-        {
-          nvm: "nvm install #{version} && nvm use #{version}",
-          fnm: "fnm install #{version} && fnm use #{version}",
-          nodenv: "nodenv install #{version} && nodenv local #{version}",
-          asdf: "asdf install nodejs #{version} && asdf set nodejs #{version}",
-          mise: "mise use node@#{version}",
-          volta: "volta install node@#{version}",
-          homebrew: "brew install node@#{version} (or use nvm, fnm, asdf or mise)"
-        }.fetch(manager, "install Node.js #{version} (e.g. with nvm, fnm, asdf or mise) and make it the active node")
-      end
-
-      # { version: "22.11.0", path: "/…/bin/node" } or nil when there's no node.
-      def node(run = ->(*cmd) { Open3.capture2e(*cmd) })
-        out, status = run.call("node", "-p", "process.version + ' ' + process.execPath")
-        return nil unless status.success?
-
-        version, path = out.strip.split(" ", 2)
-        { version: version.delete_prefix("v"), path: path }
-      rescue SystemCallError
-        nil
-      end
-
-      def node_ok?(version) = (version.to_s.split(".").map(&:to_i) <=> MIN_NODE) >= 0
-      def ruby_ok?(version = RUBY_VERSION) = Gem::Version.new(version) >= Gem::Version.new(MIN_RUBY)
-
-      # The Node.js version new apps pin: the one running `gemstack new` when
-      # it's new enough, else the current LTS line.
-      def pinned_node_version(run = ->(*cmd) { Open3.capture2e(*cmd) })
-        found = node(run)
-        found && node_ok?(found[:version]) ? found[:version] : LTS_NODE
-      end
-    end
-  end
-end

data/lib/gemstack/dev.rb

@@ -1,43 +0,0 @@
-# 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"
-    autoload :Toolchain, "gemstack/dev/toolchain"
-
-    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