lilac-cli 0.2.0

data/lib/lilac/cli/build/vendor_writer.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+
+module Lilac
+  module CLI
+    # Stages a wasm runtime + its JS bridge into `dist/vendor/<name>/`
+    # so a built site is fully self-contained. Used for both the
+    # `:full` and `:compiled` target vendor steps — the two paths only
+    # differ in how the source files are resolved (gem soft-require vs
+    # CompiledRuntimeResolver) and in the vendored wasm's filename.
+    # The copy mechanics — mkdir, single-file wasm cp, bridge dir
+    # walk skipping subdirectories — are the same for both.
+    module VendorWriter
+      # Single source of truth for the runtime assets a self-contained
+      # (offline-runnable) dist must carry, per build target, as paths
+      # relative to the dist root. Consumed by `Builder` (the :full skip
+      # guard), `OfflineVerifier` (presence check), and `Doctor`
+      # (`RUNTIME_WASM` / `RUNTIME_JS_ADAPTER`) so the definition of "a
+      # complete vendored runtime" lives in exactly one place.
+      #
+      # Each value names its roles (`:wasm` / `:bridge`) so consumers
+      # reference by meaning, not array position. The wasm basename
+      # differs by target (`lilac-full.wasm` vs the vendored `lilac.wasm`);
+      # the bridge entry is the shared `mruby-wasm-js/index.js`. The
+      # vendor directory of a target is `File.dirname(...[:wasm])`.
+      REQUIRED_ASSETS = {
+        full: {
+          wasm:   'vendor/lilac-full/lilac-full.wasm',
+          bridge: 'vendor/lilac-full/mruby-wasm-js/index.js',
+        }.freeze,
+        compiled: {
+          wasm:   'vendor/lilac-compiled/lilac.wasm',
+          bridge: 'vendor/lilac-compiled/mruby-wasm-js/index.js',
+        }.freeze,
+      }.freeze
+
+      module_function
+
+      # Copy `wasm_src` to `<vendor_dir>/<wasm_name>` and every regular
+      # file directly inside `bridge_src` to `<vendor_dir>/mruby-wasm-js/`.
+      # Subdirectories of `bridge_src` are intentionally skipped — the
+      # bridge ships as a flat js/ directory and any nested folders are
+      # build artifacts the runtime doesn't read.
+      def copy!(wasm_src:, bridge_src:, vendor_dir:, wasm_name:)
+        bridge_out = File.join(vendor_dir, 'mruby-wasm-js')
+        FileUtils.mkdir_p(bridge_out)
+
+        FileUtils.cp(wasm_src, File.join(vendor_dir, wasm_name))
+        Dir.glob(File.join(bridge_src, '*')).each do |entry|
+          next if File.directory?(entry)
+
+          FileUtils.cp(entry, File.join(bridge_out, File.basename(entry)))
+        end
+      end
+    end
+  end
+end

