fresco 0.0.1

data/lib/fresco/cli/dev_loop.rb

@@ -0,0 +1,815 @@
+# Fresco: dev loop. CRuby only — no Spinel rebuild.
+#
+#   1. Regenerate generated/* via `fresco build`.
+#   2. Watch config/routes.rb + app/actions/ + app/views/ for changes;
+#      rebuild + reload on edit.
+#   3. Listen on -p PORT (default 3030) with a tiny TCPServer-backed
+#      HTTP loop that calls the same `dispatch_request` the prod
+#      binary uses. ERB / action edits round-trip without a Spinel
+#      recompile; the C shim only matters in release.
+#
+# Loaded by Fresco::CLI::Dev#run into top-level scope so methods
+# defined here share scope with the methods generated/runtime.rb
+# defines on load.
+
+require "socket"
+
+ROOT = Dir.pwd
+# Defensive: dev's helpers all assume relative paths from the user
+# app's cwd; bind it explicitly so `fresco dev` invoked from a
+# subdirectory still walks up to the project root cleanly when
+# we add that capability later.
+Dir.chdir(ROOT)
+
+WATCH_GLOBS = [
+  "config/routes.rb",
+  "config/app.rb",
+  "config/database.rb",
+  "db/schema.rb",
+  "app/action.rb",
+  "app/actions/**/*.rb",
+  "app/models/**/*.rb",
+  "app/views/**/*.erb",
+].freeze
+RELOAD_LOCK = Mutex.new
+
+# Spinel's FFI DSL (`ffi_func`, `ffi_cflags`, …) is analyzer-only — the
+# AOT pipeline rewrites it before runtime. Under CRuby those names
+# don't exist, which would crash any `load` of a runtime that declares
+# FFI modules. Stub them as no-ops on `Module` so we can load
+# generated/runtime.rb in dev.
+class Module
+  def ffi_lib(*);    end
+  def ffi_cflags(*); end
+  def ffi_func(*);   end
+  def ffi_buffer(*); end
+  def ffi_read_u32(*); end
+  def ffi_read_i32(*); end
+  def ffi_read_ptr(*); end
+  def ffi_const(name, value)
+    const_set(name, value) unless const_defined?(name)
+  end
+end
+
+# `load`-ing the generated runtime + actions on every reload re-runs
+# their toplevel `FOO = ...` assignments, which Ruby warns about. The
+# redefinitions are intentional under the dev reloader, so filter just
+# those two warning shapes — everything else (uninitialized ivars,
+# method redefinitions, etc.) still flows through.
+module SilenceReloadConstWarnings
+  IGNORE = /already initialized constant|previous definition of/
+  def warn(msg, category: nil)
+    return if msg.is_a?(String) && msg.match?(IGNORE)
+    super
+  end
+end
+Warning.singleton_class.prepend(SilenceReloadConstWarnings)
+
+def build!
+  # Subprocess (vs. in-process call) keeps Fresco's build-time DSL
+  # accumulators (Fresco.models, Fresco.app.routes.entries, etc.) from
+  # leaking across rebuilds. The cost is one fork + ruby startup per
+  # reload, which is fine for development.
+  unless system("bundle", "exec", "fresco", "build")
+    warn "[dev] fresco build failed — keeping previous dispatcher"
+    return false
+  end
+  true
+end
+
+# `load` (vs require) re-evaluates on each call so reloads pick up
+# edits. Paths are relative to ROOT (we chdir'd above).
+def reload!
+  RELOAD_LOCK.synchronize do
+    load "generated/runtime.rb"
+    Dir.glob("generated/views/*.rb").sort.each { |f| load f }
+    load "generated/layout_dispatch.rb"
+    # db_adapter mirrors boot.rb's order: between layout_dispatch and
+    # config/app so the FFI module + Fresco::Db::Active are defined
+    # before user code can reference them. `fresco build` always emits
+    # this file (an empty stub when no adapter is configured), so the
+    # load never misses.
+    load "generated/db_adapter.rb"
+    # Migrations runner — defines Fresco::DbMigrations. Used by
+    # `./app db:migrate` and `fresco dev db:migrate` alike, so it has
+    # to be on the dev load path too. Boot.rb requires it between
+    # db_adapter and config/app; we mirror that order here.
+    load "generated/migrations.rb"
+    load "config/app.rb"
+    # config/database.rb populates Fresco.app.database_config from the
+    # running process's environment (ENV.fetch lives inside the file).
+    # `fresco build` also synthesises a placeholder when the user
+    # didn't supply one, so the load is unconditional.
+    load "config/database.rb" if File.exist?("config/database.rb")
+    # Generated models load before user action.rb so action classes
+    # can reference them. Models live under generated/models/ (one .rb
+    # per declared model in app/models/) — same file location dev and
+    # release use.
+    Dir.glob("generated/models/*.rb").sort.each { |f| load f }
+    load "app/action.rb"
+    Dir.glob("app/actions/**/*.rb").sort.each { |f| load f }
+    # Fresco-supplied default welcome action — only present when
+    # config/routes.rb has no `root to:` and `fresco build` emitted
+    # the fallback. Dispatch.rb references Fresco::Welcome, so load
+    # it before the dispatcher.
+    load "generated/welcome.rb" if File.exist?("generated/welcome.rb")
+    load "generated/dispatch.rb"
+
+    # The C shim isn't linked under CRuby — `ffi_func` was a no-op
+    # above, so `Sock` exists but has no methods. Provide CRuby
+    # stand-ins for the handful of Sock entries the runtime calls
+    # from non-server code paths (i.e. inside actions like Files::Show).
+    # The server-loop entries (sphttp_listen/accept/read/etc.) aren't
+    # needed because serve_dev replaces that loop entirely.
+    Sock.define_singleton_method(:sphttp_file_size) do |path|
+      File.exist?(path) ? File.size(path) : -1
+    end
+
+    # HMAC stand-ins. Under Spinel these are the public-domain
+    # SHA-256/HMAC code in generated/runtime/http.c; under CRuby we
+    # route through OpenSSL::HMAC so the Session class round-trips
+    # identically.
+    require "openssl"
+    require "base64"
+    Sock.define_singleton_method(:sphttp_hmac_sha256_hex) do |key, msg|
+      OpenSSL::HMAC.hexdigest("SHA256", key, msg)
+    end
+    Sock.define_singleton_method(:sphttp_hmac_sha256_b64url) do |key, msg|
+      Base64.urlsafe_encode64(OpenSSL::HMAC.digest("SHA256", key, msg), padding: false)
+    end
+
+    # Monotonic-clock stand-ins for the request-timing primitives the
+    # production handle_connection uses. Actions can reach for these
+    # (e.g. an around filter that times its work) and `fresco dev`
+    # needs to honor the same API surface, even though serve_dev's own
+    # loop doesn't rely on them.
+    Sock.instance_variable_set(:@dev_mark, 0)
+    Sock.define_singleton_method(:sphttp_mark_now) do
+      Sock.instance_variable_set(:@dev_mark, Process.clock_gettime(Process::CLOCK_MONOTONIC, :microsecond))
+      0
+    end
+    Sock.define_singleton_method(:sphttp_elapsed_micros) do
+      Process.clock_gettime(Process::CLOCK_MONOTONIC, :microsecond) -
+        Sock.instance_variable_get(:@dev_mark)
+    end
+
+    # DB adapter stand-ins. config/database.rb (loaded above) sets
+    # Fresco.app.database_config; we install the matching FFI stubs so
+    # actions hitting Fresco::Db::Active work under CRuby. Production
+    # routes through the linked C shim instead; the Ruby surface is
+    # identical so dev and prod behave the same from action code.
+    db_adapter = Fresco.database_adapter || :none
+
+    if db_adapter == :sqlite
+    require "sqlite3"
+    Sock.instance_variable_set(:@dev_sqlite_handles, [nil] * 16)
+    Sock.instance_variable_set(:@dev_sqlite_stmts,   [nil] * 64)
+    Sqlite.define_singleton_method(:fresco_sqlite_open) do |path|
+      handles = Sock.instance_variable_get(:@dev_sqlite_handles)
+      slot = handles.index(nil)
+      return -1 if slot.nil?
+      begin
+        handles[slot] = ::SQLite3::Database.new(path)
+        slot + 1
+      rescue ::SQLite3::Exception
+        -1
+      end
+    end
+    Sqlite.define_singleton_method(:fresco_sqlite_close) do |h|
+      handles = Sock.instance_variable_get(:@dev_sqlite_handles)
+      stmts   = Sock.instance_variable_get(:@dev_sqlite_stmts)
+      return -1 if h < 1 || h > handles.length
+      db = handles[h - 1]
+      return -1 if db.nil?
+      stmts.each_with_index do |s, i|
+        next if s.nil?
+        if s[0] == db
+          s[1].close unless s[1].closed?
+          stmts[i] = nil
+        end
+      end
+      db.close
+      handles[h - 1] = nil
+      0
+    end
+    Sqlite.define_singleton_method(:fresco_sqlite_exec) do |h, sql|
+      handles = Sock.instance_variable_get(:@dev_sqlite_handles)
+      return -1 if h < 1 || h > handles.length
+      db = handles[h - 1]
+      return -1 if db.nil?
+      begin
+        db.execute_batch(sql)
+        0
+      rescue ::SQLite3::Exception
+        -1
+      end
+    end
+    Sqlite.define_singleton_method(:fresco_sqlite_prepare) do |h, sql|
+      handles = Sock.instance_variable_get(:@dev_sqlite_handles)
+      stmts   = Sock.instance_variable_get(:@dev_sqlite_stmts)
+      return -1 if h < 1 || h > handles.length
+      db = handles[h - 1]
+      return -1 if db.nil?
+      slot = stmts.index(nil)
+      return -1 if slot.nil?
+      begin
+        stmt = db.prepare(sql)
+        stmts[slot] = [db, stmt, nil] # [db, stmt, last_step_row_or_nil]
+        slot + 1
+      rescue ::SQLite3::Exception
+        -1
+      end
+    end
+    Sqlite.define_singleton_method(:fresco_sqlite_bind_str) do |cid, idx, value|
+      stmts = Sock.instance_variable_get(:@dev_sqlite_stmts)
+      return -1 if cid < 1 || cid > stmts.length
+      entry = stmts[cid - 1]
+      return -1 if entry.nil?
+      begin
+        entry[1].bind_param(idx, value)
+        0
+      rescue ::SQLite3::Exception
+        -1
+      end
+    end
+    Sqlite.define_singleton_method(:fresco_sqlite_bind_int) do |cid, idx, value|
+      stmts = Sock.instance_variable_get(:@dev_sqlite_stmts)
+      return -1 if cid < 1 || cid > stmts.length
+      entry = stmts[cid - 1]
+      return -1 if entry.nil?
+      begin
+        entry[1].bind_param(idx, value)
+        0
+      rescue ::SQLite3::Exception
+        -1
+      end
+    end
+    Sqlite.define_singleton_method(:fresco_sqlite_step) do |cid|
+      stmts = Sock.instance_variable_get(:@dev_sqlite_stmts)
+      return -1 if cid < 1 || cid > stmts.length
+      entry = stmts[cid - 1]
+      return -1 if entry.nil?
+      # The gem's stmt acts as an iterator; capture the next row (or
+      # nil at end-of-result) so col_* lookups read off the same row.
+      entry[2] = entry[1].step
+      return 0 if entry[2].nil?
+      1
+    end
+    Sqlite.define_singleton_method(:fresco_sqlite_col_str) do |cid, idx|
+      stmts = Sock.instance_variable_get(:@dev_sqlite_stmts)
+      return "" if cid < 1 || cid > stmts.length
+      entry = stmts[cid - 1]
+      return "" if entry.nil? || entry[2].nil?
+      v = entry[2][idx]
+      v.nil? ? "" : v.to_s
+    end
+    Sqlite.define_singleton_method(:fresco_sqlite_col_int) do |cid, idx|
+      stmts = Sock.instance_variable_get(:@dev_sqlite_stmts)
+      return 0 if cid < 1 || cid > stmts.length
+      entry = stmts[cid - 1]
+      return 0 if entry.nil? || entry[2].nil?
+      v = entry[2][idx]
+      v.nil? ? 0 : v.to_i
+    end
+    Sqlite.define_singleton_method(:fresco_sqlite_col_count) do |cid|
+      stmts = Sock.instance_variable_get(:@dev_sqlite_stmts)
+      return 0 if cid < 1 || cid > stmts.length
+      entry = stmts[cid - 1]
+      return 0 if entry.nil?
+      entry[1].columns.length
+    end
+    Sqlite.define_singleton_method(:fresco_sqlite_finalize) do |cid|
+      stmts = Sock.instance_variable_get(:@dev_sqlite_stmts)
+      return 0 if cid < 1 || cid > stmts.length
+      entry = stmts[cid - 1]
+      return 0 if entry.nil?
+      entry[1].close unless entry[1].closed?
+      stmts[cid - 1] = nil
+      0
+    end
+    Sqlite.define_singleton_method(:fresco_sqlite_reset) do |cid|
+      stmts = Sock.instance_variable_get(:@dev_sqlite_stmts)
+      return -1 if cid < 1 || cid > stmts.length
+      entry = stmts[cid - 1]
+      return -1 if entry.nil?
+      entry[1].reset!
+      entry[2] = nil
+      0
+    end
+    Sqlite.define_singleton_method(:fresco_sqlite_last_insert_rowid) do |h|
+      handles = Sock.instance_variable_get(:@dev_sqlite_handles)
+      return -1 if h < 1 || h > handles.length
+      db = handles[h - 1]
+      return -1 if db.nil?
+      db.last_insert_row_id.to_i
+    end
+    end
+
+    if db_adapter == :postgres
+      # Postgres stand-ins. The `pg` gem is loaded lazily so apps on
+      # the SQLite adapter (or with no DB) don't need it installed.
+      # Mirrors the production generated/runtime/postgres.c shim:
+      # per-cursor state holding {conn, sql, accumulated binds,
+      # PGresult, row index}; bind_*/step lazy-execute via PQexecParams
+      # on first step.
+      begin
+        require "pg"
+      rescue LoadError
+        abort "[dev] config/database.rb declares :postgres but the `pg` gem " \
+              "is not installed. Add `gem \"pg\"` to the :development group " \
+              "in your Gemfile and bundle."
+      end
+      Sock.instance_variable_set(:@dev_pg_handles, [nil] * 16)
+      Sock.instance_variable_set(:@dev_pg_stmts,   [nil] * 64)
+      Pg.define_singleton_method(:fresco_pg_open) do |url|
+        handles = Sock.instance_variable_get(:@dev_pg_handles)
+        slot = handles.index(nil)
+        return -1 if slot.nil?
+        begin
+          handles[slot] = ::PG.connect(url)
+          slot + 1
+        rescue ::PG::Error
+          -1
+        end
+      end
+      Pg.define_singleton_method(:fresco_pg_close) do |h|
+        handles = Sock.instance_variable_get(:@dev_pg_handles)
+        stmts   = Sock.instance_variable_get(:@dev_pg_stmts)
+        return -1 if h < 1 || h > handles.length
+        conn = handles[h - 1]
+        return -1 if conn.nil?
+        stmts.each_with_index do |s, i|
+          next if s.nil?
+          if s[:conn] == conn
+            stmts[i] = nil
+          end
+        end
+        conn.close
+        handles[h - 1] = nil
+        0
+      end
+      Pg.define_singleton_method(:fresco_pg_exec) do |h, sql|
+        handles = Sock.instance_variable_get(:@dev_pg_handles)
+        return -1 if h < 1 || h > handles.length
+        conn = handles[h - 1]
+        return -1 if conn.nil?
+        begin
+          conn.exec(sql)
+          0
+        rescue ::PG::Error
+          -1
+        end
+      end
+      Pg.define_singleton_method(:fresco_pg_prepare) do |h, sql|
+        handles = Sock.instance_variable_get(:@dev_pg_handles)
+        stmts   = Sock.instance_variable_get(:@dev_pg_stmts)
+        return -1 if h < 1 || h > handles.length
+        conn = handles[h - 1]
+        return -1 if conn.nil?
+        slot = stmts.index(nil)
+        return -1 if slot.nil?
+        # Defer execution until the first step, like the C shim. Binds
+        # accumulate into :params (1-indexed, sparse), then PQexecParams
+        # equivalent fires on first step.
+        stmts[slot] = { conn: conn, sql: sql, params: [], result: nil, row: -1, ntuples: 0 }
+        slot + 1
+      end
+      Pg.define_singleton_method(:fresco_pg_bind_str) do |cid, idx, value|
+        stmts = Sock.instance_variable_get(:@dev_pg_stmts)
+        return -1 if cid < 1 || cid > stmts.length
+        entry = stmts[cid - 1]
+        return -1 if entry.nil?
+        entry[:params][idx - 1] = value.to_s
+        0
+      end
+      Pg.define_singleton_method(:fresco_pg_bind_int) do |cid, idx, value|
+        stmts = Sock.instance_variable_get(:@dev_pg_stmts)
+        return -1 if cid < 1 || cid > stmts.length
+        entry = stmts[cid - 1]
+        return -1 if entry.nil?
+        entry[:params][idx - 1] = value.to_s
+        0
+      end
+      Pg.define_singleton_method(:fresco_pg_step) do |cid|
+        stmts = Sock.instance_variable_get(:@dev_pg_stmts)
+        return -1 if cid < 1 || cid > stmts.length
+        entry = stmts[cid - 1]
+        return -1 if entry.nil?
+        if entry[:result].nil?
+          # First step: fire query with accumulated binds. Replace nils
+          # with empty strings so libpq's text coercion has something
+          # to chew on.
+          values = entry[:params].map { |v| v.nil? ? "" : v }
+          begin
+            entry[:result]  = entry[:conn].exec_params(entry[:sql], values)
+            entry[:ntuples] = entry[:result].ntuples
+            entry[:row]     = -1
+          rescue ::PG::Error
+            entry[:result] = nil
+            return -1
+          end
+        end
+        entry[:row] += 1
+        entry[:row] < entry[:ntuples] ? 1 : 0
+      end
+      Pg.define_singleton_method(:fresco_pg_col_str) do |cid, idx|
+        stmts = Sock.instance_variable_get(:@dev_pg_stmts)
+        return "" if cid < 1 || cid > stmts.length
+        entry = stmts[cid - 1]
+        return "" if entry.nil? || entry[:result].nil?
+        return "" if entry[:row] < 0 || entry[:row] >= entry[:ntuples]
+        v = entry[:result].getvalue(entry[:row], idx)
+        v.nil? ? "" : v.to_s
+      end
+      Pg.define_singleton_method(:fresco_pg_col_int) do |cid, idx|
+        stmts = Sock.instance_variable_get(:@dev_pg_stmts)
+        return 0 if cid < 1 || cid > stmts.length
+        entry = stmts[cid - 1]
+        return 0 if entry.nil? || entry[:result].nil?
+        return 0 if entry[:row] < 0 || entry[:row] >= entry[:ntuples]
+        v = entry[:result].getvalue(entry[:row], idx)
+        v.nil? ? 0 : v.to_i
+      end
+      Pg.define_singleton_method(:fresco_pg_col_count) do |cid|
+        stmts = Sock.instance_variable_get(:@dev_pg_stmts)
+        return 0 if cid < 1 || cid > stmts.length
+        entry = stmts[cid - 1]
+        return 0 if entry.nil? || entry[:result].nil?
+        entry[:result].nfields
+      end
+      Pg.define_singleton_method(:fresco_pg_finalize) do |cid|
+        stmts = Sock.instance_variable_get(:@dev_pg_stmts)
+        return 0 if cid < 1 || cid > stmts.length
+        stmts[cid - 1] = nil
+        0
+      end
+      Pg.define_singleton_method(:fresco_pg_reset) do |cid|
+        stmts = Sock.instance_variable_get(:@dev_pg_stmts)
+        return -1 if cid < 1 || cid > stmts.length
+        entry = stmts[cid - 1]
+        return -1 if entry.nil?
+        entry[:result]  = nil
+        entry[:row]     = -1
+        entry[:ntuples] = 0
+        0
+      end
+      Pg.define_singleton_method(:fresco_pg_last_insert_rowid) do |h|
+        handles = Sock.instance_variable_get(:@dev_pg_handles)
+        return -1 if h < 1 || h > handles.length
+        conn = handles[h - 1]
+        return -1 if conn.nil?
+        begin
+          res = conn.exec("SELECT lastval()")
+          res.ntuples > 0 ? res.getvalue(0, 0).to_i : -1
+        rescue ::PG::Error
+          -1
+        end
+      end
+    end
+  end
+end
+
+def snapshot_mtimes
+  files = WATCH_GLOBS.flat_map { |g| Dir.glob(g) }.sort
+  files.each_with_object({}) { |f, h| h[f] = File.mtime(f).to_f }
+end
+
+def start_watcher
+  last = snapshot_mtimes
+  Thread.new do
+    Thread.current.abort_on_exception = false
+    loop do
+      sleep 0.2
+      cur = snapshot_mtimes
+      next if cur == last
+      changed = (cur.keys | last.keys).select { |k| cur[k] != last[k] }
+      last = cur
+      puts "#{Color.yellow('[reload]')} #{changed.join(', ')}"
+      reload! if build!
+    end
+  end
+end
+
+# --- Dev HTTP listener ------------------------------------------
+#
+# Single-threaded TCPServer accept loop. Each request: parse the
+# request line + headers, read a Content-Length-bounded body, build a
+# Request, dispatch under RELOAD_LOCK (so file-watcher reloads don't
+# race with in-flight requests), write the response. No keep-alive —
+# every dev response carries `Connection: close`. Keep-alive lives in
+# the prefork worker on the prod path.
+
+def parse_dev_request(sock)
+  request_line = sock.gets("\r\n")
+  return nil if request_line.nil?
+  method, raw_path, _version = request_line.strip.split(" ", 3)
+  return nil if method.nil? || raw_path.nil?
+
+  qmark = raw_path.index("?")
+  if qmark
+    path = raw_path[0...qmark]
+    qstr = raw_path[(qmark + 1)..]
+  else
+    path = raw_path
+    qstr = ""
+  end
+
+  headers = {}
+  while (line = sock.gets("\r\n"))
+    line = line.chomp
+    break if line.empty?
+    colon = line.index(":")
+    next unless colon
+    name  = line[0...colon].downcase
+    value = line[(colon + 1)..].lstrip
+    headers[name] = value
+  end
+
+  body = ""
+  cl = headers["content-length"]
+  if cl && cl.to_i > 0
+    body = sock.read(cl.to_i) || ""
+  end
+
+  req = Request.new(method, path, body)
+  parse_query_string!(qstr, req.params) if qstr.length > 0
+  headers.each { |k, v| req.headers[k] = v }
+  ctype = headers["content-type"]
+  if ctype && ctype == "application/x-www-form-urlencoded"
+    parse_form_body!(body, req.params)
+  end
+
+  # Mirror runtime's `_method` override (see runtime/runtime.rb).
+  if req.verb == "POST"
+    override = req.params.str(:_method)
+    req.verb = override.upcase if override.length > 0
+  end
+
+  # Parse Cookie header into req.cookies. We can't reuse runtime's
+  # `parse_cookie_header!` because it relies on Spinel's
+  # `String#index`-returns-`-1` semantics (CRuby returns nil). The
+  # idiomatic split-and-loop below is equivalent.
+  cookie_hdr = headers["cookie"]
+  if cookie_hdr && !cookie_hdr.empty?
+    cookie_hdr.split(";").each do |pair|
+      pair = pair.strip
+      next if pair.empty?
+      eq = pair.index("=")
+      if eq.nil?
+        req.cookies[pair] = ""
+      else
+        req.cookies[pair[0...eq]] = url_decode(pair[(eq + 1)..])
+      end
+    end
+  end
+  maybe_load_session!(req)
+
+  req
+end
+
+# Write an HTTP/1.1 response. Body responses go out as one write;
+# file responses (file_path set on the Response) are loaded from
+# disk and written inline — production uses sendfile(2), but dev
+# is correctness-over-throughput.
+def write_dev_response(sock, res)
+  if res.file_path.length > 0
+    if File.exist?(res.file_path)
+      status = res.status
+      ctype  = res.content_type
+      body   = File.binread(res.file_path)
+    else
+      status = 404
+      ctype  = "text/plain; charset=utf-8"
+      body   = "Not Found"
+    end
+  else
+    status = res.status
+    ctype  = res.content_type
+    body   = res.body
+  end
+
+  reason = reason_for(status)
+  sock.write("HTTP/1.1 #{status} #{reason}\r\n")
+  sock.write("Content-Type: #{ctype}\r\n")
+  sock.write("Content-Length: #{body.bytesize}\r\n")
+  sock.write("Location: #{res.location}\r\n") if res.location.length > 0
+  res.set_cookies.each { |line| sock.write("Set-Cookie: #{line}\r\n") }
+  sock.write("Connection: close\r\n\r\n")
+  sock.write(body)
+end
+
+def serve_dev(port)
+  server = TCPServer.new("0.0.0.0", port)
+  puts "#{Color.cyan('[dev]')} listening on http://0.0.0.0:#{port}"
+  loop do
+    client = server.accept
+    handle_dev_connection(client)
+  end
+rescue Interrupt
+  puts "\n#{Color.cyan('[dev]')} stopping"
+end
+
+# Dev-only crash page. Renders the exception class, message, and
+# backtrace inline so /crash (and any other action raise) shows up
+# in the browser instead of being a static "Internal Server Error"
+# page. NEVER call this in production — leaks paths, gem versions,
+# and whatever string the exception happened to carry.
+def render_dev_error(err, req)
+  esc = ->(s) { Spinel::View.h(s.to_s) }
+  bt  = (err.backtrace || []).map { |line| "<li>#{esc.call(line)}</li>" }.join
+
+  method  = req ? req.verb  : "?"
+  path    = req ? req.path    : "?"
+  params  = req ? format_hash(req.params.raw) : "(unavailable)"
+  query   = req ? format_hash(req.query)      : "(unavailable)"
+  headers = req ? format_hash(req.headers)    : "(unavailable)"
+
+  body = <<~HTML
+    <!doctype html>
+    <html>
+      <head>
+        <meta charset="utf-8">
+        <title>500 — #{esc.call(err.class.name)}</title>
+        <link rel="preconnect" href="https://fonts.googleapis.com">
+        <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+        <link href="https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;500;700&display=swap" rel="stylesheet">
+        <script>
+          (function () {
+            var t = localStorage.getItem("theme");
+            if (!t) {
+              t = (window.matchMedia && window.matchMedia("(prefers-color-scheme: dark)").matches) ? "dark" : "light";
+              localStorage.setItem("theme", t);
+            }
+            document.documentElement.setAttribute("data-theme", t);
+          })();
+        </script>
+        <style>
+          :root {
+            --bg: #fff; --fg: #222; --muted: #888;
+            --border: #eee; --code-bg: #f7f7f7;
+            --accent: #0066cc; --status: #b00020;
+          }
+          :root[data-theme="dark"] {
+            --bg: #141414; --fg: #e8e8e8; --muted: #9a9a9a;
+            --border: #2a2a2a; --code-bg: #1f1f1f;
+            --accent: #6ab0ff; --status: #ff6680;
+          }
+          body {
+            font-family: 'IBM Plex Mono', ui-monospace, monospace;
+            max-width: 60rem; margin: 2rem auto; padding: 0 1.5rem;
+            background: var(--bg); color: var(--fg);
+            transition: background 0.15s, color 0.15s;
+          }
+          .status { color: var(--status); font-size: 0.8rem; letter-spacing: 0.05em; text-transform: uppercase; }
+          h1 { font-size: 1.25rem; font-weight: 700; margin: 0.25rem 0 0; word-break: break-word; }
+          .msg { color: var(--muted); margin: 0.5rem 0 1.5rem; white-space: pre-wrap; }
+          h2 { font-size: 0.85rem; text-transform: uppercase; letter-spacing: 0.05em; color: var(--muted); margin-top: 2rem; }
+          ol.bt { background: var(--code-bg); border: 1px solid var(--border); border-radius: 4px; padding: 1rem 1rem 1rem 3rem; font-size: 0.85rem; line-height: 1.5; color: var(--fg); }
+          ol.bt li { word-break: break-all; }
+          dl { display: grid; grid-template-columns: 6rem 1fr; gap: 0.4rem 1rem; font-size: 0.85rem; }
+          dt { color: var(--muted); }
+          dd { margin: 0; word-break: break-word; }
+          footer { color: var(--muted); font-size: 0.8rem; margin-top: 2rem; border-top: 1px solid var(--border); padding-top: 1rem; }
+          #theme-toggle {
+            position: fixed; top: 1rem; right: 1rem;
+            background: transparent; border: 1px solid var(--border);
+            color: var(--fg); border-radius: 6px;
+            padding: 0.4rem; cursor: pointer;
+            display: inline-flex; align-items: center; justify-content: center;
+          }
+          #theme-toggle:hover { background: var(--code-bg); }
+          #theme-toggle svg { width: 18px; height: 18px; display: none; }
+          :root[data-theme="light"] #theme-toggle .icon-moon { display: inline-block; }
+          :root[data-theme="dark"]  #theme-toggle .icon-sun  { display: inline-block; }
+        </style>
+      </head>
+      <body>
+        <button id="theme-toggle" aria-label="Toggle color theme" title="Toggle color theme">
+          <svg class="icon-sun" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="12" cy="12" r="4"/><path d="M12 2v2"/><path d="M12 20v2"/><path d="m4.93 4.93 1.41 1.41"/><path d="m17.66 17.66 1.41 1.41"/><path d="M2 12h2"/><path d="M20 12h2"/><path d="m6.34 17.66-1.41 1.41"/><path d="m19.07 4.93-1.41 1.41"/></svg>
+          <svg class="icon-moon" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M21 12.79A9 9 0 1 1 11.21 3 7 7 0 0 0 21 12.79z"/></svg>
+        </button>
+
+        <div class="status">500 &middot; fresco dev exception</div>
+        <h1>#{esc.call(err.class.name)}</h1>
+        <p class="msg">#{esc.call(err.message)}</p>
+
+        <h2>Backtrace</h2>
+        <ol class="bt">#{bt}</ol>
+
+        <h2>Request</h2>
+        <dl>
+          <dt>Method</dt><dd>#{esc.call(method)}</dd>
+          <dt>Path</dt><dd>#{esc.call(path)}</dd>
+          <dt>Params</dt><dd>#{esc.call(params)}</dd>
+          <dt>Query</dt><dd>#{esc.call(query)}</dd>
+          <dt>Headers</dt><dd>#{esc.call(headers)}</dd>
+        </dl>
+
+        <footer>Rendered by `fresco dev`. Production serves public/500.html with no error details.</footer>
+
+        <script>
+          (function () {
+            document.getElementById("theme-toggle").addEventListener("click", function () {
+              var cur = document.documentElement.getAttribute("data-theme");
+              var nxt = cur === "dark" ? "light" : "dark";
+              document.documentElement.setAttribute("data-theme", nxt);
+              localStorage.setItem("theme", nxt);
+            });
+          })();
+        </script>
+      </body>
+    </html>
+  HTML
+
+  Response.html(500, body)
+end
+
+def handle_dev_connection(client)
+  req = parse_dev_request(client)
+  if req.nil?
+    write_dev_response(client, error_response(400, "Bad Request\n"))
+    puts "#{Color.dim('[request]')} ? ? #{color_status(400)}"
+    return
+  end
+
+  # Mirror runtime.rb's request bracket so the SQL-log buffer flushes
+  # under the [request] line. The Fresco::Db no-op stub is loaded even
+  # when no adapter is configured, so this call is safe regardless.
+  Fresco::Db.begin_request!
+  t0 = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+  res = RELOAD_LOCK.synchronize { dispatch_request(req.verb, req.path, req) }
+  attach_session_cookie!(req, res)
+  micros = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - t0) * 1_000_000).to_i
+  write_dev_response(client, res)
+  log_request_full(req, res.status, micros)
+  Fresco::Db.flush_log!
+rescue => e
+  puts "#{Color.red('[handler]')} #{e.class}: #{e.message}"
+  (e.backtrace || []).first(5).each { |b| puts Color.dim("  #{b}") }
+  Fresco::Db.flush_log!
+  begin
+    write_dev_response(client, render_dev_error(e, req))
+  rescue StandardError
+    # client already gone — nothing to do
+  end
+ensure
+  client.close rescue nil
+end
+
+# --- main --------------------------------------------------------
+
+# `fresco dev db:*` short-circuits the watcher+server and just runs
+# the requested subcommand against the dev-mode CRuby load. Useful for
+# applying migrations from your editor without a release build, and
+# for `db:console` — drops into IRB with every generated model
+# loaded and the FFI stand-ins wired so model methods actually hit
+# the DB.
+if ARGV[0] && ARGV[0].start_with?("db:")
+  build! || abort("[dev] build failed; fix and retry")
+  reload!
+  cmd = ARGV[0]
+  case cmd
+  when "db:migrate"
+    Fresco::DbMigrations.migrate!
+  when "db:rollback"
+    Fresco::DbMigrations.rollback!
+  when "db:reset"
+    # Roll back to a clean slate, then re-apply. Loops because
+    # rollback! peels one migration per call. For a small migration
+    # set this is fine; M6+ could add a single-call "rollback all".
+    loop_count = 0
+    while loop_count < Fresco.migrations.length + 1
+      Fresco::DbMigrations.rollback!
+      loop_count += 1
+    end
+    Fresco::DbMigrations.migrate!
+  when "db:console"
+    require "irb"
+    puts "[dev] Fresco IRB console — models and Fresco::Db.* are loaded."
+    puts "[dev] adapter=#{Fresco.database_adapter.inspect} dsn=#{Fresco.database_url.empty? ? Fresco.database_path : Fresco.database_url}"
+    # IRB.start scans ARGV for a script path; left as-is it tries to
+    # open `db:console` as a file. Clear ARGV so IRB drops into a
+    # bare interactive session.
+    ARGV.clear
+    IRB.start
+  else
+    abort "[dev] unknown subcommand: #{cmd} (try db:migrate, db:rollback, db:reset, db:console)"
+  end
+  exit 0
+end
+
+port = 3030
+i = 0
+while i < ARGV.length
+  if ARGV[i] == "-p" && ARGV[i + 1]
+    port = ARGV[i + 1].to_i
+    i += 2
+  else
+    i += 1
+  end
+end
+
+build! || abort("[dev] initial build failed; fix and retry")
+reload!
+start_watcher
+serve_dev(port)