lilac-cli 0.2.0

data/lib/lilac/cli/live_reload.rb

@@ -0,0 +1,194 @@
+# frozen_string_literal: true
+
+require "wsv"
+
+module Lilac
+  module CLI
+    # SSE pub/sub for the dev server's live-reload endpoint.
+    #
+    # Each connected browser holds an open SSE response served by `#call`.
+    # When `notify_all` fires (because the file watcher detected a build),
+    # every subscriber receives a "reload" event and refreshes.
+    #
+    # Subscribers are tracked as `Queue` instances; subscription cleanup
+    # happens in an `ensure` so a closed/aborted client doesn't leak.
+    class LiveReload
+      ENDPOINT_PATH = "/__lilac/livereload"
+
+      # `:keepalive` is a SSE-comment frame: clients ignore it, but
+      # writing it lets us detect a dropped connection (the write raises
+      # Errno::EPIPE) when no real reload event has fired in a while.
+      # Short interval keeps dead subscribers from clogging the wsv
+      # connection-throttle pool (default cap 8) on rapid page reloads —
+      # without this we'd see 503s after ~8 reloads within 30 s.
+      KEEPALIVE_INTERVAL = 5
+
+      # Client snippet injected by the builder into every dev-server page.
+      # Subscribes to the dev server's SSE channel and handles two event
+      # types:
+      #
+      #   - default `message` event → successful rebuild, reload the page
+      #     (any in-page error overlay is implicitly discarded by the
+      #     reload, no explicit cleanup needed)
+      #   - `error` event → build failed; render an in-page overlay with
+      #     the error type + message so the dev sees the failure without
+      #     switching to the terminal
+      #
+      # The overlay is intentionally inline-styled and self-contained
+      # (`__lilac_err_overlay`), no dependency on user styles.
+      SCRIPT = <<~HTML
+        <script>
+          // lilac dev: live reload + error overlay via SSE
+          (function () {
+            const ES_URL = "/__lilac/livereload";
+            const OVERLAY_ID = "__lilac_err_overlay";
+
+            function renderOverlay(payload) {
+              document.getElementById(OVERLAY_ID)?.remove();
+              const root = document.createElement("div");
+              root.id = OVERLAY_ID;
+              root.setAttribute("style", [
+                "position:fixed", "inset:0", "z-index:2147483647",
+                "background:rgba(0,0,0,0.78)", "color:#fff",
+                "font:14px/1.5 ui-monospace,SFMono-Regular,Menlo,monospace",
+                "padding:32px", "overflow:auto",
+              ].join(";"));
+
+              const panel = document.createElement("div");
+              panel.setAttribute("style", [
+                "max-width:880px", "margin:0 auto",
+                "background:#1f1f23", "border:1px solid #ff5b6c",
+                "border-radius:8px", "padding:20px 24px",
+                "box-shadow:0 12px 40px rgba(0,0,0,0.45)",
+              ].join(";"));
+
+              const head = document.createElement("div");
+              head.setAttribute("style", "display:flex;justify-content:space-between;align-items:center;gap:12px;margin-bottom:12px");
+              const title = document.createElement("strong");
+              title.textContent = "lilac dev: build failed";
+              title.setAttribute("style", "color:#ff5b6c;font-size:15px");
+              const close = document.createElement("button");
+              close.type = "button";
+              close.textContent = "×";
+              close.setAttribute("aria-label", "Dismiss");
+              close.setAttribute("style", "background:transparent;border:0;color:#fff;font-size:22px;cursor:pointer;line-height:1");
+              close.addEventListener("click", () => root.remove());
+              head.appendChild(title);
+              head.appendChild(close);
+              panel.appendChild(head);
+
+              if (payload && payload.type) {
+                const t = document.createElement("div");
+                t.textContent = payload.type;
+                t.setAttribute("style", "color:#9aa0a6;font-size:12px;margin-bottom:8px");
+                panel.appendChild(t);
+              }
+
+              const msg = document.createElement("pre");
+              msg.textContent = (payload && payload.message) || "(no message)";
+              msg.setAttribute("style", "white-space:pre-wrap;word-break:break-word;margin:0;color:#f5f5f5");
+              panel.appendChild(msg);
+
+              const hint = document.createElement("div");
+              hint.textContent = "Save the file to retry — this overlay will close automatically on a successful rebuild.";
+              hint.setAttribute("style", "color:#9aa0a6;font-size:12px;margin-top:14px");
+              panel.appendChild(hint);
+
+              root.appendChild(panel);
+              document.body.appendChild(root);
+            }
+
+            const es = new EventSource(ES_URL);
+            es.addEventListener("message", () => location.reload());
+            es.addEventListener("error", (ev) => {
+              // EventSource fires "error" on transport failure too — those
+              // have no `data` field. Distinguish from server-sent error
+              // events by presence of `ev.data`.
+              if (!ev.data) return;
+              try {
+                renderOverlay(JSON.parse(ev.data));
+              } catch (_e) {
+                renderOverlay({ type: "(parse failure)", message: ev.data });
+              }
+            });
+          })();
+        </script>
+      HTML
+
+      def initialize
+        @subscribers = []
+        @mutex = Mutex.new
+      end
+
+      def call(_request)
+        queue = subscribe
+        Wsv::Response.sse do |io|
+          io.write(":connected\n\n")
+          io.flush
+          serve_loop(queue, io)
+        rescue Errno::EPIPE, IOError
+          # Client disconnected mid-stream; producer just exits.
+        ensure
+          unsubscribe(queue)
+        end
+      end
+
+      def notify_all(message = "reload")
+        @mutex.synchronize { @subscribers.each { |q| q << message } }
+      end
+
+      # Push a `event: error` SSE frame to all subscribers with the
+      # given payload encoded as JSON. The client overlay reads this
+      # via `addEventListener("error", ...)` and renders an overlay.
+      # A subsequent successful build calls `notify_all("reload")`
+      # which reloads the page and the overlay disappears on its own.
+      def notify_error(payload)
+        require "json"
+        json = JSON.generate(payload)
+        marker = [ERROR_MARKER, json]
+        @mutex.synchronize { @subscribers.each { |q| q << marker } }
+      end
+
+      def subscriber_count
+        @mutex.synchronize { @subscribers.length }
+      end
+
+      # Sentinel object used to tag error tuples in the queue without
+      # colliding with any plausible reload-message string.
+      ERROR_MARKER = Object.new.freeze
+
+      private
+
+      def subscribe
+        queue = Queue.new
+        @mutex.synchronize { @subscribers << queue }
+        queue
+      end
+
+      def unsubscribe(queue)
+        @mutex.synchronize { @subscribers.delete(queue) }
+      end
+
+      def serve_loop(queue, io)
+        loop do
+          # Queue#pop(timeout:) is Ruby 3.2+ — required Ruby version
+          # already enforced in the gemspec.
+          msg = queue.pop(timeout: KEEPALIVE_INTERVAL)
+          io.write(format_frame(msg))
+          io.flush
+        end
+      end
+
+      def format_frame(msg)
+        case msg
+        when nil
+          ":keepalive\n\n"
+        when Array  # tagged [ERROR_MARKER, json]
+          "event: error\ndata: #{msg.last}\n\n"
+        else
+          "data: #{msg}\n\n"
+        end
+      end
+    end
+  end
+end