data/lib/lilac/cli/build/wasm_mrbc_driver.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+module Lilac
+  module CLI
+    # Drives `mrbc-host.wasm` from the host Ruby via `wasmtime-rb` to
+    # produce mruby bytecode in place of an external `mrbc` binary.
+    #
+    # Wire-level ABI (defined in `runtime/mruby-host-compile/src/host_compile.c`):
+    #
+    #   compile_source(src_ptr, src_len,
+    #                  out_ptr_outp, out_len_outp,
+    #                  err_ptr_outp, err_len_outp) -> i32 status
+    #   mrbc_alloc(len) -> i32 ptr   (host writes/reads through this buffer)
+    #   mrbc_free(ptr)               (host frees both input and output)
+    #
+    # Status codes:
+    #   0  ok           — irep bytes in out_ptr / out_len
+    #   1  compile fail — utf-8 message in err_ptr / err_len
+    #   2  no compiler  — wasm was built without mruby-compiler
+    #
+    # Lifecycle: the engine + module + instance are created once on the
+    # first `compile` call and reused across subsequent calls within a
+    # single `BytecodeBuilder` invocation. mruby's `mrb_state` itself is
+    # opened/closed *inside* the wasm per call (see `compile_source` in
+    # host_compile.c) — this matches `mrbc` binary's process-per-invocation
+    # semantics and keeps symbol-table growth from leaking across builds.
+    class WasmMrbcDriver
+      class Error < StandardError; end
+      class WasmtimeMissingError < Error; end
+      class WasmExportMissingError < Error; end
+      class CompileError < Error; end
+
+      REQUIRED_EXPORTS = %w[compile_source mrbc_alloc mrbc_free memory].freeze
+
+      # Test whether a usable backend can be constructed from `wasm_path`.
+      # Returns true only when wasmtime-rb is loadable AND the module
+      # parses + instantiates AND all required exports are present.
+      #
+      # Used by `BytecodeBuilder#resolve_backend!` to decide between the
+      # wasm-driven and binary mrbc paths; also surfaced via `lilac doctor`
+      # so users can see exactly why the wasm path was/wasn't picked.
+      #
+      # wasmtime-rb's `Module` doesn't expose `exports` directly, so we
+      # actually instantiate to enumerate the exports. The cost (~200-500ms
+      # cold) is paid once per `lilac build`, which is acceptable for a
+      # build-time tool.
+      def self.available?(wasm_path:)
+        return false unless wasm_path && File.file?(wasm_path)
+
+        begin
+          require 'wasmtime'
+        rescue LoadError
+          return false
+        end
+
+        begin
+          engine = Wasmtime::Engine.new(wasm_exceptions: true)
+          mod = Wasmtime::Module.from_file(engine, wasm_path)
+          linker = Wasmtime::Linker.new(engine)
+          Wasmtime::WASI::P1.add_to_linker_sync(linker)
+          store = Wasmtime::Store.new(engine, wasi_p1_config: Wasmtime::WasiConfig.new)
+          instance = linker.instantiate(store, mod)
+          REQUIRED_EXPORTS.all? { |name| !instance.export(name).nil? }
+        rescue Wasmtime::Error, ArgumentError
+          false
+        end
+      end
+
+      def initialize(wasm_path:)
+        @wasm_path = wasm_path
+      end
+
+      attr_reader :wasm_path
+
+      # Compile a Ruby source string and return the raw mruby bytecode
+      # (binary string, starts with "RITE" magic). Raises CompileError on
+      # syntax/semantic errors (carrying the parser's error buffer text)
+      # or WasmExportMissingError / WasmtimeMissingError on environment
+      # problems.
+      def compile(ruby_source)
+        ensure_instance!
+
+        # mrbc_alloc returns 0 on size <= 0 or malloc failure. We allocate
+        # six buffers per call:
+        #   src_buf    — caller-written source bytes
+        #   out_p/out_l — out-params written by compile_source on success
+        #   err_p/err_l — out-params written by compile_source on failure
+        # The three out-param pairs are 4-byte i32 each.
+        src_bytes = ruby_source.b
+        src_buf = @alloc.call(src_bytes.bytesize)
+        raise CompileError, 'mrbc_alloc returned 0 for src buffer' if src_buf.zero?
+
+        out_p = @alloc.call(4)
+        out_l = @alloc.call(4)
+        err_p = @alloc.call(4)
+        err_l = @alloc.call(4)
+        if [out_p, out_l, err_p, err_l].any?(&:zero?)
+          [src_buf, out_p, out_l, err_p, err_l].each { |p| @free.call(p) unless p.zero? }
+          raise CompileError, 'mrbc_alloc returned 0 for out-param buffers'
+        end
+
+        @memory.write(src_buf, src_bytes)
+
+        status = @compile.call(src_buf, src_bytes.bytesize, out_p, out_l, err_p, err_l)
+
+        irep_ptr = read_i32(out_p)
+        irep_len = read_i32(out_l)
+        err_ptr  = read_i32(err_p)
+        err_len  = read_i32(err_l)
+
+        case status
+        when 0
+          bytecode = @memory.read(irep_ptr, irep_len)
+          @free.call(irep_ptr)
+          bytecode
+        when 1
+          message = err_len.positive? ? @memory.read(err_ptr, err_len).force_encoding('UTF-8') : '(no message)'
+          @free.call(err_ptr) unless err_ptr.zero?
+          raise CompileError, message
+        when 2
+          raise WasmExportMissingError,
+                'mrbc-host.wasm was built without mruby-compiler — rebuild with build_config/mrbc-host.rb'
+        else
+          raise CompileError, "compile_source returned unexpected status=#{status}"
+        end
+      ensure
+        # Free the input buffer and the four out-param scratch buffers.
+        # irep_ptr / err_ptr were freed inside the case branches because
+        # they're the wasm's own malloc'd outputs (separate from the
+        # 4-byte holders the host allocated for the pointer values).
+        [src_buf, out_p, out_l, err_p, err_l].compact.each do |p|
+          @free.call(p) unless p.zero?
+        end
+      end
+
+      private
+
+      # Lazy initialization: avoid paying the ~200-500ms wasmtime cold
+      # compile cost if the caller only uses `available?` for discovery
+      # and never actually compiles anything.
+      def ensure_instance!
+        return if @instance
+
+        begin
+          require 'wasmtime'
+        rescue LoadError => e
+          raise WasmtimeMissingError, "wasmtime-rb not available: #{e.message}"
+        end
+
+        @engine = Wasmtime::Engine.new(wasm_exceptions: true)
+        @module = Wasmtime::Module.from_file(@engine, @wasm_path)
+
+        # WASI is wired even though host_compile.c doesn't deliberately
+        # call into it — mruby-wasm-runtime / wasi-libc reference fd_write,
+        # fd_fdstat_get, etc. at link time even when those code paths are
+        # unreachable, so wasmtime requires the imports to be satisfied.
+        linker = Wasmtime::Linker.new(@engine)
+        Wasmtime::WASI::P1.add_to_linker_sync(linker)
+        store = Wasmtime::Store.new(@engine, wasi_p1_config: Wasmtime::WasiConfig.new)
+        @instance = linker.instantiate(store, @module)
+
+        if (init = @instance.export('_initialize')&.to_func)
+          init.call
+        end
+
+        @memory  = export_or_raise('memory').to_memory
+        @alloc   = export_or_raise('mrbc_alloc').to_func
+        @free    = export_or_raise('mrbc_free').to_func
+        @compile = export_or_raise('compile_source').to_func
+      end
+
+      def export_or_raise(name)
+        @instance.export(name) ||
+          raise(WasmExportMissingError,
+                "#{File.basename(@wasm_path)} is missing required export `#{name}`")
+      end
+
+      def read_i32(ptr)
+        @memory.read(ptr, 4).unpack1('l<')
+      end
+    end
+  end
+end

