seams 0.1.0

data/lib/seams/generators/host_injector.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Seams
+  module Generators
+    # Idempotent host-file edits used by every canonical generator.
+    # Mix into a Rails::Generators::Base subclass; the methods below
+    # delegate to Thor's inject_into_file / append_to_file primitives
+    # but skip the edit if the host already contains the snippet.
+    #
+    # Every method is safe to call when the target file is missing —
+    # it prints a yellow `skip` line so the user knows to do the edit
+    # themselves later.
+    module HostInjector
+      def host_inject_gem(name, *args, group: nil)
+        gemfile = host_path("Gemfile")
+        return host_skip("Gemfile not found — add `gem #{name.inspect}` yourself") unless File.exist?(gemfile)
+
+        return if File.read(gemfile).match?(/^\s*gem\s+["']#{Regexp.escape(name)}["']/)
+
+        line = build_gem_line(name, args, group)
+        say "  inject  Gemfile (gem \"#{name}\")", :green
+        append_to_file(gemfile, "\n#{line}\n")
+      end
+
+      def host_inject_mount(engine_class:, at:)
+        routes = host_path("config/routes.rb")
+        unless File.exist?(routes)
+          return host_skip("config/routes.rb not found — add `mount #{engine_class}, at: \"#{at}\"` yourself")
+        end
+
+        # Word-boundary match on the engine class name so a sibling
+        # `mount Auth::EngineExtras` doesn't trick us into thinking
+        # `Auth::Engine` is already mounted. The boundary is "anything
+        # that isn't a constant-name character" (`[\w:]` excluded).
+        return if File.read(routes).match?(/\bmount\s+#{Regexp.escape(engine_class)}(?![\w:])/)
+
+        say "  inject  config/routes.rb (mount #{engine_class})", :green
+        inject_into_file(routes, after: routes_draw_anchor) do
+          "  mount #{engine_class}, at: \"#{at}\"\n"
+        end
+      end
+
+      # Matches the common `Rails.application.routes.draw do` forms:
+      # plain `do`, `do |routes|` block-arg, `do  # comment`, and the
+      # rare `Rails::Application.routes.draw`.
+      def routes_draw_anchor
+        /Rails(?:\.application|::Application)\.routes\.draw\s+do(?:\s*\|[^|]+\|)?[^\n]*\n/
+      end
+
+      def host_inject_include_in_user(concern_name)
+        host_inject_include("app/models/user.rb", "User", concern_name, label: "User model")
+      end
+
+      def host_inject_include_in_application_controller(concern_name)
+        host_inject_include(
+          "app/controllers/application_controller.rb", "ApplicationController",
+          concern_name, label: "ApplicationController"
+        )
+      end
+
+      # Reverse of host_inject_gem — used by the remove generator.
+      # Removes the `gem "<name>"` line if present.
+      def host_uninject_gem(name)
+        gemfile = host_path("Gemfile")
+        return unless File.exist?(gemfile)
+
+        new_content = File.read(gemfile).gsub(/^\s*gem\s+["']#{Regexp.escape(name)}["'][^\n]*\n/, "")
+        File.write(gemfile, new_content)
+        say "  remove  Gemfile (gem \"#{name}\")", :red
+      end
+
+      def host_uninject_mount(engine_class:)
+        routes = host_path("config/routes.rb")
+        return unless File.exist?(routes)
+
+        # Word-boundary match — see host_inject_mount. Without it, an
+        # unrelated `mount Auth::EngineExtras` would match a remove of
+        # `mount Auth::Engine` and silently delete the wrong line.
+        pattern     = /^\s*mount\s+#{Regexp.escape(engine_class)}(?![\w:])[^\n]*\n/
+        new_content = File.read(routes).gsub(pattern, "")
+        File.write(routes, new_content)
+        say "  remove  config/routes.rb (mount #{engine_class})", :red
+      end
+
+      def host_uninject_include(file_relative, concern_name)
+        full = host_path(file_relative)
+        return unless File.exist?(full)
+
+        new_content = File.read(full).gsub(/^\s*include\s+#{Regexp.escape(concern_name)}\s*\n/, "")
+        File.write(full, new_content)
+        say "  remove  #{file_relative} (include #{concern_name})", :red
+      end
+
+      private
+
+      def host_path(relative)
+        File.join(destination_root, relative)
+      end
+
+      def host_skip(message)
+        say "  skip    #{message}", :yellow
+      end
+
+      def host_inject_include(file_relative, class_name, concern_name, label:)
+        full = host_path(file_relative)
+        return host_skip("#{label} not found — add `include #{concern_name}` yourself") unless File.exist?(full)
+
+        return if File.read(full).match?(/^\s*include\s+#{Regexp.escape(concern_name)}\s*$/)
+
+        say "  inject  #{file_relative} (include #{concern_name})", :green
+        inject_into_class(full, class_name, "  include #{concern_name}\n")
+      end
+
+      def build_gem_line(name, args, group)
+        version_part = args.first.is_a?(String) ? %(, "#{args.first}") : ""
+        gem_line     = %(gem "#{name}"#{version_part})
+        gem_line     = "group #{group.inspect} do\n  #{gem_line}\nend" if group
+        gem_line
+      end
+    end
+  end
+end

data/lib/seams/generators/sibling_rubocop_writer.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Seams
+  module Generators
+    # Rewrites the OtherEngines lists inside every engine's .rubocop.yml
+    # so each engine is configured with every OTHER engine as a
+    # boundary. Used by both the seams:engine and seams:remove
+    # generators — generation adds the new engine, removal prunes the
+    # gone one.
+    #
+    # The replacement is scoped tightly to the OtherEngines key so we
+    # never clobber the surrounding ExposedConcerns / Enabled / OwnEngine
+    # values. The previous version of this code used a too-greedy
+    # lookahead that ate the next sibling key.
+    module SiblingRubocopWriter
+      module_function
+
+      MODULE_ACCESS_KEY = "Seams/NoCrossEngineModelAccess"
+      DEPENDENCY_KEY    = "Seams/NoCrossEngineDependency"
+
+      # @param engines_root [String] absolute or relative path to engines/
+      # @param dirs         [Array<String>] directory names of the engines
+      #                     that currently exist on disk
+      def rewrite!(engines_root:, dirs:)
+        dirs.each do |engine_dir|
+          others        = (dirs - [engine_dir]).sort
+          others_module = others.map { |d| camelcase(d) }
+          rubocop_path  = File.join(engines_root, engine_dir, ".rubocop.yml")
+          next unless File.exist?(rubocop_path)
+
+          content = File.read(rubocop_path)
+          content = replace_other_engines(content, MODULE_ACCESS_KEY, others_module)
+          content = replace_other_engines(content, DEPENDENCY_KEY,    others)
+          File.write(rubocop_path, content)
+        end
+      end
+
+      def camelcase(name)
+        name.split("_").map(&:capitalize).join
+      end
+
+      # Matches `<cop_key>:` and the very next `OtherEngines:` line under
+      # it, replacing only the value of OtherEngines. We don't try to
+      # span multiple following keys — the regex stops as soon as it has
+      # consumed either the inline `[]` form or the indented list form.
+      def replace_other_engines(content, cop_key, values)
+        regex     = other_engines_regex(cop_key)
+        formatted = formatted_block(values)
+
+        unless regex.match?(content)
+          raise ArgumentError,
+                "SiblingRubocopWriter could not find a writable `OtherEngines:` " \
+                "value under `#{cop_key}`. Hand-edited or flow-style YAML " \
+                "(`{ OtherEngines: [Foo] }`) is not supported — restore the " \
+                "block-style template and retry."
+        end
+
+        content.sub(regex, "\\1#{formatted}\n")
+      end
+
+      def formatted_block(values)
+        return "  OtherEngines: []" if values.empty?
+
+        "  OtherEngines:\n#{values.map { |v| "    - #{v}" }.join("\n")}"
+      end
+
+      def other_engines_regex(cop_key)
+        prefix     = "#{Regexp.escape(cop_key)}:[^\\n]*\\n(?:[ \\t]+[^\\n]+\\n)*?"
+        empty_form = "[ \\t]*\\[\\][ \\t]*\\n"
+        list_form  = "[ \\t]*\\n(?:    -[ \\t]+[^\\n]+\\n)*"
+        Regexp.new("(#{prefix})  OtherEngines:(?:#{empty_form}|#{list_form})")
+      end
+    end
+  end
+end

data/lib/seams/generators/splicer.rb

@@ -0,0 +1,217 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Seams
+  module Generators
+    # Idempotent splice operations against files containing
+    # `# seams:insertion-point <name>` markers. Wave 10 introduces
+    # follow-up generators (e.g. `seams:auth:add_oauth_provider`) that
+    # need to extend already-generated engines without re-templating
+    # the whole file. The Splicer is the shared primitive: every
+    # follow-up generator funnels through these methods.
+    #
+    # See doc/INSERTION_POINTS.md for the marker format spec and
+    # doc/INSERTION_POINTS_CATALOGUE.md for the canonical list of
+    # markers each engine ships.
+    #
+    # Example:
+    #
+    #   Seams::Generators::Splicer.splice_after_marker(
+    #     file_path: "engines/auth/lib/auth/engine.rb",
+    #     marker:    "auth.engine.events",
+    #     content:   "  Seams::EventRegistry.register(\"identity.passkey_added.auth\", emitted_by: \"Auth\")\n"
+    #   )
+    #
+    # The Splicer owns four design choices worth surfacing:
+    #
+    # 1. Markers are looked up by NAME, never by line number. A
+    #    follow-up generator written today must keep working after
+    #    the host adds twenty unrelated lines above the marker.
+    # 2. Idempotency is checked by string-matching the splice content
+    #    inside a 50-line window after the marker. Re-running the
+    #    same splice is a no-op rather than an error.
+    # 3. Indentation is auto-detected from the marker line itself.
+    #    Follow-up generators don't have to know whether the marker
+    #    sits at column 0, column 4, or column 6.
+    # 4. The Splicer is pure file I/O — no Rails dep, no Thor — so
+    #    it can be tested in isolation and reused outside the
+    #    generator stack (e.g. by `bin/seams resolve --eject`).
+    module Splicer
+      module_function
+
+      # Pattern matched by every Splicer method. The character class
+      # for the marker name allows lowercase letters, digits, dot, and
+      # underscore — see INSERTION_POINTS.md naming rules.
+      MARKER_PREFIX = "# seams:insertion-point"
+      MARKER_NAME_RE = /[a-z0-9_.]+/
+      MARKER_LINE_RE = /^(\s*)#{Regexp.escape(MARKER_PREFIX)}\s+(#{MARKER_NAME_RE})\s*$/
+      IDEMPOTENCY_WINDOW = 50
+
+      # Result struct returned by every splice operation.
+      # `ok?` is the only required predicate; `error` is populated
+      # only when ok? is false; `lines_added` is 0 when ok? is true
+      # but the splice was a no-op (idempotency hit).
+      Result = Struct.new(:ok?, :lines_added, :error, keyword_init: true) do
+        def to_s
+          ok? ? "Splicer::Result(ok, +#{lines_added})" : "Splicer::Result(error: #{error})"
+        end
+      end
+
+      # Splice `content` immediately after the line containing
+      # `# seams:insertion-point <marker>`.
+      #
+      # @param file_path [String] absolute or working-dir-relative path
+      # @param marker    [String] the marker name, e.g. "auth.engine.events"
+      # @param content   [String] the snippet to insert. Must end in a newline.
+      # @param indent    [String, nil] override auto-detected indentation. Pass
+      #                   `""` to insert verbatim, or a string of spaces to
+      #                   prepend to every line of `content`.
+      # @return [Result]
+      def splice_after_marker(file_path:, marker:, content:, indent: nil)
+        splice(file_path: file_path, marker: marker, content: content, indent: indent, position: :after)
+      end
+
+      # Splice `content` immediately before the line containing the
+      # marker. Same semantics as +splice_after_marker+ otherwise.
+      #
+      # @return [Result]
+      def splice_before_marker(file_path:, marker:, content:, indent: nil)
+        splice(file_path: file_path, marker: marker, content: content, indent: indent, position: :before)
+      end
+
+      # Locate a marker without modifying the file. Useful for follow-up
+      # generators that want to verify multiple markers exist before
+      # they start writing.
+      #
+      # @return [Hash, nil] { line_number: 1-indexed, indent: "  ", marker: "auth.engine.events" }
+      #                     or nil if the marker isn't present.
+      def find_marker(file_path:, marker:)
+        return nil unless File.exist?(file_path)
+
+        lines = File.read(file_path).lines
+        lines.each_with_index do |line, index|
+          match = line.match(MARKER_LINE_RE)
+          next unless match
+          next unless match[2] == marker
+
+          return { line_number: index + 1, indent: match[1], marker: marker }
+        end
+        nil
+      end
+
+      # Enumerate every `seams:insertion-point` marker in a file in
+      # source order. Used by the eject CLI's `--list-markers` flag
+      # and by `bin/seams resolve` for human-readable diagnostics.
+      #
+      # @return [Array<Hash>] each entry shaped like +find_marker+ returns.
+      def list_markers(file_path:)
+        return [] unless File.exist?(file_path)
+
+        result = []
+        File.read(file_path).lines.each_with_index do |line, index|
+          match = line.match(MARKER_LINE_RE)
+          next unless match
+
+          result << { line_number: index + 1, indent: match[1], marker: match[2] }
+        end
+        result
+      end
+
+      # Internal: shared body for splice_{after,before}_marker.
+      def splice(file_path:, marker:, content:, indent:, position:)
+        return file_not_found_result(file_path) unless File.exist?(file_path)
+
+        lines = File.read(file_path).lines
+        marker_index = locate_marker_index(lines, marker)
+        return marker_not_found_result(marker, file_path) unless marker_index
+
+        prepared = apply_indent(content, indent || detect_indent(lines[marker_index]))
+        write_splice(file_path, lines, prepared, marker_index, position)
+      end
+
+      def write_splice(file_path, lines, prepared, marker_index, position)
+        return Result.new(ok?: true, lines_added: 0, error: nil) if already_present?(lines, prepared, marker_index,
+                                                                                     position)
+
+        File.write(file_path, insert_at(lines, prepared, marker_index, position).join)
+        Result.new(ok?: true, lines_added: prepared.lines.size, error: nil)
+      end
+
+      def file_not_found_result(file_path)
+        Result.new(ok?: false, lines_added: 0, error: "file not found: #{file_path}")
+      end
+
+      def marker_not_found_result(marker, file_path)
+        Result.new(ok?: false, lines_added: 0,
+                   error: "marker '#{marker}' not found in #{file_path}")
+      end
+
+      # The marker line plus every line in the idempotency window
+      # following (or preceding for :before) is inspected. The check
+      # looks for the FULL prepared content as a contiguous block,
+      # not for individual lines — a partial overlap is treated as
+      # "not yet spliced" and re-splices, which is the safer default
+      # for a tool that prefers re-runs to silent partials.
+      #
+      # The window grows to accommodate snippets larger than
+      # IDEMPOTENCY_WINDOW lines: a 60-line follow-up splice would
+      # never round-trip with a fixed 50-line window because the
+      # haystack would be smaller than the needle. The effective
+      # window is `max(IDEMPOTENCY_WINDOW, prepared.lines.size)`,
+      # which guarantees idempotency regardless of snippet size while
+      # keeping the small-splice fast path identical.
+      def already_present?(lines, prepared, marker_index, position)
+        haystack = haystack_for(lines, marker_index, position, prepared)
+        haystack.include?(prepared)
+      end
+
+      def haystack_for(lines, marker_index, position, prepared)
+        window = [IDEMPOTENCY_WINDOW, prepared.lines.size].max
+        if position == :after
+          slice_end = [marker_index + window, lines.size - 1].min
+          lines[(marker_index + 1)..slice_end].to_a.join
+        else
+          slice_start = [marker_index - window, 0].max
+          lines[slice_start...marker_index].to_a.join
+        end
+      end
+
+      def insert_at(lines, prepared, marker_index, position)
+        prepared_lines = prepared.lines
+        if position == :after
+          lines[0..marker_index] + prepared_lines + (lines[(marker_index + 1)..] || [])
+        else
+          lines[0...marker_index] + prepared_lines + lines[marker_index..]
+        end
+      end
+
+      def locate_marker_index(lines, marker)
+        lines.each_with_index do |line, index|
+          match = line.match(MARKER_LINE_RE)
+          return index if match && match[2] == marker
+        end
+        nil
+      end
+
+      def detect_indent(marker_line)
+        marker_line[/^\s*/].to_s
+      end
+
+      # Apply `indent` to every non-blank line of `content`. Blank
+      # lines stay blank — re-indenting them would leave trailing
+      # whitespace that some linters (and our own RuboCop config) flag.
+      def apply_indent(content, indent)
+        return content if indent.empty?
+
+        content.lines.map do |line|
+          if line.strip.empty?
+            line
+          else
+            "#{indent}#{line}"
+          end
+        end.join
+      end
+    end
+  end
+end

data/lib/seams/observability/adapter.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require "seams/observability"
+
+module Seams
+  module Observability
+    # Abstract base class for observability adapters. Concrete adapters
+    # bridge to the host application's logger / APM (Rails.logger,
+    # Datadog, OpenTelemetry, etc.) — engines never speak to those
+    # libraries directly.
+    class Adapter
+      def debug(_message, **_context)
+        raise NotImplementedError, "#{self.class} must implement #debug"
+      end
+
+      def info(_message, **_context)
+        raise NotImplementedError, "#{self.class} must implement #info"
+      end
+
+      def warn(_message, **_context)
+        raise NotImplementedError, "#{self.class} must implement #warn"
+      end
+
+      def error(_message, **_context)
+        raise NotImplementedError, "#{self.class} must implement #error"
+      end
+
+      def measure(_operation, **_context, &)
+        raise NotImplementedError, "#{self.class} must implement #measure"
+      end
+    end
+  end
+end

data/lib/seams/observability/adapters/rails_logger.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require "logger"
+require "seams/observability/adapter"
+
+module Seams
+  module Observability
+    module Adapters
+      # Default observability adapter — wraps Rails.logger (or a stdout
+      # Logger when Rails isn't booted) and emits messages tagged with
+      # the seams namespace plus structured key=value context.
+      class RailsLogger < Seams::Observability::Adapter
+        def initialize(logger: nil)
+          super()
+          @logger = logger || default_logger
+        end
+
+        %i[debug info warn error].each do |level|
+          define_method(level) do |message, **context|
+            @logger.public_send(level, format_message(message, context))
+          end
+        end
+
+        def measure(operation, **context)
+          start  = monotonic_ms
+          result = yield
+          duration = (monotonic_ms - start).round(2)
+          info(operation, **context, duration_ms: duration)
+          result
+        rescue StandardError => e
+          duration = (monotonic_ms - start).round(2)
+          error(operation, **context, duration_ms: duration, error: "#{e.class}: #{e.message}")
+          raise
+        end
+
+        private
+
+        def format_message(message, context)
+          tags = ["[seams]"]
+          tags << "[#{context.delete(:engine)}]" if context[:engine]
+          parts = context.map { |k, v| "#{k}=#{v}" }
+          ([tags.join(" "), message] + parts).join(" ").strip
+        end
+
+        def monotonic_ms
+          Process.clock_gettime(Process::CLOCK_MONOTONIC) * 1_000.0
+        end
+
+        def default_logger
+          if defined?(::Rails) && ::Rails.respond_to?(:logger) && ::Rails.logger
+            ::Rails.logger
+          else
+            ::Logger.new($stdout)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/seams/observability.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Seams
+  # Observability module — structured logging and timing primitives that
+  # every engine should use instead of calling Rails.logger directly.
+  #
+  # Engines call Seams::Observability.adapter.info / .warn / .error /
+  # .measure with structured context (engine name, actor id, etc.) so that
+  # logs can be parsed and filtered uniformly by the host application's
+  # log aggregator.
+  module Observability
+    class Error < Seams::Error; end
+
+    class << self
+      def adapter
+        @adapter ||= build_adapter
+      end
+
+      def reset!
+        @adapter = nil
+      end
+
+      private
+
+      def build_adapter
+        klass_name = Seams.configuration.observability_adapter
+        Object.const_get(klass_name).new
+      rescue NameError => e
+        raise Seams::ConfigurationError,
+              "Observability adapter #{klass_name.inspect} could not be loaded: #{e.message}"
+      end
+    end
+  end
+end

data/lib/seams/runtime.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Seams
+  # Module-level methods for the public Seams API. Lives in its own
+  # file so that lib/seams.rb stays a thin require-only wrapper.
+  module Runtime
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield configuration
+    end
+
+    def reset_configuration!
+      @configuration = Configuration.new
+      Events::Publisher.reset!     if defined?(Events::Publisher)
+      Observability.reset!         if defined?(Observability)
+    end
+  end
+
+  extend Runtime
+end

data/lib/seams/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Seams
+  VERSION = "0.1.0"
+end

data/lib/seams.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require "seams/version"
+
+# Seams — A CLI framework that generates modular Rails engines.
+#
+# See https://github.com/Davidslv/seams for documentation.
+module Seams
+  class Error < StandardError; end
+  class ConfigurationError < Error; end
+  class GeneratorError < Error; end
+end
+
+require "seams/configuration"
+require "seams/runtime"
+require "seams/events"
+require "seams/events/adapter"
+require "seams/events/adapters/active_support"
+require "seams/event_registry"
+require "seams/events/publisher"
+require "seams/observability"
+require "seams/observability/adapter"
+require "seams/observability/adapters/rails_logger"