fresco 0.0.1

data/lib/fresco/cli/build.rb

@@ -0,0 +1,682 @@
+# Fresco: codegen step. Reads config/routes.rb + app/actions/ +
+# app/views/ from the user app's cwd, emits
+# generated/{boot,runtime,dispatch,requires,views}.rb (plus per-view
+# files under generated/views/) deterministically.
+
+require "erb"
+require "fileutils"
+require "herb"
+require "herb/engine"
+
+require "fresco"
+
+module Fresco
+  class CLI
+    class Build
+      GEN_DIR        = "generated".freeze
+      VIEWS_GEN_DIR  = "#{GEN_DIR}/views".freeze
+      MODELS_GEN_DIR = "#{GEN_DIR}/models".freeze
+      # C shims get copied here so the `ffi_cflags "generated/runtime/*.c"`
+      # strings in the runtime templates resolve from the user app's cwd.
+      RUNTIME_GEN_DIR = "#{GEN_DIR}/runtime".freeze
+
+      # In-gem source roots (set once at load — Fresco::Paths resolves
+      # relative to lib/fresco/paths.rb, which is stable per-install).
+      TEMPLATES_DIR = Fresco::Paths.template_root
+      RUNTIME_DIR   = Fresco::Paths.runtime_root
+
+      NAME_CHAR = /[A-Za-z0-9_]/.freeze
+
+      # Partial render call rewrite — see resolve_partial / rewrite_partial_renders.
+      PARTIAL_RENDER_RE = /<%=\s*render(?:\s*\(\s*|\s+)partial:\s*["']([^"']+)["'](?:\s*,\s*locals:\s*\{(.*?)\})?\s*\)?\s*%>/m
+
+      # Fresco-supplied kwargs every layout receives.
+      LAYOUT_FRAMEWORK_KWARGS = "flash: Flash.new, content: \"\"".freeze
+
+      LOCALS_RE       = /\A\s*<%#\s*locals:\s*(\(.*?\))\s*%>\s*\r?\n?/.freeze
+      LAYOUT_YIELD_RE = /<%=\s*yield\s*%>/.freeze
+
+      STATIC_APPEND_PREFIX  = "_buf << '".freeze
+      STATIC_APPEND_SUFFIX  = "'.freeze".freeze
+      MAX_VIEW_LITERAL_BYTES = 512
+
+      def run(argv = [])
+        FileUtils.mkdir_p(GEN_DIR)
+        FileUtils.mkdir_p(VIEWS_GEN_DIR)
+        FileUtils.mkdir_p(RUNTIME_GEN_DIR)
+
+        lint_actions!
+        action_files = stub_action_classes
+        route_entries = load_routes
+        has_root = route_entries.any? { |verb, pattern, _, _| verb == "GET" && pattern == "/" }
+
+        emit_welcome(has_root, route_entries)
+        emit_dispatch(route_entries)
+        emit_runtime
+        emit_c_shims
+        db_adapter = emit_db_adapter
+        emit_models(db_adapter)
+        generated_models = collect_generated_models
+        emit_migrations(db_adapter)
+        emit_requires_manifest(action_files, generated_models, has_root)
+        emit_boot
+        view_names, layout_names = emit_views
+        emit_layout_dispatch(layout_names)
+
+        puts "wrote #{GEN_DIR}/{boot,dispatch,layout_dispatch,requires,runtime,views}.rb " \
+             "(#{route_entries.size} routes, #{view_names.size} views, #{layout_names.size} layouts)"
+        0
+      end
+
+      private
+
+      def render_template(name, **locals)
+        src = File.read(File.join(TEMPLATES_DIR, name))
+        ERB.new(src, trim_mode: "-").result_with_hash(locals)
+      end
+
+      # Lint user actions against the Spinel-acceptable Ruby subset before
+      # touching generated/. Anything the rubocop_spinel plugin flags is
+      # a hard build failure — generated output from un-compileable input
+      # would just push the error downstream into Spinel itself.
+      #
+      # Skip silently when rubocop_spinel isn't on the user's bundle (it's
+      # the recommended setup but not a hard requirement; freshly-scaffolded
+      # apps run their first build before `bundle install` adds it).
+      def lint_actions!
+        return unless File.exist?("Gemfile.lock") && File.read("Gemfile.lock").include?("rubocop_spinel")
+        unless system("bundle", "exec", "rubocop", "--no-color", "app/")
+          abort "[build] rubocop_spinel: violations in app/; aborting."
+        end
+      end
+
+      # Action stubs let config/routes.rb resolve `to: SomeAction` constants
+      # without actually loading user code (which would need runtime.rb).
+      def stub_action_classes
+        files = Dir.glob("app/actions/**/*.rb").sort
+        files.each do |file|
+          name = Fresco.path_to_class(file, "app/actions")
+          Fresco.const_set_path(name, Class.new)
+        end
+        files
+      end
+
+      def load_routes
+        load "config/routes.rb"
+        Fresco.app.routes.entries
+      end
+
+      # --- Default welcome route fallback ------------------------------
+      def emit_welcome(has_root, route_entries)
+        welcome_path = "#{GEN_DIR}/welcome.rb"
+        if has_root
+          # Stale welcome from a prior build (when the user had no root) —
+          # clear it so dev doesn't load a Fresco::Welcome nothing references.
+          File.delete(welcome_path) if File.exist?(welcome_path)
+        else
+          FileUtils.cp("#{RUNTIME_DIR}/welcome.rb", welcome_path)
+          Fresco.const_set_path("Fresco::Welcome", Class.new)
+          route_entries.unshift(["GET", "/", Fresco.const_get_path("Fresco::Welcome"), {}])
+        end
+      end
+
+      # --- Pattern → regex source + capture names -----------------------
+      #
+      # Char-by-char scan. Tokens:
+      #   :name        → named capture; default [^/]+, or constraints[:name].source
+      #   *name        → splat capture; matches .+ (incl. slashes)
+      #   (...)        → optional group, compiled as (?:...)?  (may nest)
+      #   /            → literal slash, emitted as \/
+      #   anything else → Regexp.escape
+      #
+      # For optional captures, the dispatcher emits `req.params[:name] = $N || ""`
+      # so CRuby (dev mode) and Spinel (release) both store "" when un-matched —
+      # Spinel already coerces NULL $N to "", but CRuby leaves it nil.
+      def compile_pattern(pattern, constraints = {})
+        captures = []
+        out      = String.new('\A')
+        paren    = 0
+        i        = 0
+        n        = pattern.length
+
+        while i < n
+          c = pattern[i]
+          case c
+          when "("
+            out << "(?:"
+            paren += 1
+            i += 1
+          when ")"
+            raise "unbalanced ')' in #{pattern.inspect}" if paren.zero?
+            out << ")?"
+            paren -= 1
+            i += 1
+          when "/"
+            out << '\/'
+            i += 1
+          when ":"
+            i += 1
+            name_start = i
+            i += 1 while i < n && NAME_CHAR.match?(pattern[i])
+            raise "empty :param name in #{pattern.inspect}" if i == name_start
+            name = pattern[name_start...i].to_sym
+            captures << name
+            out << (constraints.key?(name) ? "(#{constraints[name].source})" : '([^\/]+)')
+          when "*"
+            i += 1
+            name_start = i
+            i += 1 while i < n && NAME_CHAR.match?(pattern[i])
+            raise "empty *splat name in #{pattern.inspect}" if i == name_start
+            captures << pattern[name_start...i].to_sym
+            out << '(.+)'
+          else
+            out << Regexp.escape(c)
+            i += 1
+          end
+        end
+
+        raise "unclosed '(' in #{pattern.inspect}" unless paren.zero?
+
+        out << '\z'
+        [out, captures]
+      end
+
+      # --- Emit dispatch.rb --------------------------------------------
+      def emit_dispatch(route_entries)
+        compiled_routes = route_entries.map do |verb, pattern, klass, constraints|
+          regex_src, captures = compile_pattern(pattern, constraints)
+          { verb: verb, pattern: pattern, klass: klass, regex_src: regex_src, captures: captures }
+        end
+        File.write("#{GEN_DIR}/dispatch.rb", render_template("dispatch.rb.erb", routes: compiled_routes))
+      end
+
+      # --- Emit runtime.rb (copied from the gem's runtime/) ------------
+      def emit_runtime
+        FileUtils.cp("#{RUNTIME_DIR}/runtime.rb", "#{GEN_DIR}/runtime.rb")
+      end
+
+      # --- Copy C shims into generated/runtime/ ------------------------
+      #
+      # runtime.rb / db_*.rb reference these via `ffi_cflags
+      # "generated/runtime/<name>.c"`. The strings are evaluated by
+      # Spinel from the user app's cwd, so the .c files have to live
+      # there — they ship in the gem and get copied per-build.
+      def emit_c_shims
+        %w[http.c sqlite.c postgres.c].each do |c|
+          FileUtils.cp("#{RUNTIME_DIR}/#{c}", "#{RUNTIME_GEN_DIR}/#{c}")
+        end
+      end
+
+      # --- Emit db_adapter.rb (per-adapter template) -------------------
+      def emit_db_adapter
+        db_adapter = :none
+        if File.exist?("config/database.rb")
+          load "config/database.rb"
+          db_adapter = Fresco.database_adapter if Fresco.database_adapter
+        end
+
+        case db_adapter
+        when :sqlite
+          FileUtils.cp("#{RUNTIME_DIR}/db_sqlite.rb", "#{GEN_DIR}/db_adapter.rb")
+        when :postgres
+          FileUtils.cp("#{RUNTIME_DIR}/db_postgres.rb", "#{GEN_DIR}/db_adapter.rb")
+        when :none
+          # Even with no adapter, runtime.rb's request handler still calls
+          # `Fresco::Db.begin_request!` / `flush_log!`. Define them as no-ops.
+          File.write(
+            "#{GEN_DIR}/db_adapter.rb",
+            <<~RUBY,
+              # Fresco: no DB adapter configured. Auto-generated by `fresco build`.
+              # Add config/database.rb with `Fresco.database :sqlite` (or :postgres)
+              # to enable Fresco::Db::Active.
+              module Fresco
+                module Db
+                  def self.begin_request!; end
+                  def self.flush_log!; end
+                end
+              end
+            RUBY
+          )
+        else
+          abort "[build] unknown adapter #{db_adapter.inspect} in config/database.rb " \
+                "(expected :sqlite or :postgres)"
+        end
+
+        unless File.exist?("config/database.rb")
+          FileUtils.mkdir_p("config")
+          File.write(
+            "config/database.rb",
+            "# Fresco: no DB configured. Replace with `Fresco.database :sqlite, " \
+            "path: ENV.fetch(\"DATABASE_PATH\", \"db/app.sqlite3\")` (or :postgres) " \
+            "when you need one.\n",
+          )
+        end
+
+        db_adapter
+      end
+
+      # --- Emit generated models (per-adapter SQL baked in) ------------
+      def emit_models(db_adapter)
+        FileUtils.mkdir_p(MODELS_GEN_DIR)
+        Dir.glob("#{MODELS_GEN_DIR}/*.rb").each { |f| File.delete(f) }
+
+        # Schema + model + migration source files. Loaded under CRuby at
+        # build time — captured DSL state is read back below to drive
+        # codegen. Migrations need to load whether or not the user has
+        # models (e.g. early apps that haven't declared models yet still
+        # want db:migrate to work).
+        if File.exist?("db/schema.rb") && Dir.glob("app/models/*.rb").any?
+          load "db/schema.rb"
+          Dir.glob("app/models/*.rb").sort.each { |f| load f }
+        end
+
+        Fresco.models.each do |model|
+          write_model_file(model, db_adapter)
+        end
+      end
+
+      def collect_generated_models
+        Dir.glob("#{MODELS_GEN_DIR}/*.rb").sort.map { |f| File.basename(f, ".rb") }
+      end
+
+      def write_model_file(model, db_adapter)
+        table = Fresco.schema_tables.find { |t| t[:name] == model[:table] }
+        unless table
+          abort "[build] Fresco.model :#{model[:name]} references table :#{model[:table]} " \
+                "but db/schema.rb doesn't declare it"
+        end
+
+        columns = table[:columns]
+        pk_col  = columns.find { |c| c[:primary_key] }
+        unless pk_col
+          abort "[build] table :#{table[:name]} has no primary_key column; " \
+                "declare one with `column :id, :int, primary_key: true`"
+        end
+
+        data_cols = columns.reject { |c| c[:primary_key] }
+
+        # `find(id = 0)` — positional ctor with defaulted PK. The default
+        # acts as the type pin for Spinel ([[spinel_initialize_kwargs]],
+        # [[spinel_param_type_collapse]]).
+        ctor_params = columns.map { |c| "#{c[:name]} = #{col_zero(c)}" }.join(", ") +
+                      ", found = false"
+
+        pk_param = "#{pk_col[:name]} = 0"
+
+        row_ctor_args = columns.each_with_index.map { |c, i| col_read_expr(c, i, db_adapter) }.join(", ")
+
+        table_name = table[:name].to_s
+
+        select_by_pk_sql = "SELECT #{join_cols(columns)} FROM #{table_name} WHERE #{pk_col[:name]} = " \
+                           "#{db_adapter == :postgres ? '$1' : '?'}"
+        select_all_sql   = "SELECT #{join_cols(columns)} FROM #{table_name} ORDER BY #{pk_col[:name]}"
+
+        finders = model[:finders].map do |fname|
+          col = columns.find { |c| c[:name] == fname }
+          abort "[build] finder :#{fname} on :#{model[:name]} but no such column" unless col
+          {
+            name:        fname,
+            sql:         "SELECT #{join_cols(columns)} FROM #{table_name} WHERE #{fname} = " \
+                         "#{db_adapter == :postgres ? '$1' : '?'}",
+            count_sql:   "SELECT COUNT(*) FROM #{table_name} WHERE #{fname} = " \
+                         "#{db_adapter == :postgres ? '$1' : '?'}",
+            bind_call:   col_finder_bind_call(col),
+            default:     col_zero(col),
+            unique:      col[:index] == :unique,
+          }
+        end
+
+        count_sql = "SELECT COUNT(*) FROM #{table_name}"
+
+        validators = (model[:validators] || []).map do |v|
+          col = columns.find { |c| c[:name] == v[:column] }
+          abort "[build] validates :#{v[:column]} on :#{model[:name]} but no such column" unless col
+          case v[:rule]
+          when :presence
+            guard = case col[:type]
+                    when :str  then "#{col[:name]}.length == 0"
+                    when :int  then "#{col[:name]} == 0"
+                    when :bool then "#{col[:name]} == false"
+                    end
+            { column: v[:column], guard: guard, message: "#{col[:name]} required" }
+          else
+            abort "[build] unknown validation rule #{v[:rule].inspect} for :#{model[:name]}"
+          end
+        end
+
+        insert_bind_lines = data_cols.each_with_index.map { |c, i| col_bind_stmt(c, i + 1) }
+        insert_kwargs     = data_cols.map { |c| "#{c[:name]}: #{col_zero(c)}" }.join(", ")
+        insert_kwarg_sig  = data_cols.map { |c| "#{c[:name]}:" }.join(", ")
+
+        insert_sql = if db_adapter == :postgres
+          "INSERT INTO #{table_name} (#{join_cols(data_cols)}) VALUES (#{placeholders(data_cols.length, :postgres)}) RETURNING #{pk_col[:name]}"
+        else
+          "INSERT INTO #{table_name} (#{join_cols(data_cols)}) VALUES (#{placeholders(data_cols.length, :sqlite)})"
+        end
+
+        update_bind_lines = data_cols.each_with_index.map { |c, i| col_bind_stmt(c, i + 1) }
+        update_kwargs     = data_cols.map { |c| "#{c[:name]}: #{col_zero(c)}" }.join(", ")
+        update_kwarg_sig  = data_cols.map { |c| "#{c[:name]}:" }.join(", ")
+        pk_placeholder = db_adapter == :postgres ? "$#{data_cols.length + 1}" : "?"
+        update_sql = "UPDATE #{table_name} SET #{assignments(data_cols, db_adapter, 1)} WHERE #{pk_col[:name]} = #{pk_placeholder}"
+
+        delete_sql = "DELETE FROM #{table_name} WHERE #{pk_col[:name]} = " \
+                     "#{db_adapter == :postgres ? '$1' : '?'}"
+
+        file_stem = model[:name].to_s.gsub(/([a-z0-9])([A-Z])/, '\1_\2').downcase
+
+        File.write(
+          "#{MODELS_GEN_DIR}/#{file_stem}.rb",
+          render_template("model.rb.erb",
+            model_name:              model[:name].to_s,
+            file_stem:               file_stem,
+            table_name:              table_name,
+            adapter:                 db_adapter,
+            columns:                 columns,
+            pk_name:                 pk_col[:name],
+            pk_param:                pk_param,
+            ctor_params:             ctor_params,
+            row_ctor_args:           row_ctor_args,
+            select_by_pk_sql:        select_by_pk_sql,
+            select_all_sql:          select_all_sql,
+            finders:                 finders,
+            count_sql:               count_sql,
+            validators:              validators,
+            insert_bind_lines:       insert_bind_lines,
+            insert_kwargs:           insert_kwargs,
+            insert_kwarg_signature:  insert_kwarg_sig,
+            insert_sql:              insert_sql,
+            update_bind_lines:       update_bind_lines,
+            update_kwargs:           update_kwargs,
+            update_kwarg_signature:  update_kwarg_sig,
+            update_sql:              update_sql,
+            delete_sql:              delete_sql,
+          ),
+        )
+      end
+
+      # Per-column-type codegen helpers — see bin/build comment block in
+      # the pre-gem layout for the full rationale (col_str rotating-buffer
+      # quirk, bool adapter divergence, etc.).
+      def col_read_expr(col, idx, adapter)
+        case col[:type]
+        when :int  then "Fresco::Db.col_int(cid, #{idx})"
+        when :str  then "(Fresco::Db.col_str(cid, #{idx}) + \"\")"
+        when :bool
+          if adapter == :postgres
+            "(Fresco::Db.col_str(cid, #{idx}) == \"t\")"
+          else
+            "(Fresco::Db.col_int(cid, #{idx}) != 0)"
+          end
+        else abort "[build] unknown column type #{col[:type].inspect} on #{col[:name]}"
+        end
+      end
+
+      def col_bind_stmt(col, idx)
+        nm = col[:name].to_s.inspect
+        case col[:type]
+        when :int  then "Fresco::Db.bind_int(cid, #{idx}, #{col[:name]}, #{nm})"
+        when :str  then "Fresco::Db.bind_str(cid, #{idx}, #{col[:name]}, #{nm})"
+        when :bool then "Fresco::Db.bind_int(cid, #{idx}, #{col[:name]} ? 1 : 0, #{nm})"
+        else abort "[build] unknown column type #{col[:type].inspect} on #{col[:name]}"
+        end
+      end
+
+      def col_zero(col)
+        case col[:type]
+        when :int  then "0"
+        when :str  then '""'
+        when :bool then "false"
+        else abort "[build] unknown column type #{col[:type].inspect} on #{col[:name]}"
+        end
+      end
+
+      def col_finder_bind_call(col)
+        nm = col[:name].to_s.inspect
+        case col[:type]
+        when :int  then "Fresco::Db.bind_int(cid, 1, #{col[:name]}, #{nm})"
+        when :str  then "Fresco::Db.bind_str(cid, 1, #{col[:name]}, #{nm})"
+        when :bool then "Fresco::Db.bind_int(cid, 1, #{col[:name]} ? 1 : 0, #{nm})"
+        end
+      end
+
+      def join_cols(columns)
+        columns.map { |c| c[:name].to_s }.join(", ")
+      end
+
+      def placeholders(n, adapter)
+        if adapter == :postgres
+          (1..n).map { |i| "$#{i}" }.join(", ")
+        else
+          Array.new(n, "?").join(", ")
+        end
+      end
+
+      def assignments(columns, adapter, start_idx = 1)
+        columns.map.with_index do |c, i|
+          ph = adapter == :postgres ? "$#{start_idx + i}" : "?"
+          "#{c[:name]} = #{ph}"
+        end.join(", ")
+      end
+
+      # --- Emit migrations.rb (embedded SQL + runner) ------------------
+      def emit_migrations(db_adapter)
+        Dir.glob("db/migrations/*.rb").sort.each { |f| load f }
+
+        migrations_data = Fresco.migrations.map do |m|
+          suffix = m[:name].to_s.gsub(/[^A-Za-z0-9_]/, "_")
+          { name: m[:name], method_suffix: suffix, up_sql: m[:up_sql], down_sql: m[:down_sql] }
+        end
+
+        pl_q = db_adapter == :postgres ? "$1" : "?"
+
+        File.write(
+          "#{GEN_DIR}/migrations.rb",
+          render_template("migrations.rb.erb",
+            migrations:          migrations_data,
+            applied_sql:         "SELECT COUNT(*) FROM schema_migrations WHERE name = #{pl_q}",
+            insert_applied_sql:  "INSERT INTO schema_migrations (name) VALUES (#{pl_q})",
+            delete_applied_sql:  "DELETE FROM schema_migrations WHERE name = #{pl_q}",
+          ),
+        )
+      end
+
+      # --- Emit requires.rb (model + action manifest) ------------------
+      def emit_requires_manifest(action_files, generated_models, has_root)
+        model_require_paths = generated_models.map { |stem| "models/#{stem}" }
+        action_paths = model_require_paths + ["../app/action"] + action_files.map do |f|
+          f.sub(%r{\Aapp/actions/}, "../app/actions/").sub(/\.rb\z/, "")
+        end
+        action_paths.unshift("welcome") unless has_root
+        File.write("#{GEN_DIR}/requires.rb", render_template("manifest.rb.erb", kind: "action", paths: action_paths))
+      end
+
+      # --- Emit boot.rb ------------------------------------------------
+      def emit_boot
+        FileUtils.cp("#{RUNTIME_DIR}/boot.rb", "#{GEN_DIR}/boot.rb")
+      end
+
+      # --- Emit view modules (Herb::Engine → render_<name>) ------------
+      def emit_views
+        view_files = Dir.glob("app/views/**/*.html.erb").sort
+        Dir.glob("#{VIEWS_GEN_DIR}/*.rb").each { |f| File.delete(f) }
+
+        view_names   = []
+        layout_names = []
+        view_files.each do |path|
+          rel    = path.sub(%r{\Aapp/views/}, "")
+          source = File.read(path)
+
+          signature = +""
+          if (m = source.match(LOCALS_RE))
+            signature = m[1]
+            source = source.sub(LOCALS_RE, "")
+          end
+
+          if layout_file?(rel)
+            source    = source.gsub(LAYOUT_YIELD_RE, "<%== content %>")
+            signature = inject_layout_kwargs(signature)
+            layout_names << layout_name_from(rel)
+          end
+
+          source = rewrite_partial_renders(source, rel)
+
+          src = Herb::Engine.new(
+            source,
+            filename:   path,
+            escape:     true,
+            escapefunc: "::Spinel::View.h",
+            attrfunc:   "::Spinel::View.attr",
+            jsfunc:     "::Spinel::View.js",
+            cssfunc:    "::Spinel::View.css",
+          ).src
+          src = split_static_view_literals(src)
+
+          name = view_method_name(rel)
+          File.write(
+            "#{VIEWS_GEN_DIR}/#{name}.rb",
+            render_template("view.rb.erb", rel: rel, name: name, signature: signature, src: src),
+          )
+          view_names << name
+        end
+
+        view_paths = view_names.map { |n| "views/#{n}" }
+        File.write("#{GEN_DIR}/views.rb", render_template("manifest.rb.erb", kind: "view", paths: view_paths))
+
+        [view_names, layout_names]
+      end
+
+      def view_method_name(rel)
+        rel.sub(/\.html\.erb\z/, "").tr("/", "_")
+      end
+
+      # Build-time rewrite of `<%= render partial: "name", locals: {...} %>`
+      # to a typed direct call. Spinel's poly-hash collapse means we can't
+      # ship the locals hash to runtime — splice as kwargs instead.
+      def resolve_partial(name, source_rel)
+        candidates =
+          if name.include?("/")
+            parts = name.split("/")
+            parts[-1] = "_#{parts[-1]}"
+            ["#{parts.join('/')}.html.erb"]
+          else
+            list = []
+            folder = File.dirname(source_rel)
+            loop do
+              if folder == "."
+                list << "_#{name}.html.erb"
+                break
+              end
+              list << "#{folder}/_#{name}.html.erb"
+              folder = File.dirname(folder)
+            end
+            list
+          end
+        resolved = candidates.find { |c| File.exist?("app/views/#{c}") }
+        unless resolved
+          abort "[build] partial #{name.inspect} not found from app/views/#{source_rel} " \
+                "(tried: #{candidates.map { |c| "app/views/#{c}" }.join(", ")})"
+        end
+        view_method_name(resolved)
+      end
+
+      def rewrite_partial_renders(source, source_rel)
+        source.gsub(PARTIAL_RENDER_RE) do
+          method_name = "render_#{resolve_partial($1, source_rel)}"
+          locals_body = ($2 || "").strip
+          "<%== #{method_name}(#{locals_body}) %>"
+        end
+      end
+
+      def layout_file?(rel)
+        rel.start_with?("layouts/")
+      end
+
+      def layout_name_from(rel)
+        rel.sub(%r{\Alayouts/}, "").sub(/\.html\.erb\z/, "").tr("/", "_")
+      end
+
+      def inject_layout_kwargs(sig)
+        return "(#{LAYOUT_FRAMEWORK_KWARGS})" if sig.empty?
+        sig.sub(/\)\z/, ", #{LAYOUT_FRAMEWORK_KWARGS})")
+      end
+
+      def odd_backslashes_before?(src, idx)
+        count = 0
+        i = idx - 1
+        while i >= 0 && src[i] == "\\"
+          count += 1
+          i -= 1
+        end
+        count.odd?
+      end
+
+      def find_single_quote_end(src, start)
+        i = start
+        while i < src.length
+          return i if src[i] == "'" && !odd_backslashes_before?(src, i)
+          i += 1
+        end
+        raise "[build] unterminated Herb string literal in generated view source"
+      end
+
+      def trailing_backslashes_odd?(src)
+        count = 0
+        i = src.length - 1
+        while i >= 0 && src[i] == "\\"
+          count += 1
+          i -= 1
+        end
+        count.odd?
+      end
+
+      def split_single_quoted_content(content)
+        return [content] if content.length <= MAX_VIEW_LITERAL_BYTES
+
+        chunks = []
+        i = 0
+        while i < content.length
+          j = [i + MAX_VIEW_LITERAL_BYTES, content.length].min
+          if j < content.length
+            j -= 1 while j > i && trailing_backslashes_odd?(content[i...j])
+            j = [i + MAX_VIEW_LITERAL_BYTES, content.length].min if j == i
+          end
+          chunks << content[i...j]
+          i = j
+        end
+        chunks
+      end
+
+      def split_static_view_literals(src)
+        out = +""
+        i = 0
+        while (pos = src.index(STATIC_APPEND_PREFIX, i))
+          out << src[i...pos]
+          content_start = pos + STATIC_APPEND_PREFIX.length
+          quote_end = find_single_quote_end(src, content_start)
+          after_quote = quote_end + 1
+
+          unless src[after_quote, ".freeze".length] == ".freeze"
+            out << src[pos...after_quote]
+            i = after_quote
+            next
+          end
+
+          chunks = split_single_quoted_content(src[content_start...quote_end])
+          out << chunks.map { |chunk| "#{STATIC_APPEND_PREFIX}#{chunk}#{STATIC_APPEND_SUFFIX}" }.join("; ")
+          i = after_quote + ".freeze".length
+        end
+        out << src[i..] if i < src.length
+        out
+      end
+
+      # --- Emit layout_dispatch.rb -------------------------------------
+      def emit_layout_dispatch(layout_names)
+        File.write(
+          "#{GEN_DIR}/layout_dispatch.rb",
+          render_template("layout_dispatch.rb.erb", layout_names: layout_names),
+        )
+      end
+    end
+  end
+end

data/lib/fresco/cli/dev.rb

@@ -0,0 +1,17 @@
+module Fresco
+  class CLI
+    class Dev
+      # The dev loop relies on top-level method and constant definitions
+      # in the loaded generated/runtime.rb (Request, Response, Sock,
+      # dispatch_request, Color, parse_query_string!, …). Keeping the
+      # loop itself as a top-level script preserves that scoping —
+      # methods defined in dev_loop.rb live in the same Object scope as
+      # the things `load "generated/runtime.rb"` defines.
+      def run(argv)
+        ARGV.replace(argv)
+        Kernel.load(File.expand_path("dev_loop.rb", __dir__))
+        0
+      end
+    end
+  end
+end