data/lib/lilac/cli/command.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+require_relative "subcommand/build"
+require_relative "subcommand/dev"
+require_relative "subcommand/preview"
+require_relative "subcommand/new"
+require_relative "subcommand/doctor"
+require_relative "subcommand/package_build"
+
+module Lilac
+  module CLI
+    # Entry point for `exe/lilac`. Routes argv[0] to the matching
+    # `Subcommand::*` handler; each subcommand owns its own OptionParser
+    # and `run` method. The outer rescue here keeps the user-facing
+    # error surface uniform (Builder::Error / ConfigLoader::LoadError /
+    # etc. → "lilac: <msg>" + exit 1).
+    class Command
+      SUBCOMMAND_HANDLERS = {
+        "build"         => Subcommand::Build,
+        "dev"           => Subcommand::Dev,
+        "preview"       => Subcommand::Preview,
+        "new"           => Subcommand::New,
+        "doctor"        => Subcommand::Doctor,
+        "package-build" => Subcommand::PackageBuild,
+      }.freeze
+
+      def initialize(argv, out: $stdout, err: $stderr)
+        @argv = argv.dup
+        @out = out
+        @err = err
+      end
+
+      # Returns an exit status (0 for success).
+      def run
+        name = @argv.shift || "help"
+
+        return print_version if name == "--version"
+        return run_help if %w[help -h --help].include?(name)
+
+        if (handler = SUBCOMMAND_HANDLERS[name])
+          handler.new(@argv, out: @out, err: @err).run
+        else
+          @err.puts "lilac: unknown command #{name.inspect}"
+          @err.puts
+          print_help(io: @err)
+          1
+        end
+      rescue Builder::Error, SFC::ParseError, Scaffold::Error,
+             ConfigLoader::LoadError, PreviewServer::Error,
+             PackageBuild::Error => e
+        @err.puts "lilac: #{e.message}"
+        1
+      end
+
+      # `lilac help` shows the top-level help; `lilac help <subcmd>`
+      # shows the per-subcommand option list (sourced from the same
+      # OptionParser that the subcommand uses, so it stays in sync).
+      def run_help
+        topic = @argv.shift
+        case topic
+        when nil, "help", "-h", "--help"
+          print_help
+          0
+        else
+          if (handler = SUBCOMMAND_HANDLERS[topic])
+            @out.puts handler.help_text
+            0
+          else
+            @err.puts "lilac help: unknown command #{topic.inspect}"
+            @err.puts
+            print_help(io: @err)
+            1
+          end
+        end
+      end
+
+      private
+
+      def print_help(io: @out)
+        io.puts <<~HELP
+          lilac — build .lil single-file components into static HTML
+
+          Usage:
+            lilac <command> [options]
+
+          Commands:
+            new <name>  Scaffold a new Lilac app
+            build       Compile components/ + pages/ into dist/
+            dev         Build, serve, watch — live reload on changes
+            preview     Serve the built dist/ as a static site (no watch / reload)
+            doctor      Verify project setup (runtime, references, paths)
+            package-build  Compile pure-Ruby package source(s) to `.mrb` bytecode
+            help        Show this help
+            --version   Print version
+
+          Tip: place the mruby-wasm runtime under public/vendor/. Run
+          `lilac doctor` to check the setup.
+
+          Run `lilac help <command>` or `lilac <command> --help` for
+          command-specific options.
+        HELP
+      end
+
+      def print_version
+        @out.puts "lilac-cli #{VERSION}"
+        0
+      end
+    end
+  end
+end

