lilac-cli 0.2.0

data/lib/lilac/cli/dev_server.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+require "wsv"
+require_relative "build/builder"
+require_relative "build/build_error"
+require_relative "live_reload"
+require_relative "watcher"
+
+module Lilac
+  module CLI
+    # Long-running dev server: initial build, file watch, live reload.
+    #
+    #   1. Builds `components/*.lil + pages/*.html` → `output_dir/` once,
+    #      with the live-reload client script injected
+    #   2. Wraps `Wsv::Server` with a custom app that routes
+    #      `/__lilac/livereload` to the SSE pub/sub, everything else
+    #      to the default static-file `Wsv::App`
+    #   3. Starts the file watcher; on debounced change events,
+    #      rebuilds and notifies all SSE subscribers, which reload
+    #      their pages
+    class DevServer
+      DEFAULT_HOST = "127.0.0.1"
+      DEFAULT_PORT = 5173
+
+      def initialize(config, host: DEFAULT_HOST, port: DEFAULT_PORT, out: $stdout, err: $stderr)
+        @config = config
+        @host = host
+        @port = port
+        @out = out
+        @err = err
+        @live_reload = LiveReload.new
+      end
+
+      def start
+        rebuild!
+        # Watch public/ too, so changes to vendored assets (vendor/*.js,
+        # favicons, images) also trigger a rebuild + reload.
+        @watcher = Watcher.new(watched_paths) { rebuild_and_notify }
+        @watcher.start
+
+        @server = build_server
+        @out.puts banner
+        @server.start
+      ensure
+        @watcher&.stop
+      end
+
+      def stop
+        @server&.stop
+        @watcher&.stop
+      end
+
+      private
+
+      def rebuild!
+        # `dev_target` (not `build_target`) is intentional — `lilac dev`
+        # follows the dev path: `:full` skips mrbc for fast reloads,
+        # `:compiled` exercises the production mrbc + lilac-compiled
+        # flow under live reload so the dev experience matches what
+        # ships in prod.
+        #
+        # `delivery:` is left unset so `Builder.from_config` reads
+        # `config.delivery` — projects that opt into `c.delivery = :bundle`
+        # in lilac.config.rb get the bundle path under live reload too,
+        # which is the same shape that ships to prod.
+        Builder.from_config(
+          @config,
+          live_reload: true,
+          target: @config.dev_target,
+        ).build
+      end
+
+      def watched_paths
+        [@config.components_dir, @config.pages_dir, @config.public_dir].select { |p| File.directory?(p) }
+      end
+
+      def rebuild_and_notify
+        @out.puts "lilac dev: rebuilding…"
+        rebuild!
+        @live_reload.notify_all
+        @out.puts "lilac dev: reloaded #{@live_reload.subscriber_count} client(s)"
+      rescue Builder::Error, SFC::ParseError, BuildError => e
+        # BuildError covers BytecodeBuilder::Error (mrbc invocation
+        # failures) as well as Lints errors. Keeps the dev
+        # loop alive — the watcher stays armed for the next save. The
+        # client-side overlay (injected with LIVE_RELOAD_SCRIPT) renders
+        # the error in-page so the developer doesn't have to switch to
+        # the terminal to see why the reload didn't happen.
+        @err.puts "lilac dev: build failed: #{e.message}"
+        @live_reload.notify_error(
+          type: e.class.name,
+          message: e.message,
+        )
+      end
+
+      # Bumping `max_connections` (wsv defaults to 8) gives the dev server
+      # enough headroom to handle many SSE subscribers (one per open tab,
+      # plus a brief overlap during navigation) without rejecting page
+      # requests with 503. LiveReload's keepalive reaps dead subscribers
+      # promptly, so this is generous-but-not-leaky.
+      DEV_MAX_CONNECTIONS = 64
+
+      def build_server
+        Wsv::Server.new(
+          host: @host,
+          port: @port,
+          root: @config.output_dir,
+          out: @out,
+          err: @err,
+          app: build_app,
+          max_connections: DEV_MAX_CONNECTIONS,
+        )
+      end
+
+      # The custom app routes the SSE endpoint to LiveReload; every
+      # other URL falls through to the default static-file app rooted
+      # at `output_dir/`.
+      #
+      # `Wsv::App.new` does NOT realpath its root the way `Wsv::Server`
+      # does, so we resolve symlinks here. On macOS, `/tmp` is a symlink
+      # to `/private/tmp`; without this the resolver's within-root check
+      # rejects every request as 403.
+      def build_app
+        RoutingApp.new(
+          default_app: Wsv::App.new(File.realpath(@config.output_dir)),
+          live_reload: @live_reload,
+          endpoint: LiveReload::ENDPOINT_PATH,
+        )
+      end
+
+      def banner
+        "lilac dev: serving #{@config.output_dir} at http://#{@host}:#{@port}"
+      end
+
+      # Wsv app that routes one path to `live_reload`, everything else
+      # to `default_app`. Lives here because it's only useful as the
+      # dev server's request demultiplexer.
+      class RoutingApp
+        def initialize(default_app:, live_reload:, endpoint:)
+          @default_app = default_app
+          @live_reload = live_reload
+          @endpoint = endpoint
+        end
+
+        def call(request)
+          path, = request.target.split("?", 2)
+          if path == @endpoint
+            @live_reload.call(request)
+          else
+            @default_app.call(request)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/lilac/cli/doctor.rb

