tep 0.11.0

data/bin/tep

@@ -0,0 +1,2156 @@
+#!/usr/bin/env ruby
+# tep -- build-time translator + driver for the Tep framework.
+#
+# `tep build app.rb [-o out]`  -- translate Sinatra-style source to
+#                                 spinel-compilable Ruby and compile
+#                                 it to a native binary via spinel.
+#
+# `tep run app.rb [-p PORT] [-w WORKERS]` -- build, then run the result.
+#
+# Translation: top-level `get '/' do ... end` (and post/put/patch/
+# delete/before/after/not_found) blocks are extracted by Prism and
+# emitted as Tep::Handler / Tep::Filter subclasses. Common Sinatra
+# DSL idioms inside blocks are textually rewritten:
+#
+#   params           -> req.params
+#   request          -> req
+#   response         -> res
+#   redirect 'x'     -> res.set_status(302); res.headers['Location']='x'; ''
+#   halt N, 'msg'    -> res.set_status(N); 'msg'
+#   content_type 'x' -> res.headers['Content-Type'] = 'x'
+#   set :public_dir, 'p' -> Tep.public_dir 'p'
+#
+# Spinel-incompatible patterns (template engines, helpers blocks,
+# rack middleware, etc.) get warned about; they don't translate.
+
+# The translator parses the user's Sinatra source with Prism. Prism
+# ships with Ruby 3.4+, but tep keeps it a *development-only* gem
+# dependency (it's a C extension Spinel can't compile, so a runtime dep
+# would drag it into a spinelgems consumer's lock + fail the compat
+# gate). So on a `gem install tep` under Ruby 3.2/3.3 it may be absent
+# -- fail with an actionable message instead of a bare LoadError.
+begin
+  require "prism"
+rescue LoadError
+  abort "tep: the translator needs the `prism` parser, which isn't " \
+        "available here.\n" \
+        "  - Ruby 3.4+ bundles it (no action needed).\n" \
+        "  - On Ruby 3.2/3.3:  gem install prism\n" \
+        "Prism is a build-time-only dep (a C extension Spinel can't " \
+        "compile), so tep deliberately doesn't pull it into your lock."
+end
+require "fileutils"
+require "tmpdir"
+require "pathname"
+
+LIB_DIR   = File.expand_path("../lib", __dir__)
+REPO_ROOT = File.dirname(LIB_DIR)
+
+# The @TEP_*@ placeholder shape lives in spinel-ext.json at the gem
+# root -- the single source of truth shared with `spinel-compat
+# vendor` (which wires the C-ext for downstream consumers), so the
+# substitution list isn't duplicated per consumer. See
+# OriPekelman/tep#97 + #98 and spinelgems' docs/c-ext.md.
+require "json"
+
+# Resolve spinel: explicit env var wins, then a sibling
+# `../spinel/spinel` checkout (matches the typical dev layout where
+# tep and spinel are checked out side by side), then plain `spinel`
+# on PATH. The Makefile exports SPINEL=spinel by default; treat the
+# literal placeholder as unset so the sibling fallback still fires.
+def self.locate_spinel
+  e = ENV["SPINEL"]
+  return e if e && !e.empty? && e != "spinel"
+  sibling = File.expand_path("../../spinel/spinel", __dir__)
+  return sibling if File.executable?(sibling)
+  "spinel"
+end
+SPINEL = locate_spinel
+
+DSL_VERBS = %w[get post put patch delete options head]
+HOOK_NAMES = %w[before after not_found]
+WS_EVENTS  = %w[on_open on_message on_close on_ping on_pong on_error]
+
+def fatal(msg)
+  warn "tep: #{msg}"
+  exit 1
+end
+
+# Build the translated Ruby source from a Sinatra-style file.
+def translate(input_path)
+  raw_source = File.read(input_path)
+
+  # Split off `__END__` inline templates. Sinatra's convention is
+  # `@@ name\n<template body>` repeated. Pre-__END__ goes through
+  # Prism; post-__END__ is parsed by us into a name->body map.
+  source, inline_views = split_inline_views(raw_source)
+
+  parsed = Prism.parse(source)
+  fatal "parse errors in #{input_path}\n  #{parsed.errors.map(&:message).join("\n  ")}" unless parsed.success?
+
+  prog = parsed.value
+  routes        = []
+  websockets    = []
+  live_views    = []
+  mcp_tools     = []
+  mcp_resources = []
+  proxies       = []   # Tep::Proxy block-DSL (#88): one entry per
+                       # `var = Tep::Proxy.new(...)` + its .before/.after/
+                       # .on_stream_chunk/.on_stream_end/.stream_request?
+                       # block calls, lowered to a generated subclass.
+  filters       = { "before" => [], "after" => [] }
+  not_founds    = []
+  startup_block = nil
+  config        = { public_dir: nil, mcp_server_name: nil, mcp_server_version: nil }
+  warnings      = []
+  anon_id       = 0
+
+  # We only walk the top-level statements; handlers inside Sinatra's
+  # `class App < Sinatra::Base` are not supported in v0.1.
+  unwrapped_apps = []
+  passthrough    = []
+  # Dedupe set for recursive require_relative inlining (deps.rb chains;
+  # shared deps must inline once). Keyed by absolute path; build-wide.
+  inlined_seen   = {}
+  # Scan ALL `erb :name` and `mustache :name` references up front;
+  # every referenced view gets compiled and emitted at the top of
+  # the synthesized output. ERB views compile to `tep_view_<name>`,
+  # mustache views to `tep_mustache_<name>` -- separate namespaces
+  # so a project can mix engines without name collisions.
+  views_used     = source.scan(/(?<![\w.])erb\s+:(\w+)/).flatten.uniq
+  mustaches_used = source.scan(/(?<![\w.])mustache\s+:(\w+)/).flatten.uniq
+  process = lambda do |node|
+    # `Tep.live "/path", ViewClass` -- the one Tep::*-receiver call
+    # the translator owns. Lowers to a GET route (render_page) +
+    # WS route (per-connection view instance, event dispatch +
+    # re-render). Other Tep.*  calls (Tep.before, Tep.get, ...)
+    # pass through as runtime method calls.
+    if call?(node) && node.name == :live &&
+       node.receiver.is_a?(Prism::ConstantReadNode) &&
+       node.receiver.name == :Tep
+      handle_tep_live(node, live_views, warnings)
+      return
+    end
+
+    # Proxy block-DSL (#88), part 1: `var = Tep::Proxy.new(...)`.
+    # Record the proxy var + rewrite the assignment to instantiate
+    # the generated subclass (TepProxy_<idx>), which carries the
+    # before/after/stream hooks collected below. The base
+    # `Tep::Proxy.new` would forward with no customization; the
+    # subclass is only emitted when at least one hook block is seen,
+    # but we always rewrite so the var name stays consistent.
+    if node.is_a?(Prism::LocalVariableWriteNode) && proxy_new_call?(node.value)
+      idx    = proxies.length
+      up_src = proxy_upstream_src(node.value, warnings)
+      proxies << { var: node.name.to_s, idx: idx, upstream: up_src, hooks: {} }
+      # Assign to a CONSTANT, not the original local. A Tep::Proxy
+      # subclass instance flowing through a *local* into Tep.<verb>
+      # widens rewrite_path's virtual `path` param to poly (poisoning
+      # Tep::App.guess_mime's `path` file-wide); the same instance via
+      # a constant compiles clean. Mounts are rewritten to the
+      # constant below.
+      passthrough << "TEPPROXY_#{idx} = TepProxy_#{idx}.new(#{up_src})"
+      return
+    end
+
+    # Proxy block-DSL (#88), part 2: `proxyvar.before do ... end`
+    # (and .after / .on_stream_chunk / .on_stream_end /
+    # .stream_request?). Collect the block onto the proxy entry +
+    # suppress from passthrough (a receiver-method call with a block
+    # can't lower -- spinel has no PtrArray<Block>; the block becomes
+    # an imeth on the generated subclass instead).
+    if call?(node) && node.receiver.is_a?(Prism::LocalVariableReadNode) &&
+       PROXY_HOOK_IMETH.key?(node.name.to_s) && node.block.is_a?(Prism::BlockNode)
+      pv = proxies.find { |p| p[:var] == node.receiver.name.to_s }
+      if pv
+        pv[:hooks][node.name.to_s] = {
+          params: block_param_list(node.block),
+          src:    block_source(node.block),
+        }
+        return
+      end
+    end
+
+    # Proxy block-DSL (#88), part 3: rewrite a mount of a proxy var --
+    # `Tep.<verb> "path", proxyvar` or bare `<verb> "path", proxyvar`
+    # (no block) -- to reference the generated constant instead of the
+    # (dropped) local. Reconstructed structurally so the handler arg
+    # becomes TEPPROXY_<idx>.
+    if call?(node) && PROXY_MOUNT_VERBS.include?(node.name.to_s) && node.block.nil?
+      margs = node.arguments&.arguments || []
+      if margs.length == 2 && margs[1].is_a?(Prism::LocalVariableReadNode)
+        pv = proxies.find { |p| p[:var] == margs[1].name.to_s }
+        if pv
+          recv = node.receiver ? "#{node.receiver.location.slice}." : ""
+          passthrough << "#{recv}#{node.name}(#{margs[0].location.slice}, TEPPROXY_#{pv[:idx]})"
+          return
+        end
+      end
+    end
+
+    # Only bare top-level method calls (no receiver) are candidates
+    # for DSL handling -- `get '/'`, `before do`, `set :public_dir`,
+    # etc. A call with a receiver (`$arr.delete_at(0)`,
+    # `something.frob`) is just user code: pass it through verbatim
+    # so spinel sees it at program load.
+    if call?(node) && node.receiver.nil?
+      result = handle_top_call(node, routes, websockets, mcp_tools, mcp_resources, filters, not_founds, config, warnings, passthrough, input_path, inlined_seen)
+      startup_block = result if result.is_a?(Hash) && result[:kind] == :startup
+      return
+    end
+
+    # Modular Sinatra::Base: `class MyApp < Sinatra::Base; ...; end`.
+    # Unwrap the body so `get '/'`, `before do`, etc. inside register
+    # against the global Tep app -- v0.1 doesn't run multiple apps
+    # in parallel, but the source-level shape is preserved.
+    if node.is_a?(Prism::ClassNode) && sinatra_base_class?(node)
+      unwrapped_apps << node.constant_path.location.slice
+      stmts = node.body
+      if stmts.is_a?(Prism::StatementsNode)
+        stmts.body.each { |inner| process.call(inner) }
+      end
+      return
+    end
+
+    # Drop `MyApp.run!` (etc.) when MyApp was just unwrapped.
+    # Without this the passthrough emits `MyApp.run!` and spinel
+    # has no class by that name.
+    if call?(node) && node.receiver
+      recv_src = node.receiver.location.slice
+      if unwrapped_apps.include?(recv_src)
+        return
+      end
+    end
+
+    passthrough << node.location.slice
+  end
+  prog.statements.body.each { |n| process.call(n) }
+
+  # Spinel's require_relative is finicky about long paths and absolute
+  # paths -- both fail silently. So we inline the whole tep library
+  # text into the generated file instead of relying on require_relative
+  # at build time.
+  out = []
+  out << "# Generated by tep #{Time.now.strftime('%Y-%m-%d %H:%M:%S')} from #{File.basename(input_path)}"
+  out << inlined_tep_library
+  out << ""
+
+  # Compile-time asset bundling: anything under `<app_dir>/assets/`
+  # is read into a Tep::Assets _add call. The bytes ride in the
+  # binary as Ruby string literals; mime is inferred by extension.
+  # See lib/tep/assets.rb for the runtime side.
+  asset_lines = embed_assets(input_path, warnings)
+  unless asset_lines.empty?
+    out << "# --- bundled assets ---"
+    out.concat(asset_lines)
+    out << ""
+  end
+
+  # Top-level non-DSL statements (constants, classes, defs, ...).
+  # Emitted verbatim before any DSL registrations so handler bodies
+  # can refer to them.
+  # Proxy block-DSL subclasses (#88). Emitted BEFORE passthrough so
+  # the rewritten `var = TepProxy_<idx>.new(...)` assignment (which
+  # stays in passthrough, in its original position so its upstream
+  # argument can reference earlier top-level code) finds the class
+  # defined. Each subclass's imeths are the user's `.before` /
+  # `.after` / `.on_stream_chunk` / `.on_stream_end` /
+  # `.stream_request?` block bodies, lowered verbatim with the user's
+  # param names -- a thin 1:1 sugar over the subclass-override form.
+  # Method bodies run at request time, so referencing user constants
+  # defined later in passthrough is fine. A hookless proxy still gets
+  # a (trivial) subclass so its assignment resolves.
+  unless proxies.empty?
+    out << "# --- proxy block-DSL subclasses (#88) ---"
+    proxies.each do |p|
+      out << "class TepProxy_#{p[:idx]} < Tep::Proxy"
+      p[:hooks].each do |dsl_name, info|
+        imeth = PROXY_HOOK_IMETH[dsl_name]
+        out << "  def #{imeth}(#{info[:params]})"
+        out << indent(rewrite_block(info[:src], force_string: false), 4)
+        out << "  end"
+      end
+      out << "end"
+    end
+    out << ""
+  end
+
+  unless passthrough.empty?
+    out << "# --- top-level passthrough from #{File.basename(input_path)} ---"
+    passthrough.each { |s| out << s }
+    out << ""
+  end
+
+  # Build-time ERB compile. Each referenced view becomes a top-level
+  # method `tep_view_<name>(locals)` that returns the rendered string.
+  # Resolution order: file-based (views/<name>.erb) > inline (after
+  # `__END__`, `@@ name` blocks).
+  unless views_used.empty?
+    views_dir = config[:views] || File.join(File.dirname(input_path), "views")
+    views_used.each do |vn|
+      vp = File.join(views_dir, "#{vn}.erb")
+      tmpl = nil
+      if File.exist?(vp)
+        tmpl = File.read(vp)
+      elsif inline_views.key?(vn)
+        tmpl = inline_views[vn]
+      end
+      if tmpl.nil?
+        warnings << "view :#{vn} -- not found in #{vp} nor in inline `@@` templates; emitting empty stub"
+        out << "def tep_view_#{vn}(locals, ivars); \"\"; end"
+        next
+      end
+      out << "def tep_view_#{vn}(locals, ivars)"
+      out << "  " + erb_to_ruby_body(tmpl)
+      out << "end"
+      out << ""
+    end
+  end
+
+  # Same loop for mustache views: file-based (.mustache) > inline
+  # (`@@ name` blocks). Documented subset only -- `{{var}}`,
+  # `{{{var}}}`, `{{!comment}}`, `{{@ivar}}`. Sections / partials /
+  # lambdas are deliberately not implemented (they'd need iterable
+  # locals, which clashes with tep's String=>String view-arg model).
+  unless mustaches_used.empty?
+    views_dir = config[:views] || File.join(File.dirname(input_path), "views")
+    mustaches_used.each do |vn|
+      vp = File.join(views_dir, "#{vn}.mustache")
+      tmpl = nil
+      if File.exist?(vp)
+        tmpl = File.read(vp)
+      elsif inline_views.key?(vn)
+        tmpl = inline_views[vn]
+      end
+      if tmpl.nil?
+        warnings << "mustache :#{vn} -- not found in #{vp} nor in inline `@@` templates; emitting empty stub"
+        out << "def tep_mustache_#{vn}(locals, ivars); \"\"; end"
+        next
+      end
+      out << "def tep_mustache_#{vn}(locals, ivars)"
+      out << "  " + mustache_to_ruby_body(tmpl)
+      out << "end"
+      out << ""
+    end
+  end
+
+  # Build Handler subclasses for routes. For regex routes we bake the
+  # regex literal directly into the same Handler subclass, exposing
+  # is_regex? / re_match? / re_capture for the router to use; this
+  # lets us keep a single routes table (one class type) and rely on
+  # spinel's cls_id virtual dispatch on the handler.
+  routes.each_with_index do |r, i|
+    cname = "TepRoute_#{i}"
+    body  = rewrite_block(r[:block_src])
+    out << "class #{cname} < Tep::Handler"
+    out << "  def handle(req, res)"
+    out << indent(body, 4)
+    out << "  end"
+    if r[:regex]
+      lit = "%r{#{r[:regex]}}"
+      out << "  def is_regex?; true; end"
+      out << "  def re_match?(path); !!(path =~ #{lit}); end"
+      out << "  def re_capture(path)"
+      out << "    path =~ #{lit}"
+      out << "    [$1.to_s, $2.to_s, $3.to_s, $4.to_s, $5.to_s, $6.to_s, $7.to_s, $8.to_s, $9.to_s]"
+      out << "  end"
+    end
+    out << "end"
+    out << ""
+    r[:cls] = cname
+  end
+
+  # Multiple `before do` / `after do` blocks fold into a single
+  # composite Filter subclass per kind -- spinel's PtrArray of
+  # mixed Filter subclasses can't dispatch virtually, and the App
+  # holds a single before/after slot.
+  filter_classes = {}
+  filters.each do |kind, fs|
+    next if fs.empty?
+    cname = "TepFilters_#{kind}"
+    out << "class #{cname} < Tep::Filter"
+    out << "  def #{kind}(req, res)"
+    fs.each_with_index do |f, i|
+      body = rewrite_block(f[:block_src], force_string: false)
+      out << "    # filter #{kind} ##{i}"
+      out << indent(body, 4)
+    end
+    out << "    0"
+    out << "  end"
+    out << "end"
+    out << ""
+    filter_classes[kind] = cname
+  end
+
+  not_founds.each_with_index do |n, i|
+    cname = "TepNotFound_#{i}"
+    body  = rewrite_block(n[:block_src])
+    out << "class #{cname} < Tep::Handler"
+    out << "  def handle(req, res)"
+    out << indent(body, 4)
+    out << "  end"
+    out << "end"
+    out << ""
+    n[:cls] = cname
+  end
+
+  # WebSocket route synthesis. Each `websocket '/path' do |ws|
+  # on_open { ... }; on_message { ... }; ... end` becomes:
+  #   - one Tep::WebSocket::Handler subclass per on_X event with the
+  #     user's block body as handle_event(evt), with `<ws_name> = @ws`
+  #     bound at the top so the user's references just work.
+  #   - one Tep::Handler subclass for the upgrade route that runs the
+  #     handshake check, wires the per-event callbacks onto a fresh
+  #     Driver, and flips res.start_websocket so the server runs the
+  #     recv loop in lieu of writing a normal response.
+  # WS only works under Tep::Server::Scheduled; the runtime warns
+  # (and the blocking server returns 501) if the route fires there.
+  websockets.each_with_index do |w, i|
+    base = "TepWS_#{i}"
+    cbs  = {}
+    w[:events].each do |ev, info|
+      ev_cls = "#{base}_#{ev}"
+      body = rewrite_block(info[:src], force_string: false)
+      out << "class #{ev_cls} < Tep::WebSocket::Handler"
+      out << "  def initialize"
+      out << "    super"
+      out << "    @ws = Tep::WebSocket::Driver.new(0)"
+      out << "  end"
+      out << "  attr_accessor :ws"
+      out << "  def handle_event(#{info[:evt_param]})"
+      out << "    #{w[:ws_param]} = @ws"
+      out << "    req = @req"
+      out << indent(body, 4)
+      out << "    0"
+      out << "  end"
+      out << "end"
+      out << ""
+      cbs[ev] = ev_cls
+    end
+
+    rt_cls = "#{base}_Route"
+    out << "class #{rt_cls} < Tep::Handler"
+    out << "  def handle(req, res)"
+    out << "    hs = Tep::WebSocket::Handshake.check(req)"
+    out << "    if !hs.valid"
+    out << "      res.set_status(400)"
+    out << "      return \"\""
+    out << "    end"
+    out << "    drv = Tep::WebSocket::Driver.new(0)"
+    cbs.each do |ev, cls|
+      slot = ev.sub("on_", "set_on_")
+      out << "    _cb_#{ev} = #{cls}.new"
+      out << "    _cb_#{ev}.ws = drv"
+      out << "    _cb_#{ev}.req = req"
+      out << "    drv.#{slot}(_cb_#{ev})"
+    end
+    out << "    res.start_websocket(hs.accept_key, drv)"
+    out << "    \"\""
+    out << "  end"
+    out << "end"
+    out << ""
+    w[:cls] = rt_cls
+  end
+
+  # Tep.live emission. For each `Tep.live "/path", ViewClass`:
+  #   * TepLive_N_Get handles GET /path -- instantiate view per
+  #     request, mount(req), wrap in render_page targeting /path/ws.
+  #   * TepLive_N_WsOpen / TepLive_N_WsMessage are Handler subclasses;
+  #     each connection's route handler creates ONE ViewClass instance
+  #     and stashes it on both handlers so on_open and on_message
+  #     share state. on_open mounts + subscribes to view.topic (when
+  #     non-empty) + sends initial render; on_message dispatches the
+  #     JSON event + sends re-render.
+  #   * TepLive_N_WsRoute handles the WS upgrade at /path/ws.
+  live_views.each_with_index do |lv, i|
+    base   = "TepLive_#{i}"
+    klass  = lv[:view_class]
+    path   = lv[:path]
+    ws_path = path + "/ws"
+
+    get_cls = "#{base}_Get"
+    out << "class #{get_cls} < Tep::Handler"
+    out << "  def handle(req, res)"
+    out << "    v = #{klass}.new"
+    out << "    v.mount(req)"
+    out << "    Tep::LiveView.render_page(v.render, #{ws_path.inspect})"
+    out << "  end"
+    out << "end"
+    out << ""
+
+    open_cls = "#{base}_WsOpen"
+    out << "class #{open_cls} < Tep::WebSocket::Handler"
+    out << "  attr_accessor :ws, :view"
+    out << "  def initialize"
+    out << "    super"
+    out << "    @ws   = Tep::WebSocket::Driver.new(0)"
+    out << "    @view = #{klass}.new"
+    out << "  end"
+    out << "  def handle_event(evt)"
+    out << "    ws   = @ws"
+    out << "    req  = @req"
+    out << "    view = @view"
+    out << "    view.mount(req)"
+    out << "    t = view.topic"
+    out << "    if t.length > 0"
+    out << "      Tep::Broadcast.subscribe_ws(t, ws.fd)"
+    out << "    end"
+    out << "    ws.text(view.render)"
+    out << "    0"
+    out << "  end"
+    out << "end"
+    out << ""
+
+    msg_cls = "#{base}_WsMessage"
+    out << "class #{msg_cls} < Tep::WebSocket::Handler"
+    out << "  attr_accessor :ws, :view"
+    out << "  def initialize"
+    out << "    super"
+    out << "    @ws   = Tep::WebSocket::Driver.new(0)"
+    out << "    @view = #{klass}.new"
+    out << "  end"
+    out << "  def handle_event(evt)"
+    out << "    ws   = @ws"
+    out << "    req  = @req"
+    out << "    view = @view"
+    out << "    view.dispatch_event_json(evt.data, req)"
+    out << "    ws.text(view.render)"
+    out << "    0"
+    out << "  end"
+    out << "end"
+    out << ""
+
+    ws_route_cls = "#{base}_WsRoute"
+    out << "class #{ws_route_cls} < Tep::Handler"
+    out << "  def handle(req, res)"
+    out << "    hs = Tep::WebSocket::Handshake.check(req)"
+    out << "    if !hs.valid"
+    out << "      res.set_status(400)"
+    out << "      return \"\""
+    out << "    end"
+    out << "    drv = Tep::WebSocket::Driver.new(0)"
+    out << "    v = #{klass}.new"
+    out << "    _cb_on_open = #{open_cls}.new"
+    out << "    _cb_on_open.ws   = drv"
+    out << "    _cb_on_open.req  = req"
+    out << "    _cb_on_open.view = v"
+    out << "    drv.set_on_open(_cb_on_open)"
+    out << "    _cb_on_message = #{msg_cls}.new"
+    out << "    _cb_on_message.ws   = drv"
+    out << "    _cb_on_message.req  = req"
+    out << "    _cb_on_message.view = v"
+    out << "    drv.set_on_message(_cb_on_message)"
+    out << "    res.start_websocket(hs.accept_key, drv)"
+    out << "    \"\""
+    out << "  end"
+    out << "end"
+    out << ""
+
+    lv[:get_cls] = get_cls
+    lv[:ws_cls]  = ws_route_cls
+    lv[:ws_path] = ws_path
+  end
+
+  # Tep::MCP emission. For each `mcp_tool 'name', "desc" do ... end`:
+  #
+  #   * TepMCP_Tools.call_<i>(req, args_json) -- static cmeth that
+  #     parses args out of args_json (via Tep::Json.get_str/get_int),
+  #     binds them as locals, and runs the user's on_call body. The
+  #     body is rewritten the same way route bodies are (req / res /
+  #     params rewrites). Returns Tep::MCP::Result.
+  #   * TepMCP_<i>_HttpRoute -- POST /tools/<name>, takes the args
+  #     as the JSON request body, returns the Result's text directly
+  #     (with the right status / content-type).
+  #
+  # After all tools, two more classes:
+  #
+  #   * TepMCP_Dispatcher -- POST /mcp, parses the JSON-RPC envelope
+  #     and dispatches `initialize` / `tools/list` / `tools/call` by
+  #     statically-elif'd name. No PtrArray<Tool> involvement -- each
+  #     tool's call cmeth is referenced literally so spinel can
+  #     trace types end-to-end.
+  #   * TepMCP_LlmsTxt -- GET /llms.txt, returns the tool catalog as
+  #     a markdown index any LLM-friendly client can fetch.
+  if !mcp_tools.empty? || !mcp_resources.empty?
+    # Build the tools/list JSON once, at translate time. Each entry
+    # is {name, description, inputSchema}; inputSchema follows the
+    # JSON Schema object form with property type/description per
+    # param. Keep the schema flat (no $ref, no nested objects); MCP
+    # clients all accept this minimal shape.
+    tools_list_json_parts = []
+    mcp_tools.each do |t|
+      props_parts = []
+      t[:params].each do |p|
+        json_type =
+          case p[:type]
+          when "Integer" then "integer"
+          when "Float"   then "number"
+          else                "string"
+          end
+        props_parts << %("#{p[:name]}":{"type":"#{json_type}","description":#{p[:desc].inspect}})
+      end
+      required_arr = t[:params].map { |p| %("#{p[:name]}") }.join(",")
+      schema_json = %({"type":"object","properties":{#{props_parts.join(",")}},"required":[#{required_arr}]})
+      tools_list_json_parts << %({"name":"#{t[:name]}","description":#{t[:description].inspect},"inputSchema":#{schema_json}})
+    end
+    tools_list_json = "[" + tools_list_json_parts.join(",") + "]"
+
+    out << "module TepMCP_Tools"
+    mcp_tools.each_with_index do |t, i|
+      body = rewrite_block(t[:call_body], force_string: false)
+      out << "  def self.call_#{i}(req, args_json)"
+      # Per-cap may? checks (chunk 5.2). One inline check per cap
+      # rather than a loop -- spinel's symbol-array iteration is
+      # uneven, and a flat sequence of identical branches is the
+      # safest emit. Anonymous identity has empty caps so any
+      # capped tool denies anonymous callers cleanly.
+      t[:caps].each do |cap|
+        out << "    if !req.identity.may?(:#{cap})"
+        out << "      return Tep::MCP.error(\"missing capability: #{cap}\")"
+        out << "    end"
+      end
+      t[:params].each do |p|
+        if p[:type] == "Integer"
+          out << "    #{p[:name]} = Tep::Json.get_int(args_json, #{p[:name].inspect})"
+        elsif p[:type] == "Float"
+          out << "    #{p[:name]} = Tep::Json.get_str(args_json, #{p[:name].inspect}).to_f"
+        else
+          out << "    #{p[:name]} = Tep::Json.get_str(args_json, #{p[:name].inspect})"
+        end
+      end
+      out << indent(body, 4)
+      out << "  end"
+      out << ""
+    end
+    out << "end"
+    out << ""
+
+    mcp_tools.each_with_index do |t, i|
+      http_cls = "TepMCP_#{i}_HttpRoute"
+      out << "class #{http_cls} < Tep::Handler"
+      out << "  def handle(req, res)"
+      out << "    args_json = req.raw_body"
+      out << "    r = TepMCP_Tools.call_#{i}(req, args_json)"
+      out << "    res.headers[\"Content-Type\"] = \"text/plain; charset=utf-8\""
+      out << "    if r.is_error == 1"
+      out << "      res.set_status(400)"
+      out << "    end"
+      out << "    r.text"
+      out << "  end"
+      out << "end"
+      out << ""
+      t[:http_cls] = http_cls
+    end
+
+    tools_const = "TepMCP_TOOLS_LIST_JSON"
+    out << "#{tools_const} = #{tools_list_json.inspect}"
+    out << ""
+
+    # Per-resource read cmeths + HTTP-direct Handler subclasses
+    # (chunk 5.3). One Handler per resource for GET /resources/<name>
+    # plus a sibling cmeth `TepMCP_Resources.read_<i>(req)` that the
+    # dispatcher's resources/read arm calls statically (no
+    # PtrArray<Resource> dispatch, same pattern as tools).
+    unless mcp_resources.empty?
+      out << "module TepMCP_Resources"
+      mcp_resources.each_with_index do |rdef, i|
+        body = rewrite_block(rdef[:read_body], force_string: false)
+        out << "  def self.read_#{i}(req)"
+        out << indent(body, 4)
+        out << "  end"
+        out << ""
+      end
+      out << "end"
+      out << ""
+
+      mcp_resources.each_with_index do |rdef, i|
+        http_cls = "TepMCP_Res_#{i}_HttpRoute"
+        out << "class #{http_cls} < Tep::Handler"
+        out << "  def handle(req, res)"
+        out << "    c = TepMCP_Resources.read_#{i}(req)"
+        out << "    res.headers[\"Content-Type\"] = c.mime"
+        out << "    c.text"
+        out << "  end"
+        out << "end"
+        out << ""
+        rdef[:http_cls] = http_cls
+      end
+
+      # resources/list array, pre-built at translate time.
+      res_list_parts = mcp_resources.map do |rdef|
+        %({"uri":#{rdef[:name].inspect},"name":#{rdef[:name].inspect},"description":#{rdef[:description].inspect},"mimeType":"text/plain"})
+      end
+      resources_list_json = "[" + res_list_parts.join(",") + "]"
+      resources_const = "TepMCP_RESOURCES_LIST_JSON"
+      out << "#{resources_const} = #{resources_list_json.inspect}"
+      out << ""
+    end
+
+    server_name    = (config[:mcp_server_name] || "tep-mcp-server").to_s
+    server_version = config[:mcp_server_version] || begin
+      vfile = File.read(File.expand_path("../lib/tep/version.rb", __dir__))
+      vfile[/VERSION\s*=\s*"([^"]+)"/, 1] || "0.0.0"
+    rescue
+      "0.0.0"
+    end
+
+    out << "class TepMCP_Dispatcher < Tep::Handler"
+    out << "  def handle(req, res)"
+    out << "    res.headers[\"Content-Type\"] = \"application/json\""
+    out << "    body = req.raw_body"
+    out << "    method = Tep::Json.get_str(body, \"method\")"
+    out << "    req_id = Tep::Json.get_int(body, \"id\")"
+    out << "    if method == \"initialize\""
+    out << "      return Tep::MCP.initialize_envelope(req_id, #{server_name.inspect}, #{server_version.inspect})"
+    out << "    end"
+    # notifications/initialized is a JSON-RPC notification (no
+    # response per spec). Return 204 No Content with an empty body
+    # to satisfy HTTP while honoring the no-response semantics.
+    out << "    if method == \"notifications/initialized\""
+    out << "      res.set_status(204)"
+    out << "      return \"\""
+    out << "    end"
+    out << "    if method == \"tools/list\""
+    out << "      return Tep::MCP.tools_list_envelope(req_id, #{tools_const})"
+    out << "    end"
+    out << "    if method == \"tools/call\""
+    out << "      params = Tep::MCP.nested_extract(body, \"params\")"
+    out << "      tool_name = Tep::Json.get_str(params, \"name\")"
+    out << "      args = Tep::MCP.nested_extract(params, \"arguments\")"
+    mcp_tools.each_with_index do |t, i|
+      out << "      if tool_name == #{t[:name].inspect}"
+      out << "        r = TepMCP_Tools.call_#{i}(req, args)"
+      out << "        return Tep::MCP.tools_call_envelope(req_id, r.text, r.is_error)"
+      out << "      end"
+    end
+    out << "      return Tep::MCP.unknown_tool_envelope(req_id, tool_name)"
+    out << "    end"
+    unless mcp_resources.empty?
+      out << "    if method == \"resources/list\""
+      out << "      return Tep::MCP.resources_list_envelope(req_id, TepMCP_RESOURCES_LIST_JSON)"
+      out << "    end"
+      out << "    if method == \"resources/read\""
+      out << "      res_params = Tep::MCP.nested_extract(body, \"params\")"
+      out << "      res_uri = Tep::Json.get_str(res_params, \"uri\")"
+      mcp_resources.each_with_index do |rdef, i|
+        out << "      if res_uri == #{rdef[:name].inspect}"
+        out << "        c = TepMCP_Resources.read_#{i}(req)"
+        out << "        return Tep::MCP.resources_read_envelope(req_id, c.uri, c.mime, c.text)"
+        out << "      end"
+      end
+      out << "      return Tep::MCP.unknown_resource_envelope(req_id, res_uri)"
+      out << "    end"
+    end
+    out << "    Tep::MCP.method_not_found_envelope(req_id, method)"
+    out << "  end"
+    out << "end"
+    out << ""
+
+    # openapi.json: OpenAPI 3.0 description of the HTTP-direct
+    # surface (tools at POST /tools/<name>, resources at GET
+    # /resources/<name>). Generated at translate time as a single
+    # constant string the handler returns verbatim. Mirrors what
+    # MCP clients see at tools/list + resources/list, but in the
+    # universal OpenAPI shape so non-MCP agents (and ordinary
+    # OpenAPI tooling) can consume the same catalog.
+    paths_parts = []
+    mcp_tools.each do |t|
+      props_parts = t[:params].map do |p|
+        json_type =
+          case p[:type]
+          when "Integer" then "integer"
+          when "Float"   then "number"
+          else                "string"
+          end
+        %("#{p[:name]}":{"type":"#{json_type}","description":#{p[:desc].inspect}})
+      end
+      required_arr = t[:params].map { |p| %("#{p[:name]}") }.join(",")
+      schema_json = %({"type":"object","properties":{#{props_parts.join(",")}},"required":[#{required_arr}]})
+      paths_parts << %("/tools/#{t[:name]}":{"post":{"summary":#{t[:description].inspect},"requestBody":{"required":true,"content":{"application/json":{"schema":#{schema_json}}}},"responses":{"200":{"description":"tool text result","content":{"text/plain":{}}},"400":{"description":"tool error"}}}})
+    end
+    mcp_resources.each do |rdef|
+      paths_parts << %("/resources/#{rdef[:name]}":{"get":{"summary":#{rdef[:description].inspect},"responses":{"200":{"description":"resource content","content":{"text/plain":{}}}}}})
+    end
+    openapi_json =
+      %({"openapi":"3.0.3","info":{"title":#{server_name.inspect},"version":#{server_version.inspect}},) +
+      %("paths":{#{paths_parts.join(",")}}})
+    openapi_const = "TepMCP_OPENAPI_JSON"
+    out << "#{openapi_const} = #{openapi_json.inspect}"
+    out << ""
+    out << "class TepMCP_OpenAPI < Tep::Handler"
+    out << "  def handle(req, res)"
+    out << "    res.headers[\"Content-Type\"] = \"application/json\""
+    out << "    #{openapi_const}"
+    out << "  end"
+    out << "end"
+    out << ""
+
+    # llms.txt: minimal markdown index of the tool + resource
+    # catalogs. Stable ASCII so even a non-LLM reader can scan it.
+    llms_lines = ["# " + server_name, "", "MCP-endpoint: /mcp", "OpenAPI: /openapi.json", ""]
+    unless mcp_tools.empty?
+      llms_lines << "## Tools"
+      llms_lines << ""
+      mcp_tools.each do |t|
+        llms_lines << "- " + t[:name] + " -- " + t[:description]
+      end
+      llms_lines << ""
+    end
+    unless mcp_resources.empty?
+      llms_lines << "## Resources"
+      llms_lines << ""
+      mcp_resources.each do |rdef|
+        llms_lines << "- " + rdef[:name] + " -- " + rdef[:description]
+      end
+      llms_lines << ""
+    end
+    llms_body = llms_lines.join("\n")
+
+    out << "class TepMCP_LlmsTxt < Tep::Handler"
+    out << "  def handle(req, res)"
+    out << "    res.headers[\"Content-Type\"] = \"text/markdown; charset=utf-8\""
+    out << "    #{llms_body.inspect}"
+    out << "  end"
+    out << "end"
+    out << ""
+  end
+
+  # Registrations.
+  out << Tep_public_dir(config[:public_dir]) if config[:public_dir]
+  out << %(Tep.before #{filter_classes["before"]}.new) if filter_classes["before"]
+  out << %(Tep.after  #{filter_classes["after"]}.new)  if filter_classes["after"]
+  not_founds.each        { |n| out << %(Tep.not_found #{n[:cls]}.new) }
+  routes.each do |r|
+    if r[:regex]
+      # Regex routes go through the literal-route DSL with an unused
+      # `pattern` arg (the matcher uses re_match? on the handler).
+      out << %(Tep.#{r[:verb].downcase} "" , #{r[:cls]}.new)
+    else
+      # Optional segments `(/:foo)`: expand to the cartesian product
+      # of "include each optional or not", registering one route per
+      # combination with the same handler class. Bodies share state
+      # via the single class; missing optional captures show up as
+      # empty strings in `params[...]`.
+      paths = expand_optional_segments(r[:path])
+      paths.each do |p|
+        out << %(Tep.#{r[:verb].downcase} #{p.inspect}, #{r[:cls]}.new)
+      end
+    end
+  end
+  websockets.each do |w|
+    out << %(Tep.get #{w[:path].inspect}, #{w[:cls]}.new)
+  end
+  live_views.each do |lv|
+    out << %(Tep.get #{lv[:path].inspect},    #{lv[:get_cls]}.new)
+    out << %(Tep.get #{lv[:ws_path].inspect}, #{lv[:ws_cls]}.new)
+  end
+  if !mcp_tools.empty? || !mcp_resources.empty?
+    mcp_tools.each do |t|
+      out << %(Tep.post "/tools/#{t[:name]}", #{t[:http_cls]}.new)
+    end
+    mcp_resources.each do |rdef|
+      out << %(Tep.get "/resources/#{rdef[:name]}", #{rdef[:http_cls]}.new)
+    end
+    out << %(Tep.post "/mcp", TepMCP_Dispatcher.new)
+    out << %(Tep.get  "/llms.txt", TepMCP_LlmsTxt.new)
+    out << %(Tep.get  "/openapi.json", TepMCP_OpenAPI.new)
+  end
+  out << ""
+
+  # `on_start do ... end` body runs once before the accept loop.
+  # Inline as plain top-level code so spinel sees it as program-load
+  # statements, no class/handler wrapping needed.
+  if startup_block
+    out << "# --- on_start ---"
+    out << rewrite_block(startup_block[:src], force_string: false)
+    out << ""
+  end
+
+  # CLI option parsing -- emitted at top level so spinel's codegen
+  # actually declares `sp_argv` (it skips it for method-local ARGV
+  # references). Every translated app picks up `-p`, `-w`, `-q`.
+  scheduled = config[:scheduler] == :scheduled
+  out << <<~RB
+    __port = #{config[:port] || 4567}
+    __workers = #{config[:workers] || 1}
+    __quiet = false
+    __scheduled = #{scheduled ? 'true' : 'false'}
+    __i = 0
+    while __i < ARGV.length
+      __a = ARGV[__i]
+      if __a == "-p" && __i + 1 < ARGV.length
+        __port = ARGV[__i + 1].to_i
+        __i += 2
+      elsif __a == "-w" && __i + 1 < ARGV.length
+        __workers = ARGV[__i + 1].to_i
+        __i += 2
+      elsif __a == "-q"
+        __quiet = true
+        __i += 1
+      elsif __a == "-s"
+        # Phase 1.5 opt-in: scheduled fiber-per-connection server
+        # (vs the default prefork-blocking-one-conn-per-worker shape).
+        __scheduled = true
+        __i += 1
+      else
+        __i += 1
+      end
+    end
+    Tep.run!(__port, __workers, __quiet, __scheduled)
+  RB
+  out << ""
+
+  warnings.each { |w| warn "tep: #{w}" }
+
+  out.join("\n")
+end
+
+def Tep_public_dir(path)
+  abs = File.expand_path(path, Dir.pwd)
+  %(Tep.public_dir #{abs.inspect})
+end
+
+def call?(node)
+  node.is_a?(Prism::CallNode)
+end
+
+# `mcp_tool 'name', "description" do ... end` — collect the tool's
+# input-param declarations + the on_call body. Each `param :sym,
+# Type, "desc"` line inside the block records one parameter (with
+# optional `default:` and `enum:` keyword args, kept verbatim into
+# the JSON Schema we emit). Each `on_call do |kwargs| ... end`
+# block becomes the tool's invocation body.
+# `mcp_resource 'name', "description" do; on_read do ... end; end`
+# (chunk 5.3). Each resource gets a read-only fetch endpoint at
+# `GET /resources/<name>` plus a `resources/list` + `resources/read`
+# dispatch arm via the /mcp dispatcher. The on_read body returns
+# Tep::MCP::ResourceContent (built via Tep::MCP.resource_text). No
+# URI templating + no streaming in this chunk -- both defer.
+def handle_mcp_resource(node, mcp_resources, warnings)
+  args  = node.arguments&.arguments || []
+  block = node.block
+  unless block.is_a?(Prism::BlockNode)
+    return warnings << "skipped mcp_resource -- needs a `do ... end` block"
+  end
+  if args.length < 2
+    return warnings << "skipped mcp_resource -- needs (\"name\", \"description\", &block)"
+  end
+  name_node = args[0]
+  desc_node = args[1]
+  unless name_node.is_a?(Prism::StringNode)
+    return warnings << "skipped mcp_resource -- first arg must be a string literal name"
+  end
+  unless desc_node.is_a?(Prism::StringNode)
+    return warnings << "skipped mcp_resource -- second arg must be a string literal description"
+  end
+
+  read_body = nil
+  body = block.body
+  if body.is_a?(Prism::StatementsNode)
+    body.body.each do |stmt|
+      next unless call?(stmt) && stmt.receiver.nil?
+      cname = stmt.name.to_s
+      if cname == "on_read"
+        inner = stmt.block
+        unless inner.is_a?(Prism::BlockNode)
+          warnings << "mcp_resource #{name_node.unescaped}: on_read needs a `do ... end` block"
+          next
+        end
+        read_body = block_source(inner)
+      else
+        warnings << "mcp_resource #{name_node.unescaped}: ignored unrecognized statement `#{cname}`"
+      end
+    end
+  end
+
+  if read_body.nil?
+    return warnings << "skipped mcp_resource #{name_node.unescaped} -- missing on_read do ... end"
+  end
+
+  mcp_resources << {
+    name:        name_node.unescaped,
+    description: desc_node.unescaped,
+    read_body:   read_body,
+  }
+end
+
+def handle_mcp_tool(node, mcp_tools, warnings)
+  args  = node.arguments&.arguments || []
+  block = node.block
+  unless block.is_a?(Prism::BlockNode)
+    return warnings << "skipped mcp_tool -- needs a `do ... end` block"
+  end
+  if args.length < 2
+    return warnings << "skipped mcp_tool -- needs (\"name\", \"description\", &block)"
+  end
+  name_node = args[0]
+  desc_node = args[1]
+  unless name_node.is_a?(Prism::StringNode)
+    return warnings << "skipped mcp_tool -- first arg must be a string literal name"
+  end
+  unless desc_node.is_a?(Prism::StringNode)
+    return warnings << "skipped mcp_tool -- second arg must be a string literal description"
+  end
+
+  # Optional caps: [:foo, :bar] keyword (chunk 5.2). Required
+  # capabilities checked against req.identity.may?(...) at the
+  # top of call_<i>. Missing any -> Tep::MCP.error("missing
+  # capability: <name>") returned without running the on_call
+  # body.
+  caps = []
+  if args.length >= 3 && args[2].is_a?(Prism::KeywordHashNode)
+    args[2].elements.each do |el|
+      next unless el.is_a?(Prism::AssocNode)
+      k = el.key
+      next unless k.is_a?(Prism::SymbolNode) && k.value.to_s == "caps"
+      v = el.value
+      unless v.is_a?(Prism::ArrayNode)
+        warnings << "mcp_tool #{name_node.unescaped}: caps: must be an array literal of symbols"
+        next
+      end
+      v.elements.each do |sym|
+        unless sym.is_a?(Prism::SymbolNode)
+          warnings << "mcp_tool #{name_node.unescaped}: caps: entry must be a symbol literal"
+          next
+        end
+        caps << sym.value.to_s
+      end
+    end
+  end
+
+  params      = []
+  call_body   = nil
+  call_kwargs = []
+  body = block.body
+  if body.is_a?(Prism::StatementsNode)
+    body.body.each do |stmt|
+      next unless call?(stmt) && stmt.receiver.nil?
+      cname = stmt.name.to_s
+      if cname == "param"
+        pargs = stmt.arguments&.arguments || []
+        if pargs.length < 3
+          warnings << "mcp_tool #{name_node.unescaped}: skipped param -- needs (:sym, Type, \"desc\", default:, enum:)"
+          next
+        end
+        unless pargs[0].is_a?(Prism::SymbolNode)
+          warnings << "mcp_tool #{name_node.unescaped}: param name must be a symbol"
+          next
+        end
+        unless pargs[1].is_a?(Prism::ConstantReadNode)
+          warnings << "mcp_tool #{name_node.unescaped}: param type must be a bare constant (String/Integer/Float)"
+          next
+        end
+        unless pargs[2].is_a?(Prism::StringNode)
+          warnings << "mcp_tool #{name_node.unescaped}: param description must be a string literal"
+          next
+        end
+        type_name = pargs[1].name.to_s
+        unless %w[String Integer Float].include?(type_name)
+          warnings << "mcp_tool #{name_node.unescaped}: param type #{type_name} not supported (use String / Integer / Float)"
+          next
+        end
+        # Optional `default:` keyword (chunk 5.1 only honors default
+        # for input-schema annotation; the on_call body still needs
+        # to handle missing values defensively via the zero default).
+        params << {
+          name: pargs[0].value.to_s,
+          type: type_name,
+          desc: pargs[2].unescaped,
+        }
+      elsif cname == "on_call"
+        inner = stmt.block
+        unless inner.is_a?(Prism::BlockNode)
+          warnings << "mcp_tool #{name_node.unescaped}: on_call needs a `do |kwargs| ... end` block"
+          next
+        end
+        call_body = block_source(inner)
+        # Capture the keyword-param names from the block signature
+        # so the generated cmeth can pass them by-keyword to the
+        # rewritten body. v1 supports keyword params only.
+        ibp = inner.parameters
+        if ibp.is_a?(Prism::BlockParametersNode)
+          ipp = ibp.parameters
+          if ipp.is_a?(Prism::ParametersNode)
+            ipp.keywords.each do |kw|
+              call_kwargs << kw.name.to_s
+            end
+          end
+        end
+      else
+        warnings << "mcp_tool #{name_node.unescaped}: ignored unrecognized statement `#{cname}`"
+      end
+    end
+  end
+
+  if call_body.nil?
+    return warnings << "skipped mcp_tool #{name_node.unescaped} -- missing on_call do ... end"
+  end
+
+  mcp_tools << {
+    name:        name_node.unescaped,
+    description: desc_node.unescaped,
+    caps:        caps,
+    params:      params,
+    call_kwargs: call_kwargs,
+    call_body:   call_body,
+  }
+end
+
+def handle_tep_live(node, live_views, warnings)
+  args = node.arguments&.arguments || []
+  if args.length < 2
+    return warnings << "skipped Tep.live -- needs (\"/path\", ViewClass)"
+  end
+  path = args[0]
+  view = args[1]
+  unless path.is_a?(Prism::StringNode)
+    return warnings << "skipped Tep.live -- first arg must be a string literal path"
+  end
+  unless view.is_a?(Prism::ConstantReadNode) || view.is_a?(Prism::ConstantPathNode)
+    return warnings << "skipped Tep.live -- second arg must be a class constant"
+  end
+  live_views << {
+    path:       path.unescaped,
+    view_class: view.slice,
+  }
+end
+
+# Recursively inline an app-local `require_relative` target. Reads the
+# file; for each `require_relative` IT contains, resolves the path
+# relative to THAT file's own directory and inlines it too. This is what
+# lets `require_relative "vendor/spinel/deps"` work: bundler-spinel's
+# generated deps.rb is itself a list of `require_relative`s (one per
+# vendored gem, in lock order), so a single app-level require pulls in
+# the whole dependency set. `seen` (keyed by absolute path) dedupes
+# shared deps and breaks cycles. Returns the spliced source; a missing
+# target becomes a dropped-marker comment + a warning. Plain `require`
+# lines are left verbatim -- spinel drops them (no load path), which is
+# correct for a self-contained gem; a gem that needs an unvendored
+# require won't link, same as today.
+def inline_require_relative_tree(abs_path, seen, warnings)
+  return "" if seen[abs_path]
+  seen[abs_path] = true
+  dir = File.dirname(abs_path)
+  out = []
+  File.read(abs_path).each_line do |line|
+    m = line.match(/\A\s*require_relative\s+["']([^"']+)["']\s*\z/)
+    if m
+      target = m[1]
+      cand = File.expand_path(target.end_with?(".rb") ? target : target + ".rb", dir)
+      if File.file?(cand)
+        out << "# --- inlined require_relative #{target.inspect} (#{File.basename(cand)}) ---"
+        out << inline_require_relative_tree(cand, seen, warnings)
+      else
+        out << "# (require_relative #{target.inspect} -- not found at #{cand}, dropped)"
+        warnings << "require_relative #{target.inspect} (from #{File.basename(abs_path)}) not found at #{cand}; dropped"
+      end
+    else
+      out << line.rstrip
+    end
+  end
+  out.join("\n")
+end
+
+def handle_top_call(node, routes, websockets, mcp_tools, mcp_resources, filters, not_founds, config, warnings, passthrough, input_path = nil, inlined_seen = nil)
+  inlined_seen ||= {}
+  name = node.name.to_s
+
+  if name == "mcp_tool"
+    handle_mcp_tool(node, mcp_tools, warnings)
+    return
+  end
+
+  if name == "mcp_resource"
+    handle_mcp_resource(node, mcp_resources, warnings)
+    return
+  end
+
+  if name == "websocket"
+    args  = node.arguments&.arguments || []
+    block = node.block
+    first = args.first
+    unless block.is_a?(Prism::BlockNode)
+      return warnings << "skipped websocket -- needs a `do |ws| ... end` block"
+    end
+    unless first.is_a?(Prism::StringNode)
+      return warnings << "skipped websocket -- first arg must be a string literal path"
+    end
+
+    # Extract the block parameter name (`do |ws|` -> "ws"). Used to
+    # let the user's on_X bodies reference the driver by their chosen
+    # name -- we bind `<name> = @ws` at the top of every handler.
+    ws_param = "ws"
+    bparams = block.parameters
+    if bparams.is_a?(Prism::BlockParametersNode)
+      pp = bparams.parameters
+      if pp.is_a?(Prism::ParametersNode) && pp.requireds.first.is_a?(Prism::RequiredParameterNode)
+        ws_param = pp.requireds.first.name.to_s
+      end
+    end
+
+    # Walk the block body looking for `on_<event> do |evt| ... end`
+    # calls; collect each event's block body as its own callback class.
+    events = {}
+    body = block.body
+    if body.is_a?(Prism::StatementsNode)
+      body.body.each do |stmt|
+        next unless call?(stmt) && stmt.receiver.nil?
+        ev = stmt.name.to_s
+        unless WS_EVENTS.include?(ev)
+          warnings << "websocket #{first.unescaped}: unrecognised event `#{ev}` -- ignored"
+          next
+        end
+        inner = stmt.block
+        unless inner.is_a?(Prism::BlockNode)
+          warnings << "websocket #{first.unescaped}: `#{ev}` needs a `do |evt| ... end` block"
+          next
+        end
+        # Capture the event-block param name too, so a user who
+        # writes `|message|` instead of `|evt|` keeps their name.
+        evt_param = "evt"
+        ibp = inner.parameters
+        if ibp.is_a?(Prism::BlockParametersNode)
+          ipp = ibp.parameters
+          if ipp.is_a?(Prism::ParametersNode) && ipp.requireds.first.is_a?(Prism::RequiredParameterNode)
+            evt_param = ipp.requireds.first.name.to_s
+          end
+        end
+        events[ev] = { src: block_source(inner), evt_param: evt_param }
+      end
+    end
+
+    websockets << {
+      path:     first.unescaped,
+      ws_param: ws_param,
+      events:   events,
+    }
+    return
+  end
+
+  if DSL_VERBS.include?(name)
+    args = node.arguments&.arguments || []
+    block = node.block
+    first = args.first
+    return warnings << "skipped #{name} -- needs a `do ... end` block" unless block.is_a?(Prism::BlockNode)
+    if first.is_a?(Prism::StringNode)
+      routes << {
+        verb:      name.upcase,
+        path:      first.unescaped,
+        block_src: block_source(block),
+      }
+      return
+    end
+    if first.is_a?(Prism::RegularExpressionNode)
+      routes << {
+        verb:      name.upcase,
+        regex:     first.unescaped,
+        block_src: block_source(block),
+      }
+      return
+    end
+    return warnings << "skipped #{name} -- first arg must be a string or regex literal"
+  end
+
+  if HOOK_NAMES.include?(name)
+    block = node.block
+    return warnings << "skipped #{name} -- needs a `do ... end` block" unless block.is_a?(Prism::BlockNode)
+    if name == "not_found"
+      not_founds << { block_src: block_source(block) }
+    else
+      filters[name] << { block_src: block_source(block) }
+    end
+    return
+  end
+
+  if name == "on_start"
+    block = node.block
+    return warnings << "skipped on_start -- needs a `do ... end` block" unless block.is_a?(Prism::BlockNode)
+    return { kind: :startup, src: block_source(block) }
+  end
+
+  if name == "on_stop"
+    # tep doesn't have a graceful shutdown path -- the server runs
+    # until SIGINT/SIGTERM ends the process. Honour the spirit by
+    # warning loudly; the block content is dropped.
+    warnings << "on_stop -- tep has no graceful shutdown path; block ignored"
+    return
+  end
+
+  if name == "configure"
+    block = node.block
+    return warnings << "skipped configure -- needs a `do ... end` block" unless block.is_a?(Prism::BlockNode)
+    body  = block_source(block)
+    args  = node.arguments&.arguments || []
+    envs  = args.map { |a| a.is_a?(Prism::SymbolNode) ? a.unescaped : nil }.compact
+    if envs.empty?
+      passthrough << "# --- configure ---"
+      passthrough << body
+    else
+      # spinel doesn't have ENV.fetch with a default; ENV[k] returns
+      # nil for missing keys, but we'd then `.include?(nil)` which
+      # works (returns false). Default env "development" is matched
+      # only when TEP_ENV is unset; users who want dev-specific
+      # `configure :development` should set TEP_ENV explicitly.
+      env_lits = envs.map(&:inspect).join(", ")
+      passthrough << "# --- configure :#{envs.join(', :')} ---"
+      passthrough << "_tep_env = ENV[\"TEP_ENV\"]"
+      passthrough << "_tep_env = \"development\" if _tep_env.nil? || _tep_env.length == 0"
+      passthrough << "if [#{env_lits}].include?(_tep_env)"
+      passthrough << body
+      passthrough << "end"
+    end
+    return
+  end
+
+  if name == "erb"
+    # Track which views are referenced; the translator compiles the
+    # corresponding .erb files into top-level Ruby methods. A bare
+    # top-level `erb :name` is unusual but harmless.
+    args = node.arguments&.arguments || []
+    if args.first.is_a?(Prism::SymbolNode)
+      # handled below in the rewrite_block textual pass; no-op here
+    end
+    return
+  end
+
+  if name == "set"
+    args = node.arguments&.arguments || []
+    if args.length == 2 && args[0].is_a?(Prism::SymbolNode)
+      key = args[0].unescaped
+      val = literal_string(args[1])
+      case key
+      when "public_dir", "public_folder", "public"
+        config[:public_dir] = val if val
+      when "views"
+        config[:views] = val if val
+      when "port"
+        config[:port] = literal_int(args[1]) || config[:port]
+      when "workers"
+        # Default worker count; the runtime CLI's `-w N` still
+        # overrides. Useful for apps whose handlers can block --
+        # SSE streamers, long-poll endpoints -- to default to
+        # something more useful than 1 and keep the homepage
+        # responsive while one worker is held by a stream.
+        config[:workers] = literal_int(args[1]) || config[:workers]
+      when "bind"
+        # silently accept; tep always binds 0.0.0.0
+      when "scheduler"
+        # `set :scheduler, :scheduled` opts the app into the fiber-
+        # per-connection server (Tep::Server::Scheduled). Default
+        # stays the prefork-blocking Tep::Server until the next major
+        # release, when this flips and Blocking is deleted. The CLI
+        # `-s` flag overrides the same way `-w` overrides `:workers`.
+        sym = args[1].is_a?(Prism::SymbolNode) ? args[1].unescaped : nil
+        if sym == "scheduled"
+          config[:scheduler] = :scheduled
+        elsif sym == "blocking" || sym.nil?
+          # default; explicit blocking is a no-op
+        else
+          warnings << "unsupported `set :scheduler, :#{sym}` -- choose :scheduled or :blocking"
+        end
+      else
+        warnings << "unsupported `set :#{key}` -- ignored"
+      end
+    end
+    return
+  end
+
+  case name
+  when "require", "require_relative"
+    # tep's own library is inlined wholesale (see inlined_tep_library), so
+    # `require_relative "tep"` / "tep/..." is a no-op. A plain `require
+    # "gem"` (by name) is dropped -- spinel has no gem load path. But an
+    # app-local `require_relative "vendor/foo"` IS honoured: we read the
+    # target now and splice its source straight into the program, exactly
+    # as we do for tep's library. spinel can't be relied on to resolve
+    # require_relative at build time, but build-time inlining is reliable
+    # -- and it lets a tep app vendor and use a real Ruby gem (e.g.
+    # examples/geohash/vendor/pr_geohash.rb). Only genuinely-missing files
+    # warn, so a typo still surfaces early instead of fifty spinel
+    # "uninitialized constant" lines later.
+    if name == "require_relative"
+      args = node.arguments&.arguments || []
+      first = args.first
+      if first.is_a?(Prism::StringNode)
+        path = first.unescaped
+        base = input_path ? File.dirname(input_path) : Dir.pwd
+        cand = File.expand_path(path.end_with?(".rb") ? path : path + ".rb", base)
+        # tep's own library is already inlined wholesale at the top
+        # (inlined_tep_library), so requiring it here must be a no-op --
+        # otherwise we inline the whole library a SECOND time. Beyond the
+        # by-name forms ("tep" / "tep/foo"), an example loads it by PATH
+        # (`require_relative "../lib/tep"`); since the app-local inliner
+        # became recursive (#166) that path form would re-pull every
+        # tep/*.rb, duplicating `module Pg` + its ffi_const into a C
+        # `redefinition` error. Resolve and compare against LIB_DIR so all
+        # spellings that land inside tep's own lib are skipped.
+        is_tep_lib = path == "tep" || path.start_with?("tep/") ||
+                     cand == File.join(LIB_DIR, "tep.rb") ||
+                     cand.start_with?(LIB_DIR + File::SEPARATOR)
+        if !is_tep_lib
+          if File.file?(cand)
+            passthrough << "# --- inlined require_relative #{path.inspect} (#{File.basename(cand)}) ---"
+            passthrough << inline_require_relative_tree(cand, inlined_seen, warnings)
+          else
+            warnings << "external `require_relative #{path.inspect}` ignored " \
+                        "(no file at #{cand}). For a published gem, declare it in " \
+                        "a Gemfile and run `spinel-compat vendor` (bundler-spinel), " \
+                        "then require_relative \"vendor/spinel/deps\"."
+          end
+        end
+      end
+    end
+    return
+  when "enable", "disable"           then return  # ignore (sessions, etc.)
+  when "configure"                   then return  # we run as a single env
+  when "use"
+    warnings << "unsupported `use` (Rack middleware) -- ignored"
+    return
+  when "helpers"
+    warnings << "unsupported `helpers do ... end` -- ignored"
+    return
+  end
+
+  # Unknown top-level call -- skip with a warning.
+  warnings << "unrecognised top-level call `#{name}` -- ignored"
+end
+
+def block_source(block_node)
+  body = block_node.body
+  return "" if body.nil?
+  src = body.location.slice
+  src
+end
+
+# ---- Tep::Proxy block-DSL lowering (#88) ----
+
+# Maps a proxy block-DSL method name to the Tep::Proxy imeth the
+# generated subclass overrides. `before`/`after` rename to
+# `before_forward`/`after_forward` (the runtime hook names -- bare
+# before/after collide with Filter/Security/Auth under spinel's
+# same-name dispatch); the rest map 1:1.
+PROXY_HOOK_IMETH = {
+  "before"          => "before_forward",
+  "after"           => "after_forward",
+  "on_stream_chunk" => "on_stream_chunk",
+  "on_stream_end"   => "on_stream_end",
+  "stream_request?" => "stream_request?",
+  # 6.4: per-request upstream picker. `pick_upstream do |req| ... end`
+  # lowers to a subclass override; default behavior (return @upstream)
+  # is preserved when the block isn't supplied.
+  "pick_upstream"   => "pick_upstream",
+  # 6.5: per-request retry policy. `retry_policy do |req| ... end`
+  # lowers to a subclass override returning a Tep::Proxy::RetryPolicy.
+  # Default (no override) returns a no-retry policy.
+  "retry_policy"    => "retry_policy",
+}.freeze
+
+# Route verbs a proxy var can be mounted on (`Tep.<verb> "p", api`).
+PROXY_MOUNT_VERBS = %w[get post put patch delete head].freeze
+
+# True for a `Tep::Proxy.new(...)` / `Proxy.new(...)` call node.
+def proxy_new_call?(node)
+  return false unless node.is_a?(Prism::CallNode) && node.name == :new
+  recv = node.receiver
+  return false if recv.nil?
+  slice = recv.location.slice
+  slice == "Tep::Proxy" || slice == "Proxy"
+end
+
+# Extract the upstream argument source from a `Tep::Proxy.new(...)`
+# call, normalising the doc's keyword form (`upstream: "..."`) to the
+# positional arg the runtime initialize(upstream) takes. Returns the
+# raw source slice of the value expression.
+def proxy_upstream_src(node, warnings)
+  args = node.arguments&.arguments || []
+  if args.empty?
+    warnings << "Tep::Proxy.new needs an upstream argument; emitting empty"
+    return '""'
+  end
+  first = args.first
+  if first.is_a?(Prism::KeywordHashNode)
+    first.elements.each do |el|
+      next unless el.is_a?(Prism::AssocNode)
+      k = el.key
+      kn = k.is_a?(Prism::SymbolNode) ? k.unescaped : nil
+      return el.value.location.slice if kn == "upstream"
+    end
+    warnings << "Tep::Proxy.new: no `upstream:` key found; emitting empty"
+    return '""'
+  end
+  first.location.slice
+end
+
+# Comma-joined block parameter names ("req, res, ureq"). The generated
+# imeth uses the user's chosen names verbatim, so their block body
+# references resolve. Empty string for a paramless block.
+def block_param_list(block_node)
+  bp = block_node.parameters
+  return "" unless bp.is_a?(Prism::BlockParametersNode)
+  pp = bp.parameters
+  return "" unless pp.is_a?(Prism::ParametersNode)
+  pp.requireds.map { |r| r.is_a?(Prism::RequiredParameterNode) ? r.name.to_s : nil }.compact.join(", ")
+end
+
+def literal_string(node)
+  case node
+  when Prism::StringNode then node.unescaped
+  when Prism::SymbolNode then node.unescaped
+  else nil
+  end
+end
+
+def literal_int(node)
+  return node.value if node.is_a?(Prism::IntegerNode)
+  nil
+end
+
+# ---- block body rewrites ----
+#
+# We do simple, conservative textual substitutions. Anything more
+# elaborate (full AST rewriting) is out of scope -- the user can
+# fall back to writing explicit `Tep::Handler` subclasses.
+def rewrite_block(src, force_string: true)
+  s = src.dup
+
+  # `@name = expr` (Sinatra-style instance variables) -> store on the
+  # per-request ivars bag. The string-coerce wrap (`(...).to_s`) keeps
+  # the str_hash uniform-typed even when handlers stash an int / bool
+  # in `@count` / `@flag` for a template to render. Excluded: `==`,
+  # `=>` (which can't appear at this position anyway), `=~`. The
+  # write rewrite runs before the bare `@name` read rewrite so the
+  # LHS `@x` doesn't get caught by the read pass.
+  #
+  # Also: spinel doesn't support multi-statement single-line ivar
+  # assignments (`@a=1; @b=2`); the `(.+)$` capture is line-greedy.
+  # Users who need that should split across lines, which is the more
+  # idiomatic style anyway.
+  s = s.gsub(/^(\s*)@(\w+)\s*=(?![=~])\s*(.+)$/) do
+    %{#{$1}req.ivars["#{$2}"] = (#{$3}).to_s}
+  end
+
+  # Bare `@name` read (anywhere) -> `req.ivars["name"]`. Negative
+  # lookbehind avoids `@@x` (class var) and the suffix of identifier-
+  # like preceding text.
+  s = rewrite_ivar_reads(s, sink: "req.ivars")
+
+  # `redirect 'url', code?` (line)
+  s = s.gsub(/^(\s*)redirect\s+(['"][^'"]*['"])(?:\s*,\s*(\d+))?/) do
+    indent = $1
+    url    = $2
+    code   = $3 || "302"
+    "#{indent}res.set_status(#{code})\n#{indent}res.headers[\"Location\"] = #{url}\n#{indent}return \"\""
+  end
+
+  # `halt N, 'msg'` -> set status, return string
+  s = s.gsub(/^(\s*)halt\s+(\d+)\s*,\s*(['"][^'"]*['"])/) do
+    "#{$1}res.set_status(#{$2})\n#{$1}return #{$3}"
+  end
+  s = s.gsub(/^(\s*)halt\s+(\d+)$/) do
+    "#{$1}res.set_status(#{$2})\n#{$1}return \"\""
+  end
+
+  # `content_type 'foo'`
+  s = s.gsub(/^(\s*)content_type\s+(['"][^'"]*['"])/) do
+    "#{$1}res.headers[\"Content-Type\"] = #{$2}"
+  end
+
+  # `status N`
+  s = s.gsub(/^(\s*)status\s+(\d+)/) do
+    "#{$1}res.set_status(#{$2})"
+  end
+
+  # `headers["X"] = "y"` -> `res.headers[...]` when not already qualified
+  s = s.gsub(/(?<![\w.])headers\[/, "res.headers[")
+
+  # `cookies["k"]` -> `req.cookies["k"]` when not already qualified
+  s = s.gsub(/(?<![\w.])cookies\[/, "req.cookies[")
+
+  # `erb :name`              -> `tep_view_name(Tep.str_hash, req.ivars)`
+  # `erb :name, locals: {a: "b", c: "d"}` -> build a String=>String
+  # hash from the literal-only kwarg form, then call. The second
+  # arg threads the per-request ivars bag so templates can read
+  # `<%= @name %>` style references the handler set with `@name = v`.
+  s = s.gsub(/(?<![\w.])erb\s+:(\w+)\s*,\s*locals:\s*\{([^}]*)\}/) do
+    view = $1
+    # Value runs up to the next comma or closing brace; quoted strings
+    # are handled separately so they can contain commas or spaces.
+    pairs = $2.scan(/(\w+):\s*("[^"]*"|'[^']*'|[^,}]+?)\s*(?=,|\z)/)
+    setters = pairs.map { |k, v| %{__l["#{k}"] = (#{v.strip}).to_s} }.join("; ")
+    "(__l = Tep.str_hash; #{setters}; tep_view_#{view}(__l, req.ivars))"
+  end
+  s = s.gsub(/(?<![\w.])erb\s+:(\w+)/, 'tep_view_\1(Tep.str_hash, req.ivars)')
+
+  # Same shape for `mustache :name` and `mustache :name, locals: {...}`.
+  s = s.gsub(/(?<![\w.])mustache\s+:(\w+)\s*,\s*locals:\s*\{([^}]*)\}/) do
+    view = $1
+    pairs = $2.scan(/(\w+):\s*("[^"]*"|'[^']*'|[^,}]+?)\s*(?=,|\z)/)
+    setters = pairs.map { |k, v| %{__l["#{k}"] = (#{v.strip}).to_s} }.join("; ")
+    "(__l = Tep.str_hash; #{setters}; tep_mustache_#{view}(__l, req.ivars))"
+  end
+  s = s.gsub(/(?<![\w.])mustache\s+:(\w+)/, 'tep_mustache_\1(Tep.str_hash, req.ivars)')
+
+  # `pass` -> request a skip to the next matching route. The
+  # framework's dispatch loop watches `req.passed`. Both the bare
+  # form and `pass if cond` (modifier-if) are translated.
+  s = s.gsub(/^(\s*)pass\s+if\s+(.+)$/) do
+    "#{$1}if (#{$2})\n#{$1}  req.set_passed\n#{$1}  return \"\"\n#{$1}end"
+  end
+  s = s.gsub(/^(\s*)pass\s*$/) do
+    "#{$1}req.set_passed\n#{$1}return \"\""
+  end
+
+  # `send_file 'path'` -> `res.send_file 'path'`; reuses the static-dir
+  # write path. The framework streams the file's bytes after the
+  # headers go out, so the handler doesn't need to read it itself.
+  s = s.gsub(/^(\s*)send_file\s+(['"][^'"]*['"])/) do
+    "#{$1}res.send_file(#{$2})\n#{$1}return \"\""
+  end
+
+  # `stream X.new` -> `res.start_stream(X.new); return ""` -- ships the
+  # subclass-style streaming DSL. The Sinatra `stream do |out| ... end`
+  # block form isn't supported yet (closures aren't first-class in
+  # Spinel; you'd write a `class X < Tep::Streamer; def pump(out); ...`
+  # instead and pass `X.new` to `stream`).
+  s = s.gsub(/^(\s*)stream\s+(.+)$/) do
+    indent = $1
+    expr   = $2
+    "#{indent}res.start_stream(#{expr})\n#{indent}return \"\""
+  end
+
+  # `session[k] = v` and `session[k]` -> .set / .get on req.session.
+  # Spinel doesn't dispatch user-defined []= on user classes, and
+  # without the .set() form the dirty flag never trips.
+  s = s.gsub(/(?<![\w.])session\[:(\w+)\]\s*=\s*([^\n]+?)$/m,
+             'req.session.set("\1", \2)')
+  s = s.gsub(/(?<![\w.])session\[(['"])(\w+)\1\]\s*=\s*([^\n]+?)$/m,
+             'req.session.set("\2", \3)')
+  s = s.gsub(/(?<![\w.])session\[:(\w+)\]/,        'req.session.get("\1")')
+  s = s.gsub(/(?<![\w.])session\[(['"])(\w+)\1\]/, 'req.session.get("\2")')
+
+  # `set_cookie "name", "value"` -> `res.set_cookie("name", "value", {})`
+  # Two-arg form only; richer kwarg forms aren't translated.
+  s = s.gsub(/^(\s*)set_cookie\s+(['"][^'"]*['"])\s*,\s*(['"][^'"]*['"])/) do
+    "#{$1}res.set_cookie(#{$2}, #{$3}, Tep.str_hash)"
+  end
+
+  # `params['x']` / `params["x"]` and bare `params`
+  s = s.gsub(/(?<![\w.])params(?=[\[\.]|$|\s)/, "req.params")
+
+  # `request.body.read` -> `req.body` (a Sinatra app's request.body
+  # is an IO and apps commonly call `.read` on it; tep's req.body
+  # is already a String, so `.read` is a no-op). Run BEFORE the bare
+  # `request -> req` rewrite so we can pin the `.body.read` suffix
+  # exactly and not have to deal with the intermediate `req.body.read`
+  # state. The bare `request.body` form (no `.read`) is handled by
+  # the next rewrite, which leaves it as `req.body` -- already a
+  # String via Tep::Request#body's alias to @raw_body.
+  s = s.gsub(/(?<![\w.])request\.body\.read\b/, "req.body")
+
+  # `request` -> req,  `response` -> res, when used as bare identifiers
+  s = s.gsub(/(?<![\w.])request(?=[\.\[\s,)]|$)/, "req")
+  s = s.gsub(/(?<![\w.])response(?=[\.\[\s,)]|$)/, "res")
+
+  # Symbol keys -- Sinatra accepts both `params[:name]` and `params["name"]`.
+  # Spinel doesn't poly-convert symbols to strings inside Hash[]; rewrite
+  # to string keys.
+  s = s.gsub(/(req\.params)\[:(\w+)\]/, '\1["\2"]')
+
+  # `"#{params['x']}"` interpolation works fine after the params rewrite.
+
+  # String-coerce the last expression of the block body. Spinel's
+  # whole-program type inference unifies handler return types across
+  # all subclasses; if any one subclass returns `Hash#[]` directly
+  # (poly value), the union widens and the eventual `iv_body` read
+  # in the worker miscompiles. Wrapping the last expression in
+  # `"" + (...)` forces it to a String at the source level.
+  if force_string
+    lines = s.lines
+    last_idx = lines.rindex { |l| !l.strip.empty? }
+    if last_idx
+      last = lines[last_idx]
+      stripped = last.lstrip
+      indent = last[0, last.length - stripped.length]
+      # Skip if the last line is an explicit non-string control flow:
+      # bare `end`/`else`/`when` (handled by the surrounding block),
+      # or an explicit `return`/`raise`/`break`/`next`. Setter calls
+      # like `res.headers[...]=...` are also skipped because the
+      # assignment's value (the RHS) is captured but `"" + setter` is
+      # ill-typed.
+      unless stripped =~ /\A(end|else|elsif|when|return|raise|break|next)\b/ ||
+             stripped =~ /\A(res|response)\.[a-zA-Z_]+\s*=|\A(res|response)\.\w+\s*\(/
+        body_expr = stripped.sub(/\s*(#.*)?\Z/, "")
+        comment   = stripped[body_expr.length..-1] || ""
+        lines[last_idx] = "#{indent}\"\" + (#{body_expr.rstrip})#{comment.rstrip.empty? ? "\n" : "  #{comment}"}"
+      end
+    end
+    s = lines.join
+  end
+
+  s
+end
+
+def indent(text, n)
+  pad = " " * n
+  text.lines.map { |l| l.strip.empty? ? l.rstrip : pad + l.rstrip }.join("\n")
+end
+
+def relative_path(from_dir, target)
+  Pathname.new(File.expand_path(target))
+    .relative_path_from(Pathname.new(File.expand_path(from_dir))).to_s
+end
+
+# Compile an ERB template to a Ruby method body. The method takes
+# two String=>String Hash arguments: `locals` (passed by the
+# handler's explicit `erb :v, locals: {...}` form) and `ivars`
+# (the per-request bag carrying `@name = ...` Sinatra-style ivars
+# from handler / before-filter scope). Inside the template:
+#
+#   <%= locals["k"] %>     # explicit locals
+#   <%= @name %>           # rewrites to `ivars["name"]`
+#   <% if/else/end %>      # control flow, also gets ivar rewrite
+#   <%# ... %>             # comment, dropped
+#
+# Spinel can't `eval`, so all ERB rendering is build-time AOT --
+# this is what makes `erb :name` work on a spinel-compiled binary.
+def erb_to_ruby_body(template)
+  parts = []
+  parts << 'out = ""'
+  i = 0
+  literal = String.new
+  flush = -> {
+    if !literal.empty?
+      parts << "out += #{literal.dump}"
+      literal = String.new
+    end
+  }
+  while i < template.length
+    open_at = template.index("<%", i)
+    if open_at.nil?
+      literal << template[i..-1]
+      break
+    end
+    literal << template[i...open_at]
+    close_at = template.index("%>", open_at + 2)
+    raise "unterminated <% in template" if close_at.nil?
+    flush.call
+    code = template[(open_at + 2)...close_at]
+    if code.start_with?("=")
+      expr = rewrite_ivar_reads(code[1..-1].strip)
+      parts << "out += (#{expr}).to_s"
+    elsif code.start_with?("#")
+      # comment; ignore
+    else
+      parts << rewrite_ivar_reads(code.strip)
+    end
+    i = close_at + 2
+  end
+  flush.call
+  parts << "out"
+  parts.join("\n  ")
+end
+
+# Compile a Mustache template (documented subset) to a Ruby method
+# body. Same `(locals, ivars)` signature as ERB views; the call site
+# rewrites are parallel.
+#
+# Supported tags
+# --------------
+#
+#   {{name}}      escaped string interpolation
+#                   -> out += Tep.h(locals["name"])
+#   {{{name}}}    raw / unescaped interpolation
+#                   -> out += locals["name"]
+#   {{& name}}    raw alias (Mustache spec)
+#                   -> same as {{{name}}}
+#   {{@name}}     ivar form, escaped
+#                   -> out += Tep.h(ivars["name"])
+#   {{{@name}}}   ivar form, raw
+#                   -> out += ivars["name"]
+#   {{! comment}} dropped at compile time
+#
+# Out of scope (deliberately)
+# ---------------------------
+#
+#   {{#section}}{{/section}}    sections (need iterable locals;
+#                               tep's view args are String=>String)
+#   {{^section}}{{/section}}    inverted sections (same reason)
+#   {{>partial}}                partials -- could be added later as
+#                               sugar for tep_mustache_<partial>(...)
+#   {{=<% %>=}}                 delimiter swaps -- niche
+#   Lambdas                     require Proc / closures
+#
+# When user code reaches for an unsupported tag the compiler raises
+# at build time so the build fails fast with a clear message,
+# instead of silently rendering literal `{{...}}` to the client.
+def mustache_to_ruby_body(template)
+  parts = []
+  parts << 'out = ""'
+  i = 0
+  literal = String.new
+  flush = -> {
+    if !literal.empty?
+      parts << "out += #{literal.dump}"
+      literal = String.new
+    end
+  }
+  while i < template.length
+    open_at = template.index("{{", i)
+    if open_at.nil?
+      literal << template[i..-1]
+      break
+    end
+    literal << template[i...open_at]
+    # Triple-stache `{{{name}}}` -- raw interpolation. Consume {{{ ... }}}.
+    if template[open_at + 2] == "{"
+      close_at = template.index("}}}", open_at + 3)
+      raise "unterminated {{{ in mustache template" if close_at.nil?
+      flush.call
+      key = template[(open_at + 3)...close_at].strip
+      parts << mustache_emit_value(key, escaped: false)
+      i = close_at + 3
+      next
+    end
+    close_at = template.index("}}", open_at + 2)
+    raise "unterminated {{ in mustache template" if close_at.nil?
+    flush.call
+    inner = template[(open_at + 2)...close_at].strip
+    if inner.start_with?("!")
+      # comment, drop
+    elsif inner.start_with?("#")
+      raise "mustache section `{{##{inner[1..-1].strip}}}` unsupported -- tep's view args are String=>String, sections need iterable locals. See SINATRA_COMPAT.md > Mustache subset."
+    elsif inner.start_with?("^")
+      raise "mustache inverted section `{{^#{inner[1..-1].strip}}}` unsupported. See SINATRA_COMPAT.md > Mustache subset."
+    elsif inner.start_with?("/")
+      raise "mustache closing `{{/#{inner[1..-1].strip}}}` without a section opener (sections aren't supported)."
+    elsif inner.start_with?(">")
+      raise "mustache partial `{{>#{inner[1..-1].strip}}}` unsupported -- call `mustache :#{inner[1..-1].strip}` from the handler instead."
+    elsif inner.start_with?("&")
+      key = inner[1..-1].strip
+      parts << mustache_emit_value(key, escaped: false)
+    elsif inner.start_with?("=")
+      raise "mustache delimiter swap `{{=...=}}` unsupported."
+    else
+      parts << mustache_emit_value(inner, escaped: true)
+    end
+    i = close_at + 2
+  end
+  flush.call
+  parts << "out"
+  parts.join("\n  ")
+end
+
+def mustache_emit_value(key, escaped:)
+  # An `@name` key (with or without leading whitespace) reads from
+  # `ivars`; bare names read from `locals`. Mirrors the ERB ivar
+  # convention so a project can mix engines and the per-request
+  # `req.ivars` bag flows uniformly.
+  if key.start_with?("@")
+    bag = "ivars"
+    key = key[1..-1].strip
+  else
+    bag = "locals"
+  end
+  # `.to_s` to coerce the StrStrHash lookup back to String. Spinel
+  # widens the hash value type when the param-inference pass (#542
+  # cascade) decides the value side is poly; `.to_s` is a no-op for
+  # an actual String and gives "" for nil.
+  expr = %{#{bag}["#{key}"].to_s}
+  escaped ? "out += Tep.h(#{expr})" : "out += #{expr}"
+end
+
+# Replace `@name` references with `ivars["name"]`. Used inside ERB
+# template chunks (which receive `ivars` as a parameter) and as a
+# read-side helper for handler-body rewriting (where `@name` ->
+# `req.ivars["name"]`, see `rewrite_block`).
+#
+# The negative lookbehind `(?<![\w.@])` skips matches preceded by an
+# identifier character, a dot, or another `@` -- so `@@class_var`
+# isn't accidentally split into `@` + `@class_var` and a stray `@`
+# inside a string literal at the start of a line still gets caught
+# (callers mostly invoke this on small Ruby fragments where literal
+# strings containing `@x` are uncommon).
+def rewrite_ivar_reads(src, sink: 'ivars')
+  src.gsub(/(?<![\w.@])@(\w+)/) { %{#{sink}["#{$1}"]} }
+end
+
+# Read tep.rb plus everything it require_relatives, in order, with
+# the require lines stripped. Used to inline the framework into a
+# build-temp file so spinel doesn't have to resolve any requires.
+#
+# Also substitutes `@TEP_SPHTTP_O@` / `@TEP_SQLITE_O@` / `@TEP_PG_O@`
+# with the absolute paths to the built .o files; `@TEP_PG_CFLAGS@`
+# carries the libpq cflags+libs (pkg-config / pg_config output).
+# Override via TEP_SPHTTP_O / TEP_SQLITE_O / TEP_PG_O / TEP_PG_CFLAGS
+# env vars; defaults live under `<LIB_DIR>/tep/`.
+# Crypto symbols (sp_crypto_*) live in spinel's libspinel_rt.a since
+# matz/spinel#514, so the spinel driver auto-links them and no
+# separate placeholder is needed.
+def inlined_tep_library
+  loaded = []
+  visit  = lambda do |abs_path|
+    return if loaded.any? { |l| l[:path] == abs_path }
+    text = File.read(abs_path)
+    deps = []
+    body = text.lines.reject do |line|
+      m = line.match(/^\s*require_relative\s+"([^"]+)"/)
+      next false unless m
+      deps << File.expand_path(m[1] + ".rb", File.dirname(abs_path))
+      true
+    end.join
+    deps.each { |d| visit.call(d) }
+    loaded << { path: abs_path, body: body }
+  end
+  visit.call(File.join(LIB_DIR, "tep.rb"))
+  combined = loaded.map { |l| "# --- inlined: " + relative_to_lib(l[:path]) + " ---\n" + l[:body] }.join("\n")
+  # Resolve the @TEP_*@ placeholders from spinel-ext.json (the single
+  # source of truth) rather than a hardcoded list. Same env-first
+  # behavior as before -- the Makefile exports TEP_SPHTTP_O /
+  # TEP_SQLITE_O / TEP_PG_O / TEP_PG_CFLAGS / TEP_PG_LIBS, which this
+  # reads, defaulting `.o` paths to the entry's source-derived path.
+  tep_ext_subs.each do |placeholder, value|
+    combined = combined.gsub(placeholder, value)
+  end
+  combined
+end
+
+# Build the {@TEP_*@ => value} substitution dict from spinel-ext.json
+# for tep's OWN builds. Faithful to the historical env-first behavior:
+#   * a `.o` placeholder (entry has "source") resolves to its env
+#     override (TEP_<NAME>, the placeholder sans @) else the prebuilt
+#     .o derived from the entry's source (sphttp.c -> sphttp.o);
+#   * a cflags-only placeholder (no "source", e.g. @TEP_PG_CFLAGS@)
+#     resolves to TEP_PG_CFLAGS + TEP_PG_LIBS, the libs defaulting from
+#     the entry's pkg_config (libpq -> -lpq).
+# `spinel-compat vendor` reads the same file but resolves differently
+# (compiles the .c, runs pkg-config at the consumer) -- that's the
+# point: one declaration, two build paths. See spinelgems/docs/c-ext.md.
+def tep_ext_subs
+  ext_path = File.join(REPO_ROOT, "spinel-ext.json")
+  return {} unless File.exist?(ext_path)
+  subs = {}
+  JSON.parse(File.read(ext_path)).each do |entry|
+    placeholder = entry["placeholder"]
+    env_var = placeholder.delete("@")          # @TEP_SPHTTP_O@ -> TEP_SPHTTP_O
+    if entry["source"]
+      default_o = File.expand_path(entry["source"].sub(/\.c\z/, ".o"), REPO_ROOT)
+      subs[placeholder] = ENV.fetch(env_var, default_o)
+    else
+      cflags       = ENV.fetch(env_var, "")
+      libs_var     = env_var.sub(/_CFLAGS\z/, "_LIBS")
+      default_libs = entry["pkg_config"] ? "-l" + entry["pkg_config"].sub(/\Alib/, "") : ""
+      libs         = ENV.fetch(libs_var, default_libs)
+      subs[placeholder] = "#{cflags} #{libs}".strip
+    end
+  end
+  subs
+end
+
+# Split a Sinatra-style source on `__END__` and parse the trailing
+# `@@ name` blocks into a {name => template_body} hash.
+def split_inline_views(raw)
+  if raw =~ /^__END__\s*\n/m
+    head = $`
+    tail = $'
+  else
+    return [raw, {}]
+  end
+  views = {}
+  current = nil
+  buf = String.new
+  tail.each_line do |line|
+    m = line.match(/^@@\s+(\S+)\s*$/)
+    if m
+      views[current] = buf if current
+      current = m[1]
+      buf = String.new
+    elsif current
+      buf << line
+    end
+  end
+  views[current] = buf if current
+  [head, views]
+end
+
+# Expand a Sinatra-style path with optional `(...)` segments into the
+# Cartesian product of include/skip choices. `/say(/:greeting)` ->
+# ["/say", "/say/:greeting"]. Two optionals -> four paths, etc.
+def expand_optional_segments(path)
+  return [path] unless path.include?("(")
+  results = [""]
+  i = 0
+  while i < path.length
+    c = path[i]
+    if c == "("
+      close = path.index(")", i + 1)
+      raise "unmatched '(' in path: #{path}" unless close
+      inside = path[(i + 1)...close]
+      # Include first, skip second: when a request matches multiple
+      # optional-arrangements (e.g. `/items/42` matches both
+      # `/items/:id` and `/items/:section`), the earlier-named
+      # capture fills first -- matches Sinatra's intuition.
+      results = results.flat_map { |r| [r + inside, r] }
+      i = close + 1
+    else
+      results = results.map { |r| r + c }
+      i += 1
+    end
+  end
+  results.uniq
+end
+
+def sinatra_base_class?(class_node)
+  sup = class_node.superclass
+  return false if sup.nil?
+  src = sup.location.slice
+  src == "Sinatra::Base" || src == "Sinatra::Application" || src == "::Sinatra::Base"
+end
+
+# Walk `<input_dir>/assets/` recursively and return a list of
+# `Tep::Assets._add` lines, one per file. Inferred mime per
+# extension. Files containing NUL bytes get warned + skipped --
+# spinel's :str type doesn't track length alongside the pointer,
+# so a NUL truncates the served body. For binary assets that need
+# to round-trip exactly (PNGs with embedded NULs, fonts) the
+# right path is `Tep.public_dir` at runtime, not embed.
+ASSET_MIME_BY_EXT = {
+  ".css"   => "text/css; charset=utf-8",
+  ".js"    => "application/javascript; charset=utf-8",
+  ".json"  => "application/json",
+  ".html"  => "text/html; charset=utf-8",
+  ".htm"   => "text/html; charset=utf-8",
+  ".txt"   => "text/plain; charset=utf-8",
+  ".md"    => "text/markdown; charset=utf-8",
+  ".svg"   => "image/svg+xml",
+  ".xml"   => "application/xml",
+  ".ico"   => "image/x-icon",
+  ".png"   => "image/png",
+  ".jpg"   => "image/jpeg",
+  ".jpeg"  => "image/jpeg",
+  ".gif"   => "image/gif",
+  ".webp"  => "image/webp",
+  ".woff"  => "font/woff",
+  ".woff2" => "font/woff2",
+  ".ttf"   => "font/ttf",
+  ".otf"   => "font/otf",
+  ".pdf"   => "application/pdf",
+}.freeze
+
+def embed_assets(input_path, warnings)
+  assets_dir = File.join(File.dirname(input_path), "assets")
+  return [] unless File.directory?(assets_dir)
+  lines = []
+  count = 0
+  bytes = 0
+  Dir.glob(File.join(assets_dir, "**", "*")).sort.each do |abs|
+    next unless File.file?(abs)
+    rel = abs.sub(assets_dir, "")  # leading "/"
+    body = File.binread(abs)
+    if body.include?("\x00")
+      warnings << "asset #{rel}: contains NUL byte; skipped (use Tep.public_dir for binary assets)"
+      next
+    end
+    ext  = File.extname(abs).downcase
+    mime = ASSET_MIME_BY_EXT[ext] || "application/octet-stream"
+    # Ruby's `String#dump` produces a literal that re-parses to the
+    # exact same bytes (\xHH for non-printable, \uXXXX where
+    # applicable). Spinel reads it as a const char *.
+    lines << "Tep::Assets._add(#{rel.inspect}, #{body.dump}, #{mime.inspect})"
+    count += 1
+    bytes += body.bytesize
+  end
+  if count > 0
+    lines.unshift("# bundled #{count} asset(s), #{bytes} bytes total")
+  end
+  lines
+end
+
+def relative_to_lib(abs_path)
+  Pathname.new(abs_path).relative_path_from(Pathname.new(LIB_DIR)).to_s rescue abs_path
+end
+
+# ---- driver ----
+
+def cmd_build(args)
+  input    = nil
+  out_path = nil
+  c_only   = false
+  i = 0
+  while i < args.length
+    a = args[i]
+    case a
+    when "-o" then out_path = args[i + 1]; i += 2
+    when "-c" then c_only = true; i += 1
+    when /^-/ then fatal "unknown option: #{a}"
+    else
+      input ||= a
+      i += 1
+    end
+  end
+  fatal "usage: tep build app.rb [-o out] [-c]" unless input
+
+  base = File.basename(input, ".rb")
+  out_path ||= File.join(File.dirname(input), base)
+  translated = translate(input)
+
+  # Spinel's require_relative resolves against the source file's
+  # directory and chokes on absolute paths. Drop the generated file
+  # next to the user's source so the require_relative emitted by the
+  # translator (a path computed relative to the input dir) works.
+  rb_path = File.join(File.dirname(input), ".#{base}.tep.rb")
+  File.write(rb_path, translated)
+
+  spinel_args = [SPINEL, rb_path, "-o", out_path]
+  spinel_args << "-c" if c_only
+  warn "tep: building -> #{out_path}" unless ENV["TEP_QUIET"]
+  unless system(*spinel_args)
+    fatal "spinel failed; translated source kept at #{rb_path}"
+  end
+  File.unlink(rb_path) unless ENV["TEP_KEEP_TMP"]
+  warn "tep: built #{out_path}"
+end
+
+def cmd_run(args)
+  build_args = []
+  run_args   = []
+  i = 0
+  while i < args.length
+    a = args[i]
+    case a
+    when "-p", "-w" then run_args << a << args[i + 1]; i += 2
+    else
+      build_args << a; i += 1
+    end
+  end
+  fatal "usage: tep run app.rb [-p PORT] [-w WORKERS]" if build_args.empty?
+  out = File.join(Dir.pwd, "tep-run-bin")
+  cmd_build(build_args + ["-o", out])
+  exec(out, *run_args)
+end
+
+def cmd_translate(args)
+  input = args.first or fatal "usage: tep translate app.rb"
+  puts translate(input)
+end
+
+case ARGV.shift
+when "build"     then cmd_build(ARGV)
+when "run"       then cmd_run(ARGV)
+when "translate" then cmd_translate(ARGV)
+when nil, "-h", "--help"
+  puts <<~USAGE
+    tep -- Sinatra-flavoured framework that compiles to a native binary.
+
+    Usage:
+      tep build app.rb [-o out] [-c]    translate + spinel-compile
+      tep run   app.rb [-p PORT] [-w N] build then exec
+      tep translate app.rb               print the translated Ruby
+
+    Source compatibility: top-level `get '/path' do ... end`,
+    `post`, `put`, `patch`, `delete`, `before`, `after`, `not_found`,
+    plus `set :public_dir, ...`. Inside blocks: params, request,
+    response, redirect, halt, content_type all rewrite cleanly.
+  USAGE
+else
+  fatal "unknown command. Try `tep --help`."
+end