data/lib/lilac/cli/config.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+require_relative "config_loader"
+
+module Lilac
+  module CLI
+    # Holds resolved paths and server settings for the build pipeline.
+    # Three sources, in increasing precedence:
+    #
+    #   1. Built-in defaults (DEFAULT_* constants below)
+    #   2. `lilac.config.rb` at the project root (via ConfigLoader)
+    #   3. CLI flags (`--components`, `--port`, etc.)
+    #
+    # Most call sites should use `Config.load(opts)`, which performs the
+    # three-way merge in one shot. `Config.new(...)` remains for tests
+    # and callers that want to construct a config without a file.
+    class Config
+      DEFAULT_COMPONENTS_DIR = "components"
+      DEFAULT_PAGES_DIR = "pages"
+      DEFAULT_OUTPUT_DIR = "dist"
+      # Static files in `public/` are mirrored to `output_dir/` at
+      # build time (Vite / Eleventy / Astro convention). The directory
+      # itself is optional — Builder skips silently when absent.
+      DEFAULT_PUBLIC_DIR = "public"
+      DEFAULT_DEV_HOST = "127.0.0.1"
+      DEFAULT_DEV_PORT = 5173
+
+      # Build target. `:full` (default) emits dist HTML with inline Ruby
+      # script tags loaded by the lilac-full wasm at runtime — the
+      # original Lilac story, no extra tooling needed. `:compiled` emits
+      # pre-compiled mruby bytecode (`.mrb`) loaded by lilac-compiled
+      # wasm — smaller production bundle (~32% brotli), but requires
+      # `mrbc` in the build environment (see DEFAULT_MRBC_CANDIDATES).
+      #
+      # Mirrors Vite's dev/prod two-stage philosophy:
+      # - `lilac dev` defaults to `:full` so the development loop stays
+      #   mrbc-free and gets the runtime parser for fast iteration.
+      # - `lilac build` defaults to `:compiled` so production deploys
+      #   ship the smaller bundle by default — opt out with
+      #   `--target full` when you want the runtime parser in dist.
+      DEFAULT_BUILD_TARGET = :compiled
+      DEFAULT_DEV_TARGET   = :full
+      TARGET_VALUES = %i[full compiled].freeze
+
+      # Delivery mode for component templates + scripts:
+      #   :inline — embed everything in each page's HTML (current default)
+      #   :bundle — emit a single lilac.bundle.html, page HTML references it
+      #             via <link rel="lilac-bundle">
+      DEFAULT_DELIVERY = :inline
+      DELIVERY_VALUES = %i[inline bundle].freeze
+
+      attr_reader :root, :components_dir, :pages_dir, :output_dir, :public_dir,
+                  :dev_host, :dev_port,
+                  :build_target, :dev_target, :mrbc_path,
+                  :lilac_compiled_path, :lilac_full_path, :mruby_wasm_js_path,
+                  :packages, :delivery
+
+      # Three-way merge: CLI opts > lilac.config.rb > built-in defaults.
+      # `opts` keys mirror the keyword args of `initialize`; nil values
+      # mean "no CLI override given" and let the file/default win.
+      def self.load(root: nil, components_dir: nil, pages_dir: nil, output_dir: nil,
+                    public_dir: nil, dev_host: nil, dev_port: nil,
+                    build_target: nil, dev_target: nil, mrbc_path: nil,
+                    lilac_compiled_path: nil, lilac_full_path: nil,
+                    mruby_wasm_js_path: nil,
+                    packages: nil, delivery: nil)
+        resolved_root = File.expand_path(root || Dir.pwd)
+        settings = ConfigLoader.load(resolved_root) || ConfigLoader::Settings.new
+
+        new(
+          root: resolved_root,
+          components_dir: components_dir || settings.components_dir,
+          pages_dir:   pages_dir   || settings.pages_dir,
+          output_dir:  output_dir  || settings.output_dir,
+          public_dir:  public_dir  || settings.public_dir,
+          dev_host:    dev_host    || settings.dev_host,
+          dev_port:    dev_port    || settings.dev_port,
+          build_target: build_target || settings.build_target,
+          dev_target:   dev_target   || settings.dev_target,
+          mrbc_path:    mrbc_path    || settings.mrbc_path,
+          lilac_compiled_path: lilac_compiled_path || settings.lilac_compiled_path,
+          lilac_full_path:     lilac_full_path     || settings.lilac_full_path,
+          mruby_wasm_js_path:  mruby_wasm_js_path  || settings.mruby_wasm_js_path,
+          packages:    packages    || settings.packages,
+          delivery:    delivery    || settings.delivery,
+        )
+      end
+
+      def initialize(root: nil, components_dir: nil, pages_dir: nil, output_dir: nil,
+                     public_dir: nil, dev_host: nil, dev_port: nil,
+                     build_target: nil, dev_target: nil, mrbc_path: nil,
+                     lilac_compiled_path: nil, lilac_full_path: nil,
+                     mruby_wasm_js_path: nil,
+                     packages: nil, delivery: nil)
+        # Use `|| Dir.pwd` rather than a default keyword so callers can
+        # pass `root: opts[:root]` (often nil from un-set CLI flags)
+        # without overriding the default to nil.
+        @root = File.expand_path(root || Dir.pwd)
+        @components_dir = expand(components_dir || DEFAULT_COMPONENTS_DIR)
+        @pages_dir = expand(pages_dir || DEFAULT_PAGES_DIR)
+        @output_dir = expand(output_dir || DEFAULT_OUTPUT_DIR)
+        @public_dir = expand(public_dir || DEFAULT_PUBLIC_DIR)
+        @dev_host = dev_host || DEFAULT_DEV_HOST
+        @dev_port = dev_port || DEFAULT_DEV_PORT
+        @build_target = normalize_target(build_target || DEFAULT_BUILD_TARGET, kind: "build_target")
+        @dev_target   = normalize_target(dev_target   || DEFAULT_DEV_TARGET,   kind: "dev_target")
+        # nil = auto-discover at use time (see BytecodeBuilder.resolve_mrbc).
+        @mrbc_path = mrbc_path
+        # nil = auto-discover via CompiledRuntimeResolver (env / monorepo
+        # ancestor / node_modules).
+        @lilac_compiled_path = lilac_compiled_path
+        # nil = auto-discover via FullRuntimeResolver (env / gem /
+        # monorepo). Parallel to @lilac_compiled_path.
+        @lilac_full_path     = lilac_full_path
+        @mruby_wasm_js_path  = mruby_wasm_js_path
+        # Pre-compiled Lilac package `.mrb` paths (advanced override
+        # path — most users get packages via Bundler auto-discovery,
+        # see decisions §25/§26). Each entry is resolved against `@root`
+        # so relative paths Just Work. Nil from Config.load is
+        # normalized to an empty array.
+        @packages = (packages || []).map { |p| expand(p) }
+        @delivery = normalize_delivery(delivery || DEFAULT_DELIVERY)
+      end
+
+      private
+
+      def expand(path)
+        File.expand_path(path, @root)
+      end
+
+      def normalize_target(value, kind:)
+        sym = value.to_sym
+        unless TARGET_VALUES.include?(sym)
+          raise ArgumentError,
+                "#{kind} must be one of #{TARGET_VALUES.inspect}, got #{value.inspect}"
+        end
+        sym
+      end
+
+      def normalize_delivery(value)
+        sym = value.to_sym
+        unless DELIVERY_VALUES.include?(sym)
+          raise ArgumentError,
+                "delivery must be one of #{DELIVERY_VALUES.inspect}, got #{value.inspect}"
+        end
+        sym
+      end
+    end
+  end
+end