@@ -0,0 +1,310 @@
+# frozen_string_literal: true
+
+require_relative 'build/builder'
+require_relative 'build/bytecode_builder'
+require_relative 'build/compiled_runtime_resolver'
+require_relative 'build/full_runtime_resolver'
+require_relative 'build/page_compiler'
+require_relative 'build/sfc'
+require_relative 'offline_verifier'
+
+module Lilac
+  module CLI
+    # Inspect a Lilac project for the common ways a fresh `lilac new`
+    # fails before the user sees the page boot. Catches missing wasm
+    # runtime, dangling `<lilac-component>` references, unparseable
+    # `.lil`, and similar setup problems.
+    #
+    # `run` returns 0 when every check passes (or only warns); 1 when
+    # any check produced an :error result. Output is plain-text and
+    # mirrors the layout of `rails about` / `bundle doctor` /
+    # `npx ... doctor` — one line per check, prefix marks the level.
+    class Doctor
+      Result = Struct.new(:level, :message, keyword_init: true)
+
+      # Where the wasm runtime is expected to live, relative to public_dir.
+      # Both live under `vendor/lilac-full/` so the target-aware public
+      # mirror can prune them when building `--target compiled`. Sourced
+      # from the single `VendorWriter::REQUIRED_ASSETS` definition.
+      RUNTIME_WASM       = VendorWriter::REQUIRED_ASSETS[:full][:wasm]
+      RUNTIME_JS_ADAPTER = VendorWriter::REQUIRED_ASSETS[:full][:bridge]
+
+      def initialize(config, out: $stdout)
+        @config = config
+        @out = out
+      end
+
+      # Returns exit status (0 if no errors).
+      def run
+        results = run_checks
+        emit(results)
+        results.any? { |r| r.level == :error } ? 1 : 0
+      end
+
+      private
+
+      # Each check returns a single Result. Order is roughly "structure
+      # → content → external assets" so the report reads top-down from
+      # project layout outward.
+      def run_checks
+        [
+          check_pages_dir,
+          check_components_dir,
+          *check_components_parse,
+          *check_component_references,
+          check_unused_components,
+          check_public_dir,
+          check_runtime_wasm,
+          check_js_adapter,
+          check_compiled_runtime,
+          check_full_runtime,
+          check_mrbc_backend,
+          *check_offline_dist
+        ]
+      end
+
+      def check_pages_dir
+        if File.directory?(@config.pages_dir)
+          ok("pages/ directory found at #{relative(@config.pages_dir)}")
+        else
+          error("pages/ directory missing: #{relative(@config.pages_dir)}")
+        end
+      end
+
+      def check_components_dir
+        if File.directory?(@config.components_dir)
+          ok("components/ directory found at #{relative(@config.components_dir)}")
+        else
+          warn("components/ directory missing: #{relative(@config.components_dir)} (OK if you have no components yet)")
+        end
+      end
+
+      # Each .lil file gets its own Result so a parse failure pinpoints
+      # the offending file (rather than aborting the whole report).
+      def check_components_parse
+        gnt_paths.map do |path|
+          SFC.parse_file(path)
+          ok("component parses: #{relative(path)}")
+        rescue SFC::ParseError => e
+          error("component parse error: #{relative(path)}: #{e.message}")
+        end
+      end
+
+      def check_component_references
+        return [] unless File.directory?(@config.pages_dir)
+
+        component_names = gnt_paths.map { |p| File.basename(p, '.lil') }.to_set
+        results = []
+        page_paths.each do |page_path|
+          html = File.read(page_path)
+          html.scan(PageCompiler::DATA_USE_PATTERN) do |dq, sq|
+            name = dq || sq
+            unless component_names.include?(name)
+              results << error(
+                "page #{relative(page_path)} references data-use=#{name.inspect}, " \
+                "but no components/#{name}.lil exists"
+              )
+            end
+          end
+        end
+        results.empty? ? [ok('all data-use= references resolve')] : results
+      end
+
+      def check_unused_components
+        return ok('no components to check for usage') if gnt_paths.empty?
+
+        component_names = gnt_paths.map { |p| File.basename(p, '.lil') }.to_set
+        referenced = page_paths.flat_map do |page_path|
+          File.read(page_path).scan(PageCompiler::DATA_USE_PATTERN).map { |dq, sq| dq || sq }
+        end.uniq.to_set
+
+        unused = component_names - referenced
+        if unused.empty?
+          ok('all components are referenced from at least one page')
+        else
+          warn("unused components: #{unused.to_a.sort.join(', ')}")
+        end
+      end
+
+      def check_public_dir
+        if File.directory?(@config.public_dir)
+          ok("public/ directory found at #{relative(@config.public_dir)}")
+        else
+          warn("public/ directory missing: #{relative(@config.public_dir)} (required for the wasm runtime)")
+        end
+      end
+
+      def check_runtime_wasm
+        path = File.join(@config.public_dir, RUNTIME_WASM)
+        if File.file?(path)
+          ok("mruby-wasm runtime present: #{relative(path)} (#{format_size(File.size(path))})")
+        else
+          error("mruby-wasm runtime missing: expected at #{relative(path)}")
+        end
+      end
+
+      def check_js_adapter
+        path = File.join(@config.public_dir, RUNTIME_JS_ADAPTER)
+        if File.file?(path)
+          ok("JS adapter present: #{relative(path)}")
+        else
+          error("JS adapter missing: expected at #{relative(path)}")
+        end
+      end
+
+      # `lilac build` defaults to `--target compiled`, which requires
+      # a discoverable `lilac-compiled.wasm` (monorepo build/ dir, npm
+      # package, or explicit config). This check reports whether one is
+      # available, but doesn't fail the run — `lilac dev` and
+      # `lilac build --target full` work without it, so a project that
+      # only uses the full target shouldn't be forced to set up
+      # compiled deps.
+      def check_compiled_runtime
+        resolver = CompiledRuntimeResolver.new(
+          lilac_compiled_path: @config.lilac_compiled_path,
+          mruby_wasm_js_path: @config.mruby_wasm_js_path
+        )
+        path = resolver.wasm_path
+        if path && File.file?(path)
+          ok("compiled wasm discoverable: #{relative(path)} (#{format_size(File.size(path))})")
+        else
+          warn(
+            'lilac-compiled.wasm not discoverable — `lilac build` (default ' \
+            'target=compiled) will fail. Either run `make lilac-compiled` ' \
+            'in the lilac monorepo, add `gem "lilac-wasm-bin"` to your Gemfile ' \
+            'and `bundle install`, or use `lilac build --target full` to skip it.'
+          )
+        end
+      end
+
+      # `lilac build --target full` vendors `lilac-full.wasm` + bridge
+      # into the dist; this reports whether a runtime is discoverable so
+      # a `:full` build won't fail. Warn-only (a `:compiled`-only project
+      # needn't set up the full runtime), mirroring `check_compiled_runtime`.
+      def check_full_runtime
+        resolver = FullRuntimeResolver.new(
+          lilac_full_path: @config.lilac_full_path,
+          mruby_wasm_js_path: @config.mruby_wasm_js_path
+        )
+        path = resolver.wasm_path
+        if path && File.file?(path)
+          ok("full wasm discoverable: #{relative(path)} (#{format_size(File.size(path))})")
+        else
+          warn(
+            'lilac-full.wasm not discoverable — `lilac build --target full` ' \
+            'will fail. Either run `make lilac-full` in the lilac monorepo, ' \
+            'add `gem "lilac-wasm-bin"` to your Gemfile and `bundle install`, ' \
+            'or set `c.lilac_full_path`.'
+          )
+        end
+      end
+
+      # If a build output already exists, verify it can run offline: all
+      # of the target's runtime assets are vendored locally and no
+      # emitted HTML/JS pulls a runtime asset from a remote origin (CDN).
+      # Skipped (informational) when `dist/` is absent — `doctor` is
+      # usually run before the first build. Warn-only, like the other
+      # external-asset checks.
+      # Always returns Array<Result> (splatted into the check list) so a
+      # dist with several issues reports one line per issue.
+      def check_offline_dist
+        dist = @config.output_dir
+        return [ok("offline check skipped — no build output at #{relative(dist)} (run `lilac build` first)")] unless File.directory?(dist)
+
+        results = OfflineVerifier.new(dist).verify
+        problems = results.reject { |r| r.level == :ok }
+        if problems.empty?
+          [ok("dist is offline-runnable: #{relative(dist)} (runtime vendored locally, no remote asset URLs)")]
+        else
+          problems.map { |r| Result.new(level: r.level, message: "offline: #{r.message}") }
+        end
+      end
+
+      # Reports which mrbc backend `lilac build --target compiled` will
+      # pick (binary vs wasm-driven) so users can see at a glance why
+      # their setup works (or doesn't). Same priority chain as
+      # `BytecodeBuilder#resolve_backend`.
+      def check_mrbc_backend
+        builder = BytecodeBuilder.new(
+          mrbc_path: @config.mrbc_path,
+          output_dir: Dir.tmpdir # never used by resolve_backend
+        )
+        backend = builder.resolve_backend
+        case backend&.first
+        when :binary
+          ok("mrbc backend: binary (#{backend.last})")
+        when :wasm
+          ok("mrbc backend: wasm via lilac-wasm-bin gem (#{relative(backend.last)})")
+        else
+          warn(
+            'no mrbc backend discoverable — `lilac build --target compiled` ' \
+            'will fail. Add `gem "lilac-wasm-bin"` + `gem "wasmtime"` to ' \
+            'your Gemfile, or install mrbc on PATH.'
+          )
+        end
+      end
+
+      def gnt_paths
+        return [] unless File.directory?(@config.components_dir)
+
+        @gnt_paths ||= Dir.glob(File.join(@config.components_dir, '**', '*.lil'))
+      end
+
+      def page_paths
+        return [] unless File.directory?(@config.pages_dir)
+
+        @page_paths ||= Dir.glob(File.join(@config.pages_dir, '**', '*.html'))
+      end
+
+      def relative(path)
+        rel = Pathname.new(path).relative_path_from(Pathname.new(@config.root)).to_s
+        # Paths outside the project root produce ugly `../../../../...`
+        # forms — fall back to the absolute path which is easier to
+        # read (and grep) than a long traversal sequence.
+        rel.start_with?('../..') ? path : rel
+      rescue ArgumentError
+        path
+      end
+
+      def format_size(bytes)
+        return "#{bytes} B" if bytes < 1024
+        return "#{(bytes / 1024.0).round(1)} KB" if bytes < 1024 * 1024
+
+        "#{(bytes / (1024.0 * 1024.0)).round(1)} MB"
+      end
+
+      def ok(msg)
+        Result.new(level: :ok, message: msg)
+      end
+
+      def warn(msg)
+        Result.new(level: :warn, message: msg)
+      end
+
+      def error(msg)
+        Result.new(level: :error, message: msg)
+      end
+
+      def emit(results)
+        results.each { |r| @out.puts "  #{prefix(r.level)} #{r.message}" }
+        @out.puts
+        @out.puts summary(results)
+      end
+
+      def prefix(level)
+        case level
+        when :ok then '[OK]   '
+        when :warn then '[WARN] '
+        when :error then '[FAIL] '
+        end
+      end
+
+      def summary(results)
+        ok_count = results.count { |r| r.level == :ok }
+        warn_count = results.count { |r| r.level == :warn }
+        error_count = results.count { |r| r.level == :error }
+        "#{ok_count} ok, #{warn_count} warning(s), #{error_count} error(s)"
+      end
+    end
+  end
+end