data/lib/lilac/cli/offline_verifier.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+require "pathname"
+require_relative "build/vendor_writer"
+
+module Lilac
+  module CLI
+    # Inspects a *built* dist directory and reports whether it is
+    # self-contained — i.e. it can run with no internet access:
+    #
+    #   1. The target's runtime assets are vendored locally
+    #      (`vendor/lilac-{full,compiled}/...`).
+    #   2. No emitted HTML/JS loads a runtime asset from a remote origin
+    #      (CDN import / `<script src>` / `<link href>` / `fetch()`).
+    #
+    # Outbound *content* links in page copy (`<a href="https://...">`)
+    # are intentionally allowed — the guarantee is about runtime asset
+    # loading, not about whether the page links elsewhere.
+    #
+    # Stateless; returns an Array of `Result` (level :ok / :warn / :error
+    # — the same shape as `Doctor::Result`) so both `doctor` and any
+    # future caller can consume it without duplication.
+    class OfflineVerifier
+      Result = Struct.new(:level, :message, keyword_init: true)
+
+      # A remote URL appearing in an asset-loading position. We only flag
+      # absolute (`https://host`, `http://host`) and protocol-relative
+      # (`//host`) URLs; root-relative (`/vendor/...`) and bare-relative
+      # (`./x.js`) paths are same-origin and fine. Captured inside the
+      # asset-context patterns below so prose links don't false-positive.
+      REMOTE_URL = %r{(?:https?:)?//[^"'\s)]+}
+
+      # Asset-loading contexts whose URL must be local. Each captures the
+      # URL into group 1.
+      ASSET_CONTEXTS = [
+        /\bimport\s+[^"']*["'](#{REMOTE_URL})["']/,             # import ... from "URL" / import "URL"
+        /\bimport\s*\(\s*["'](#{REMOTE_URL})["']/,              # dynamic import("URL")
+        /\bfrom\s+["'](#{REMOTE_URL})["']/,                     # from "URL"
+        /\bfetch\s*\(\s*["'](#{REMOTE_URL})["']/,               # fetch("URL")
+        /<script\b[^>]*\bsrc\s*=\s*["'](#{REMOTE_URL})["']/i,   # <script src="URL">
+        /<link\b[^>]*\bhref\s*=\s*["'](#{REMOTE_URL})["']/i,    # <link href="URL"> (stylesheet/modulepreload)
+        /\bnew\s+URL\s*\(\s*["'](#{REMOTE_URL})["']/,           # new URL("URL", ...)
+      ].freeze
+
+      def initialize(output_dir)
+        @output_dir = output_dir
+      end
+
+      # Returns Array<Result>. Empty of :error/:warn ⇒ self-contained.
+      def verify
+        results = []
+        results.concat(check_assets)
+        results.concat(check_remote_refs)
+        if results.empty?
+          results << ok("dist is self-contained (offline-runnable): runtime assets " \
+                        "vendored locally, no remote asset URLs")
+        end
+        results
+      end
+
+      private
+
+      # Auto-detect which runtime the dist was built with by the presence
+      # of its `vendor/lilac-{full,compiled}/` directory (a build emits
+      # exactly one), then assert that runtime's required files are all
+      # there. A dist with no vendored runtime can't run offline at all.
+      def check_assets
+        warnings = []
+        any_present = false
+        VendorWriter::REQUIRED_ASSETS.each_value do |files|
+          # The target's vendor dir is the wasm's parent — derived from
+          # the SSOT so the dir name isn't independently reconstructed.
+          next unless File.directory?(File.join(@output_dir, File.dirname(files[:wasm])))
+          any_present = true
+          files.each_value do |rel|
+            next if File.file?(File.join(@output_dir, rel))
+            warnings << warn("incomplete vendored runtime: missing #{rel}")
+          end
+        end
+        warnings << warn("no vendored runtime under vendor/ — dist won't run offline (build with a discoverable runtime)") unless any_present
+        warnings
+      end
+
+      def check_remote_refs
+        scan_files.flat_map do |file|
+          remote_urls_in(File.read(file)).map do |url|
+            warn("remote asset URL in #{relative(file)}: #{url} — vendor it locally for offline use")
+          end
+        end
+      end
+
+      def scan_files
+        Dir.glob(File.join(@output_dir, "**", "*.{html,js}"), File::FNM_DOTMATCH)
+           .select { |p| File.file?(p) }
+      end
+
+      # All distinct remote URLs that appear in an asset-loading context.
+      def remote_urls_in(text)
+        ASSET_CONTEXTS.flat_map { |re| text.scan(re).map { |m| m[0] } }.uniq
+      end
+
+      def relative(path)
+        Pathname.new(path).relative_path_from(Pathname.new(@output_dir)).to_s
+      rescue ArgumentError
+        path
+      end
+
+      def ok(msg)
+        Result.new(level: :ok, message: msg)
+      end
+
+      def warn(msg)
+        Result.new(level: :warn, message: msg)
+      end
+    end
+  end
+end

data/lib/lilac/cli/package_build.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+
+require_relative 'build/build_error'
+require_relative 'build/bytecode_builder'
+
+module Lilac
+  module CLI
+    # Compile one or more pure-Ruby package source files (mrblib-style:
+    # Handler class definitions plus
+    # `Lilac::Directives::Scanner.register("ClassName")` calls) into a
+    # single `.mrb` bytecode file that can be loaded into a running
+    # `lilac-compiled` VM via `vm.loadBytecode(bytes)`.
+    #
+    # Wire-level: this is a thin wrapper around `BytecodeBuilder` (which
+    # owns mrbc backend discovery + the wasm-driven mrbc fallback). The
+    # difference from `build` is that package `.mrb` files have a
+    # user-specified output path (no content-hash filename) and are
+    # never wrapped with `Lilac.start` / framework boot — they're
+    # library-style code that registers directives / defines classes at
+    # load time and then yields control back.
+    #
+    # Multiple inputs are concatenated in the order given, separated by
+    # newlines, before compiling. This mirrors how mruby builds gems
+    # from their `mrblib/*.rb` set (alphabetical concat → single irep).
+    class PackageBuild
+      class Error < BuildError; end
+
+      def initialize(inputs:, output:, mrbc_path: nil)
+        raise Error, 'package-build: at least one input file required' if inputs.empty?
+
+        @inputs = inputs
+        @output = output
+        @mrbc_path = mrbc_path
+      end
+
+      attr_reader :inputs, :output
+
+      # Compile + write. Returns the absolute output path.
+      def run
+        source = aggregate_sources
+        builder = BytecodeBuilder.new(mrbc_path: @mrbc_path)
+        bytecode = builder.compile_to_bytes(source, source_label: source_label)
+
+        FileUtils.mkdir_p(File.dirname(@output))
+        File.binwrite(@output, bytecode)
+        File.expand_path(@output)
+      rescue BytecodeBuilder::Error => e
+        raise Error, e.message
+      end
+
+      private
+
+      def aggregate_sources
+        @inputs.map do |path|
+          raise Error, "package-build: input file not found: #{path}" unless File.file?(path)
+
+          File.read(path)
+        end.join("\n")
+      end
+
+      def source_label
+        @inputs.length == 1 ? @inputs.first : "#{@inputs.length} files (#{@inputs.first}, ...)"
+      end
+    end
+  end
+end

data/lib/lilac/cli/package_discovery.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Lilac
+  module CLI
+    # Walks `Bundler.load.specs` to find gems that declare themselves as
+    # Lilac packages via `metadata["lilac_package"] == "true"`.
+    #
+    # Each entry is described by `Discovered` (gem name, version, mrblib
+    # source files). `Builder` feeds the source files into
+    # `PackageBuild#compile_to_bytes` at build time and stages the
+    # produced `.mrb` under `dist/packages/`.
+    #
+    # If Bundler isn't loaded (e.g. `lilac-cli` is being run from a
+    # context without a Gemfile), discovery silently returns an empty
+    # list. Users who want explicit control set
+    # `c.packages = [...paths]` in `lilac.config.rb`, which goes through
+    # a different code path and bypasses discovery.
+    class PackageDiscovery
+      # Metadata key on a gemspec that marks the gem as a Lilac package.
+      # Set via `spec.metadata["lilac_package"] = "true"` in the
+      # `lilac-*.gemspec`.
+      METADATA_KEY = "lilac_package"
+
+      Discovered = Struct.new(:name, :mrblib_files, keyword_init: true)
+
+      def self.run
+        new.run
+      end
+
+      # Returns Array<Discovered>. Empty when Bundler isn't loaded or
+      # when no Lilac packages are declared in the current Gemfile.
+      def run
+        return [] unless bundler_loaded?
+
+        bundler_specs.filter_map do |spec|
+          next unless package_spec?(spec)
+
+          files = mrblib_files_for(spec)
+          next if files.empty?
+
+          Discovered.new(name: spec.name, mrblib_files: files)
+        end
+      end
+
+      private
+
+      # `Bundler.load.specs` (vs `Bundler.definition.specs`) returns the
+      # set of gems active in the current bundle — i.e. what's actually
+      # available to `require`. That's exactly the lens we want: packages
+      # listed in the user's Gemfile but uninstalled (or absent) are
+      # skipped silently rather than raising mid-build.
+      def bundler_specs
+        Bundler.load.specs.to_a
+      rescue Bundler::GemfileNotFound, Bundler::BundlerError
+        # Outside a bundle / Gemfile-less project: no packages to find.
+        # Explicit `c.packages` paths still work — see `Config#packages`.
+        []
+      end
+
+      def bundler_loaded?
+        defined?(Bundler) && Bundler.respond_to?(:load)
+      end
+
+      def package_spec?(spec)
+        spec.metadata && spec.metadata[METADATA_KEY] == "true"
+      end
+
+      # mrblib source lives at `mrblib/**/*.rb` in each package gem's
+      # root. Returns absolute paths in alphabetical order so the
+      # concatenation (`PackageBuild#aggregate_sources`) is deterministic.
+      def mrblib_files_for(spec)
+        base = spec.full_gem_path
+        Dir[File.join(base, "mrblib", "**", "*.rb")].sort
+      end
+    end
+  end
+end

data/lib/lilac/cli/preview_server.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require "wsv"
+
+module Lilac
+  module CLI
+    # Static server for the `lilac build` output. The intent is "ship-
+    # parity preview": serve `dist/` as a CDN / static host would, with
+    # no file watcher, no live reload, no rebuild. Use this to verify
+    # the production-mode (default `--target compiled`) output before
+    # deploy.
+    #
+    # Mirrors `vite preview` semantics: separate command, separate
+    # default port from `lilac dev`, no automation.
+    class PreviewServer
+      class Error < BuildError; end
+
+      DEFAULT_HOST = "127.0.0.1"
+      DEFAULT_PORT = 4173
+
+      def initialize(output_dir, host: DEFAULT_HOST, port: DEFAULT_PORT, out: $stdout, err: $stderr)
+        @output_dir = output_dir
+        @host = host
+        @port = port
+        @out = out
+        @err = err
+      end
+
+      def start
+        verify_dist!
+        @server = build_server
+        @out.puts banner
+        @server.start
+      end
+
+      def stop
+        @server&.stop
+      end
+
+      private
+
+      def verify_dist!
+        unless File.directory?(@output_dir)
+          raise Error,
+                "lilac preview: output directory #{@output_dir.inspect} does not exist. " \
+                "Run `lilac build` first."
+        end
+        return if Dir.glob(File.join(@output_dir, "*.html")).any?
+        raise Error,
+              "lilac preview: no HTML files under #{@output_dir.inspect}. " \
+              "Run `lilac build` first."
+      end
+
+      def build_server
+        Wsv::Server.new(
+          host: @host,
+          port: @port,
+          root: @output_dir,
+          out: @out,
+          err: @err,
+          app: Wsv::App.new(File.realpath(@output_dir)),
+        )
+      end
+
+      def banner
+        "lilac preview: serving #{@output_dir} at http://#{@host}:#{@port}"
+      end
+    end
+  end
+end

data/lib/lilac/cli/scaffold.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "pathname"
+
+module Lilac
+  module CLI
+    # Generates a new Lilac app skeleton under `<root>/<name>/`:
+    #
+    #   <name>/
+    #   ├── .gitignore
+    #   ├── Gemfile
+    #   ├── README.md
+    #   ├── pages/index.html
+    #   └── components/counter.lil
+    #
+    # Templates live under `lib/lilac/cli/templates/`. Files are copied
+    # 1:1 with `{{name}}` substituted to the chosen project name. The
+    # `.gitignore` template is shipped as `gitignore` (no leading dot) so
+    # the gem's own working-directory tools don't treat it as a directive
+    # for the templates folder; it gets the dot prefix at copy time.
+    class Scaffold
+      class Error < StandardError; end
+
+      TEMPLATES_DIR = File.expand_path("templates", __dir__)
+
+      # Project names must look like a valid directory + future gem-ish
+      # identifier: ASCII lowercase letters, digits, hyphens, underscores,
+      # starting with a letter.
+      NAME_PATTERN = /\A[a-z][a-z0-9_-]*\z/
+
+      def initialize(name, root: Dir.pwd)
+        @name = name
+        @root = root
+        validate_name!
+      end
+
+      # Returns the list of relative paths written.
+      def run
+        dest = File.expand_path(@name, @root)
+        raise Error, "Destination already exists: #{dest}" if File.exist?(dest)
+
+        FileUtils.mkdir_p(dest)
+        copy_templates(dest)
+      end
+
+      private
+
+      def validate_name!
+        raise Error, "Project name is required" if @name.nil? || @name.empty?
+        unless @name.match?(NAME_PATTERN)
+          raise Error, "Invalid project name #{@name.inspect}; must match [a-z][a-z0-9_-]*"
+        end
+      end
+
+      def copy_templates(dest_root)
+        # FNM_DOTMATCH so dot-prefixed templates (e.g. `public/.gitkeep`)
+        # are included. `File.file?` already excludes the `.` / `..`
+        # directory entries that FNM_DOTMATCH surfaces.
+        sources = Dir.glob(File.join(TEMPLATES_DIR, "**", "*"), File::FNM_DOTMATCH)
+                     .select { |p| File.file?(p) }
+                     .sort
+
+        sources.map do |source|
+          rel = relative_template_path(source)
+          target = File.join(dest_root, rel)
+          FileUtils.mkdir_p(File.dirname(target))
+          File.write(target, substitute(File.read(source)))
+          rel
+        end
+      end
+
+      def relative_template_path(source)
+        rel = Pathname.new(source).relative_path_from(Pathname.new(TEMPLATES_DIR)).to_s
+        # `gitignore` → `.gitignore` only when it's a top-level entry; a
+        # `components/gitignore` wouldn't be silently renamed.
+        rel == "gitignore" ? ".gitignore" : rel
+      end
+
+      def substitute(content)
+        content.gsub("{{name}}", @name)
+      end
+    end
+  end
+end

data/lib/lilac/cli/source_location.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Lilac
+  module CLI
+    # `(file, line)` pair that appears in every build-time error and
+    # lint warning. Kept as one value so error/warning constructors take
+    # a single `at:` kwarg instead of two, and so future additions
+    # (column, snippet excerpt, end-line for ranges) can be tacked on
+    # here without rippling through every raise site.
+    SourceLocation = Struct.new(:file, :line, keyword_init: true) do
+      def to_s
+        "#{file}:#{line}"
+      end
+    end
+  end
+end

data/lib/lilac/cli/subcommand/base.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require "optparse"
+require "stringio"
+require "pathname"
+require_relative "option_helpers"
+
+module Lilac
+  module CLI
+    module Subcommand
+      # Base for `lilac <subcommand>` handlers. Each subclass:
+      #
+      #   1. defines `opts_parser(opts)` returning an OptionParser whose
+      #      callbacks populate `opts`
+      #   2. defines `run` returning the desired process exit status
+      #
+      # `Command` instantiates the right subclass based on argv[0] and
+      # delegates. Exception handling (turning `Builder::Error` etc. into
+      # "lilac: <msg>" + status 1) stays in Command's outer rescue so the
+      # error surface is uniform across subcommands.
+      class Base
+        def initialize(argv, out: $stdout, err: $stderr)
+          @argv = argv
+          @out = out
+          @err = err
+        end
+
+        def run
+          raise NotImplementedError
+        end
+
+        # `lilac help <name>` dispatcher uses this to render per-subcommand
+        # help. Sink IO so the `-h` callback some `opts_parser` definitions
+        # bake in doesn't fire during help rendering.
+        def self.help_text
+          sink = StringIO.new
+          new([], out: sink, err: sink).send(:opts_parser, {}).to_s
+        end
+
+        private
+
+        # Default `parse!` (rearranges argv so flags can appear after
+        # positionals). Subcommands like `new` that need `order!` (stops
+        # at first non-option) override this.
+        def parse_opts
+          opts = {}
+          opts_parser(opts).parse!(@argv)
+          opts
+        end
+
+        def opts_parser(_opts)
+          raise NotImplementedError
+        end
+
+        # Path display helper used by subcommands that report output paths
+        # in user-facing messages.
+        def relative(path)
+          Pathname.new(path).relative_path_from(Pathname.new(Dir.pwd)).to_s
+        rescue ArgumentError
+          path
+        end
+      end
+    end
+  end
+end