data/lib/lilac/cli/config_loader.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module Lilac
+  module CLI
+    # Reads `lilac.config.rb` from a project root. The file uses the
+    # `Lilac::CLI.configure` DSL:
+    #
+    #   Lilac::CLI.configure do |c|
+    #     c.components_dir = "src/components"
+    #     c.dev_port    = 3000
+    #   end
+    #
+    # Unset fields stay nil so callers (Config.load) can fall through to
+    # their hardcoded defaults. The DSL is only callable during a
+    # `ConfigLoader.load` invocation; calling it outside that context
+    # raises, which catches typos like `Lilac.configure { ... }` in
+    # arbitrary scripts.
+    class ConfigLoader
+      DEFAULT_FILENAME = "lilac.config.rb"
+
+      # Fields here are the union of every value the CLI knows how to
+      # configure. Keep in sync with Config defaults.
+      Settings = Struct.new(
+        :components_dir, :pages_dir, :public_dir, :output_dir,
+        :dev_host, :dev_port,
+        # build_target / dev_target: `:full` (default) ships dist HTML
+        # with inline Ruby + lilac-full wasm; `:compiled` ships .mrb
+        # bytecode + lilac-compiled wasm. mrbc_path overrides the
+        # auto-discovery in BytecodeBuilder.
+        :build_target, :dev_target, :mrbc_path,
+        # Overrides for the runtime discovery (see CompiledRuntimeResolver
+        # / FullRuntimeResolver). All nil = auto-discover via
+        # env / lilac-wasm-bin gem / monorepo ancestor.
+        # `lilac_full_path` overrides the `--target full` wasm.
+        :lilac_compiled_path, :lilac_full_path, :mruby_wasm_js_path,
+        # `packages` — Array<String> of paths (absolute or
+        # project-root-relative) pointing at pre-compiled Lilac package
+        # `.mrb` files. Advanced override; most users get packages via
+        # Bundler auto-discovery (`Lilac::CLI::PackageDiscovery`).
+        # At build time the CLI copies each to `dist/packages/` and
+        # the generated boot script `loadBytecode`s them before user
+        # code. See decisions §25 / §26 + `docs/lilac-package-spec.md`.
+        :packages,
+        # `delivery` — :inline (default) embeds component definitions
+        # in each page's HTML; :bundle emits a single lilac.bundle.html
+        # referenced from each page via <link rel="lilac-bundle">. See
+        # lilac-proposals.md for the bundle-fetch strategy.
+        :delivery,
+        keyword_init: true,
+      )
+
+      class LoadError < StandardError; end
+
+      # Loads `<root>/lilac.config.rb` if present and returns a
+      # Settings struct (with nils for unset fields). Returns nil when
+      # the file doesn't exist — callers treat that as "use defaults".
+      def self.load(root, filename: DEFAULT_FILENAME)
+        path = File.join(root, filename)
+        return nil unless File.file?(path)
+
+        settings = Settings.new
+        with_settings(settings) do
+          begin
+            Kernel.load(path)
+          rescue StandardError, ScriptError => e
+            raise LoadError, "Error loading #{filename}: #{e.message}"
+          end
+        end
+        settings
+      end
+
+      # Singleton stash so `Lilac::CLI.configure` can find the active
+      # Settings without each config file passing it explicitly.
+      def self.with_settings(settings)
+        previous = Thread.current[:lilac_cli_settings]
+        Thread.current[:lilac_cli_settings] = settings
+        yield
+      ensure
+        Thread.current[:lilac_cli_settings] = previous
+      end
+
+      def self.current_settings
+        Thread.current[:lilac_cli_settings]
+      end
+    end
+
+    # Public DSL hook. `lilac.config.rb` calls this; outside a
+    # ConfigLoader.load it raises so accidental misuse fails loudly.
+    def self.configure
+      settings = ConfigLoader.current_settings
+      raise ConfigLoader::LoadError,
+            "Lilac::CLI.configure must be called from lilac.config.rb" unless settings
+
+      yield settings
+    end
+  end
+end