data/lib/lilac/cli/lint/build_linter.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require "digest"
+require_relative "script_analyzer"
+require_relative "../build/component_name"
+
+module Lilac
+  module CLI
+    # Build-time linter for component-name / cross-page consistency.
+    # Extracted from `Builder` so the build pipeline itself stays focused
+    # on HTML rewriting + bytecode emission. Owns the per-build state
+    # (page-inline component signatures) that drives cross-page drift
+    # detection.
+    class BuildLinter
+      def initialize
+        # `{ component_name => [ [content_hash, page_path], ... ] }`
+        # for every page-inline `data-component` element across pages.
+        # Populated via `record_inline_signature` from the builder.
+        @page_inline_signatures = Hash.new { |h, k| h[k] = [] }
+      end
+
+      # R4: page-inline script classes that collide with `.lil`-derived
+      # class names (project-global) are flagged here so the user sees a
+      # structured error instead of a downstream mrbc failure. Raises
+      # `Lilac::CLI::Builder::Error` to match the error surface other
+      # build-time scope violations use.
+      def check_class_name_collisions!(page_inline_scripts, components, synthesized_names, page_path)
+        return if page_inline_scripts.empty?
+
+        # `.lil` class names (skip synthesized in-memory entries — those
+        # are the page-inline data-component snapshots, not real .lil files).
+        lil_class_names = {} # ruby_class_name => kebab (original file)
+        components.each_key do |name|
+          next if synthesized_names.include?(name)
+
+          ruby_name = ComponentName.new(name).ruby_class
+          lil_class_names[ruby_name] = name
+        end
+        return if lil_class_names.empty?
+
+        page_inline_scripts.each do |script|
+          ScriptAnalyzer.extract_top_level_class_names(script).each do |declared|
+            next unless lil_class_names.key?(declared)
+
+            page_rel = page_path ? File.basename(page_path) : '(page)'
+            lil_basename = "#{lil_class_names[declared]}.lil"
+            raise Lilac::CLI::Builder::Error,
+                  "page-inline class #{declared} in #{page_rel} collides with the class " \
+                  "derived from components/#{lil_basename}. " \
+                  "Rename either the page-inline class or the .lil file."
+          end
+        end
+      end
+
+      # Records a page-inline component's body signature so
+      # `warn_cross_page_signature_drift!` can later detect divergent
+      # shapes of the same name across pages.
+      def record_inline_signature(name, body_html, page_path)
+        @page_inline_signatures[name] << [signature_for(body_html), page_path]
+      end
+
+      # R3: after every page is built, scan recorded signatures for the
+      # same name appearing with different content_hashes across pages.
+      # Output a single warning grouping divergent pages so the user can
+      # decide whether to rename one of them or align the shapes.
+      def warn_cross_page_signature_drift!
+        @page_inline_signatures.each do |name, entries|
+          unique_sigs = entries.map { |sig, _| sig }.uniq
+          next if unique_sigs.size <= 1
+
+          pages_str = entries.uniq { |sig, _| sig }
+                             .map { |_sig, page| File.basename(page) }
+                             .join(', ')
+          warn(
+            "[lilac] page-inline component #{name.inspect} appears with " \
+            "different shapes across pages (#{pages_str}). " \
+            "Page-inline names are page-local so this is allowed, but " \
+            "is likely unintentional drift — consider renaming or moving " \
+            "the component to components/#{name}.lil to share one shape."
+          )
+        end
+      end
+
+      private
+
+      # Stable hash of a page-inline component element body (outer HTML)
+      # for cross-page drift detection (proposal §A.R3). Whitespace
+      # normalised so cosmetic indentation differences across pages don't
+      # spuriously fire the warning.
+      def signature_for(body_html)
+        Digest::SHA1.hexdigest(body_html.gsub(/\s+/, ' ').strip)
+      end
+    end
+  end
+end