lcp 0.1.0

data/lib/lcp_ruby/generators/entity_menu_writer.rb

@@ -0,0 +1,258 @@
+# frozen_string_literal: true
+
+require "thor"
+require "set"
+
+module LcpRuby
+  module Generators
+    # Inserts a `- view_group: <name>` entry into `menu.yml` at the location
+    # named by `--menu=...` on the entity generator. Parser + planner are
+    # pure-functional (string/array in, struct out) so tests don't need a
+    # tempdir; the I/O wrapper `apply!` is the only side-effecting method.
+    #
+    # Spec: docs/design/entity_generator_menu_flag.md
+    module EntityMenuWriter
+      # Recognised marker forms in menu.yml. The "label" capture is optional —
+      # absent for section-level markers (`# lcp:menu top`), present for
+      # dropdown markers (`# lcp:menu top > "School"`). Trailing comment text
+      # (e.g. `# entity generator marker — do not edit/delete`) is ignored.
+      MARKER_RE = /^(\s*)# lcp:menu (top|sidebar)(?: > "([^"]+)")?\s*(?:#.*)?$/
+
+      SECTIONS = %w[top sidebar].freeze
+      POSITIONS = %w[bottom right].freeze
+      ROOT = "ROOT"
+      MARKER_WARNING = "# entity generator marker - do not edit/delete"
+
+      # Lucide icon names are kebab-case alphanumeric (e.g. `users`, `chart-bar`,
+      # `arrow-up-right`). Rejecting anything else prevents YAML injection via
+      # `--menu-icon='foo\n  malicious: x'` — CLI is a trusted surface but the
+      # check is cheap and symmetric with `validate_parent_label!`.
+      ICON_PATTERN = /\A[a-z0-9][a-z0-9-]*\z/
+
+      module_function
+
+      # Parses the value of `--menu=[<section>:]ROOT|<DropdownLabel>[:bottom|:right]`.
+      # Returns `{section:, parent:, position:}` or raises Thor::Error.
+      #
+      # `available_sections` is the set of sections actually present in menu.yml
+      # (derived from `scan` results). The default section is `top` when both
+      # sections are present, else the only section present. When the requested
+      # section is absent from menu.yml, raises with the "not initialized"
+      # message from D7 §Error Cases.
+      def parse_flag(value, available_sections:)
+        raise Thor::Error, invalid_format_message(value) if value.nil? || value.empty?
+
+        parts = value.split(":", -1)
+        raise Thor::Error, invalid_format_message(value) if parts.empty? || parts.size > 3
+
+        # Three legal shapes:
+        #   ROOT | <Label>                            → 1 part
+        #   <section>:ROOT | <section>:<Label> | <Label>:<pos> | ROOT:<pos>  → 2 parts
+        #   <section>:ROOT:<pos> | <section>:<Label>:<pos>                  → 3 parts
+        section = nil
+        parent = nil
+        position = nil
+
+        case parts.size
+        when 1
+          parent = parts[0]
+        when 2
+          if SECTIONS.include?(parts[0])
+            section = parts[0]
+            parent = parts[1]
+          elsif POSITIONS.include?(parts[1])
+            parent = parts[0]
+            position = parts[1]
+          else
+            raise Thor::Error, invalid_format_message(value)
+          end
+        when 3
+          unless SECTIONS.include?(parts[0]) && POSITIONS.include?(parts[2])
+            raise Thor::Error, invalid_format_message(value)
+          end
+          section = parts[0]
+          parent = parts[1]
+          position = parts[2]
+        end
+
+        raise Thor::Error, invalid_format_message(value) if parent.nil? || parent.empty?
+        validate_parent_label!(parent) unless parent == ROOT
+
+        section ||= default_section(available_sections)
+        unless available_sections.include?(section)
+          raise Thor::Error,
+            "Section '#{section}' not initialized in menu.yml. " \
+            "Re-run install with --menu-layout=#{section} (or 'both'), " \
+            "or add the section block manually with its marker."
+        end
+
+        if position && parent != ROOT
+          raise Thor::Error,
+            "--menu position keyword (':bottom', ':right') is only valid with parent=ROOT; " \
+            "'#{parent}' is a dropdown."
+        end
+
+        if position == "bottom" && section != "sidebar"
+          raise Thor::Error,
+            "position ':bottom' is only valid in sidebar; got --menu=#{value}. " \
+            "Use --menu=sidebar:ROOT:bottom."
+        end
+
+        { section: section, parent: parent, position: position }
+      end
+
+      # Walks each line of menu.yml and collects:
+      #   markers          – ordered list of `{section:, label:, line_idx:, indent:}`
+      #   view_groups_present – Set of view group names already in the file
+      #   sections_present – Set of sections discovered (top, sidebar)
+      def scan(lines)
+        markers = []
+        view_groups_present = Set.new
+        sections_present = Set.new
+
+        lines.each_with_index do |line, idx|
+          if (m = line.match(MARKER_RE))
+            sections_present << m[2]
+            markers << { section: m[2], label: m[3], line_idx: idx, indent: m[1] }
+          elsif (vg = line.match(/^\s*-\s+view_group:\s+([A-Za-z0-9_\-]+)\s*$/))
+            view_groups_present << vg[1]
+          end
+        end
+
+        { markers: markers, view_groups_present: view_groups_present, sections_present: sections_present }
+      end
+
+      # Plans the insertion. Returns one of:
+      #   {action: :insert,          lines: [..], idx:, message:, section:, parent:}
+      #   {action: :create_dropdown, lines: [..], idx:, message:, section:, parent:}
+      #   {action: :skip,            message:, view_group:}
+      def plan_insert(scan_result, section:, parent:, view_group:, icon: nil, position: nil)
+        validate_icon!(icon)
+
+        if scan_result[:view_groups_present].include?(view_group)
+          return { action: :skip, message: "[skip] view_group: #{view_group} already in menu.yml",
+                   view_group: view_group }
+        end
+
+        if parent == ROOT
+          marker = find_section_marker(scan_result[:markers], section)
+          raise Thor::Error, marker_missing_message(section, nil) unless marker
+
+          lines = build_entry_lines(view_group: view_group, icon: icon, position: position,
+                                    indent: marker[:indent])
+          return { action: :insert, lines: lines, idx: marker[:line_idx],
+                   section: section, parent: ROOT,
+                   message: "Menu entry added (section '#{section}', parent 'ROOT')" }
+        end
+
+        dropdown_markers = scan_result[:markers].select { |m| m[:section] == section && m[:label] == parent }
+        if dropdown_markers.size > 1
+          raise Thor::Error,
+            "Dropdown label '#{parent}' appears multiple times in menu.yml. " \
+            "Disambiguate manually before re-running."
+        end
+
+        if dropdown_markers.size == 1
+          marker = dropdown_markers.first
+          lines = build_entry_lines(view_group: view_group, icon: icon, position: nil,
+                                    indent: marker[:indent])
+          return { action: :insert, lines: lines, idx: marker[:line_idx],
+                   section: section, parent: parent,
+                   message: "Menu entry added (section '#{section}', parent '#{parent}')" }
+        end
+
+        # Auto-create dropdown above section marker
+        section_marker = find_section_marker(scan_result[:markers], section)
+        raise Thor::Error, marker_missing_message(section, nil) unless section_marker
+
+        lines = build_dropdown_block(label: parent, view_group: view_group, icon: icon,
+                                     indent: section_marker[:indent], section: section)
+        { action: :create_dropdown, lines: lines, idx: section_marker[:line_idx],
+          section: section, parent: parent,
+          message: "Menu dropdown '#{parent}' auto-created (section '#{section}')" }
+      end
+
+      # Builds an ordered array of "<indent>...\n" lines for a single
+      # view_group entry. Field order: view_group → icon → position. Position
+      # is only emitted at ROOT (caller passes nil for dropdown nesting).
+      def build_entry_lines(view_group:, icon: nil, position: nil, indent: "    ")
+        lines = []
+        lines << "#{indent}- view_group: #{view_group}\n"
+        lines << "#{indent}  icon: #{icon}\n" if icon
+        lines << "#{indent}  position: #{position}\n" if position
+        lines
+      end
+
+      # Builds the auto-created dropdown block plus its child marker. Icon
+      # attaches to the dropdown (more visible at top level than on a single
+      # hidden child — D7 §"Modifier-attachment rule").
+      def build_dropdown_block(label:, view_group:, icon: nil, indent: "    ", section:)
+        child_indent = indent + "  " # children indent = marker-indent + 2 spaces
+        lines = []
+        lines << "#{indent}- label: \"#{label}\"\n"
+        lines << "#{indent}  icon: #{icon}\n" if icon
+        lines << "#{indent}  children:\n"
+        lines << "#{child_indent}- view_group: #{view_group}\n"
+        lines << "#{child_indent}# lcp:menu #{section} > \"#{label}\"  #{MARKER_WARNING}\n"
+        lines
+      end
+
+      # Side-effecting wrapper. Splices in `plan[:lines]` at `plan[:idx]` and
+      # writes the result back to disk. No-op for :skip plans.
+      #
+      # `cached_lines:` lets the caller pass the lines array it already read
+      # when computing the plan (entity_generator does this in plan_menu_entry).
+      # When omitted, apply! re-reads the file — useful for callers that have
+      # only the plan and the path.
+      def apply!(menu_path, plan, cached_lines: nil)
+        return if plan.nil? || plan[:action] == :skip
+        unless %i[insert create_dropdown].include?(plan[:action])
+          raise ArgumentError, "Unknown plan action: #{plan[:action].inspect}"
+        end
+
+        lines = cached_lines || File.readlines(menu_path)
+        lines.insert(plan[:idx], *plan[:lines])
+        File.write(menu_path, lines.join)
+      end
+
+      def invalid_format_message(value)
+        "Invalid --menu format: '#{value}'. Expected: [<section>:]ROOT|<DropdownLabel>[:bottom|:right]"
+      end
+
+      def marker_missing_message(section, _parent)
+        "menu.yml at config/lcp_ruby/menu.yml is missing '# lcp:menu #{section}' marker. " \
+        "Add the marker manually or restore from the install_generator template."
+      end
+
+      def find_section_marker(markers, section)
+        markers.find { |m| m[:section] == section && m[:label].nil? }
+      end
+
+      def default_section(available_sections)
+        return "top" if available_sections.include?("top")
+        return "sidebar" if available_sections.include?("sidebar")
+        raise Thor::Error,
+          "menu.yml has no insertion markers. " \
+          "Re-run install with --menu-layout=top, sidebar, or both, " \
+          "or add a `# lcp:menu <section>` marker manually."
+      end
+
+      def validate_parent_label!(label)
+        if label.include?(":") || label.include?("\"")
+          raise Thor::Error,
+            "Dropdown label must not contain ':' or '\"' (got: '#{label}'). " \
+            "Edit menu.yml manually for unusual labels."
+        end
+      end
+
+      def validate_icon!(icon)
+        return if icon.nil?
+        unless ICON_PATTERN.match?(icon)
+          raise Thor::Error,
+            "Invalid --menu-icon value '#{icon}'. Expected a Lucide icon name " \
+            "(lowercase letters, digits, hyphens; e.g. `users`, `chart-bar`)."
+        end
+      end
+    end
+  end
+end

data/lib/lcp_ruby/generators/feature_registry.rb

@@ -0,0 +1,208 @@
+# frozen_string_literal: true
+
+module LcpRuby
+  module Generators
+    # Single source of truth for feature generator metadata.
+    #
+    # Three consumers read this:
+    # 1. CLI (`lcp new`) — preset expansion + wizard feature picker.
+    #    Pure-Ruby, no Rails boot — must be require-able from `bin/lcp`
+    #    before `rails new` runs.
+    # 2. Generator runtime (via `Prerequisites` concern) — `requires:` is
+    #    the contract checked in `check_lcp_prerequisites!`.
+    # 3. `lcp_ruby:doctor` rake task — feature state walk.
+    #
+    # Per-entry shape:
+    #   label:           — wizard-visible string
+    #   group:           — wizard grouping (Authentication, Data Management, …)
+    #   requires:        — feature names that must already be installed
+    #   provides_models: — model file names dropped under
+    #                      `config/lcp_ruby/models/<name>.{rb,yml}`. Used by
+    #                      `installed?` as a file-presence marker. Empty
+    #                      list means "no canonical model marker" (rare).
+    #
+    # Drift between this hash and actual generator output is caught by
+    # contract specs that run each generator against a tmpdir and inspect
+    # the resulting `config/lcp_ruby/models/` directory.
+    module FeatureRegistry
+      class UnknownFeature   < StandardError; end
+      class CyclicDependency < StandardError; end
+
+      # Path constants used by `installed?`, the `lcp_ruby:doctor` rake
+      # task, and `lcp new` manifest plumbing. `app_template.rb` cannot
+      # reuse these — it runs in the `rails new` scaffold context before
+      # Bundler loads the gem — so those literals are mirrored inline
+      # there and pinned by the registry-vs-template drift test.
+      MODELS_CONFIG_DIR     = "config/lcp_ruby/models"
+      INSTALL_MANIFEST_PATH = "tmp/lcp_ruby/install_manifest.json"
+
+      FEATURES = {
+        "install_auth" => {
+          label:           "Built-in authentication (Devise)",
+          group:           "Authentication",
+          requires:        [],
+          provides_models: %w[user]
+        },
+        "custom_fields" => {
+          label:           "Custom fields",
+          group:           "Data Management",
+          requires:        [],
+          provides_models: %w[custom_field_definition]
+        },
+        "export" => {
+          label:           "Export",
+          group:           "Data Management",
+          requires:        [],
+          provides_models: %w[export_log export_profile]
+        },
+        "import" => {
+          label:           "Import",
+          group:           "Data Management",
+          requires:        %w[background_jobs],
+          provides_models: %w[import_row import_profile]
+        },
+        "batch_operations" => {
+          label:           "Batch operations",
+          group:           "Data Management",
+          requires:        [],
+          provides_models: %w[batch_operation batch_operation_item]
+        },
+        "role_model" => {
+          label:           "Database-backed roles",
+          group:           "Access Control",
+          requires:        [],
+          provides_models: %w[role]
+        },
+        "permission_source" => {
+          label:           "Dynamic permissions",
+          group:           "Access Control",
+          requires:        [],
+          provides_models: %w[permission_config]
+        },
+        "groups" => {
+          label:           "Groups",
+          group:           "Access Control",
+          requires:        [],
+          provides_models: %w[group group_membership group_role_mapping]
+        },
+        "auditing" => {
+          label:           "Auditing",
+          group:           "Audit & Monitoring",
+          requires:        [],
+          provides_models: %w[audit_log]
+        },
+        "monitoring" => {
+          label:           "Monitoring dashboard",
+          group:           "Audit & Monitoring",
+          requires:        [],
+          provides_models: %w[lcp_error_log]
+        },
+        "saved_filters" => {
+          label:           "Saved filters",
+          group:           "Audit & Monitoring",
+          requires:        [],
+          provides_models: %w[saved_filter]
+        },
+        "pages" => {
+          label:           "Database-backed pages",
+          group:           "Pages & Jobs",
+          requires:        [],
+          provides_models: %w[page_config]
+        },
+        "background_jobs" => {
+          label:           "Background job tracking",
+          group:           "Pages & Jobs",
+          requires:        [],
+          provides_models: %w[job_execution]
+        },
+        "workflow_definition" => {
+          label:           "Workflow definitions",
+          group:           "Workflows",
+          requires:        [],
+          provides_models: %w[workflow_definition]
+        },
+        "workflow_approvals" => {
+          label:           "Workflow approvals",
+          group:           "Workflows",
+          requires:        [],
+          provides_models: %w[workflow_approval_request workflow_approval_step workflow_approval_task]
+        },
+        "workflow_audit_log" => {
+          label:           "Workflow audit log",
+          group:           "Workflows",
+          requires:        [],
+          provides_models: %w[workflow_audit_log]
+        },
+        "gapfree_sequences" => {
+          label:           "Gap-free sequences",
+          group:           "Other",
+          requires:        [],
+          provides_models: %w[gapfree_sequence]
+        },
+        "api_tokens" => {
+          label:           "API tokens",
+          group:           "Authentication",
+          requires:        %w[install_auth],
+          provides_models: %w[api_token]
+        },
+        "oidc_role_mappings" => {
+          label:           "OIDC role mappings",
+          group:           "Authentication",
+          requires:        [],
+          provides_models: %w[oidc_role_mapping]
+        }
+      }.freeze
+
+      # `extend self` exposes module methods as both `Registry.foo`
+      # callable form and (when included elsewhere) instance methods.
+      # Cleaner than mixing `module_function` with `private_class_method`
+      # because `private` works the way you'd expect — see `visit` below.
+      extend self
+
+      # File-presence marker. Returns true when every model in
+      # `provides_models` exists at `config/lcp_ruby/models/<name>.{rb,yml}`
+      # under +destination_root+. Empty `provides_models` collapses to
+      # `true` — features without a canonical marker are reported as
+      # "installed" if their entry exists at all.
+      def installed?(feature, destination_root)
+        meta = FEATURES[feature.to_s]
+        return false unless meta
+        models = meta[:provides_models]
+        return true if models.empty?
+        models_dir = File.join(destination_root, MODELS_CONFIG_DIR)
+        models.all? do |name|
+          %w[rb yml].any? { |ext| File.exist?(File.join(models_dir, "#{name}.#{ext}")) }
+        end
+      end
+
+      # Topologically sort feature names so dependencies appear before
+      # their dependents. Stable: order within the input list — and
+      # within each `requires:` list — is preserved.
+      #
+      # Raises `UnknownFeature` if any name is not in `FEATURES`,
+      # `CyclicDependency` if a cycle is detected.
+      def expand_with_dependencies(names)
+        ordered  = []
+        visited  = {}
+        visiting = {}
+        Array(names).each { |n| visit(n.to_s, ordered, visited, visiting) }
+        ordered
+      end
+
+      private
+
+      def visit(name, ordered, visited, visiting)
+        return if visited[name]
+        raise CyclicDependency, "Dependency cycle detected through feature '#{name}'" if visiting[name]
+        meta = FEATURES[name]
+        raise UnknownFeature, "Unknown feature: #{name.inspect}" unless meta
+
+        visiting[name] = true
+        meta[:requires].each { |dep| visit(dep, ordered, visited, visiting) }
+        visiting.delete(name)
+        visited[name] = true
+        ordered << name
+      end
+    end
+  end
+end

data/lib/lcp_ruby/generators/prerequisites.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require_relative "feature_registry"
+
+module LcpRuby
+  module Generators
+    # Mixin for `lcp_ruby:<feature>` generators that enforces declarative
+    # prerequisites declared via `requires_features :foo, :bar`.
+    #
+    # The concern installs `check_lcp_prerequisites!` as the FIRST Thor
+    # task on the host generator (via `define_method` in the `included`
+    # hook — see `define_method` ordering verification in the design
+    # doc). It runs before any file write; on a missing prereq it raises
+    # `Thor::Error` with a copy-pasteable hint.
+    #
+    # Usage:
+    #
+    #   class ImportGenerator < Rails::Generators::Base
+    #     include FormatSupport
+    #     include LcpRuby::Generators::Prerequisites
+    #     requires_features :background_jobs
+    #     # … rest of generator
+    #   end
+    #
+    # For option-driven prereqs (entity generator's `--auditing`,
+    # `--custom-fields`), override the instance hook:
+    #
+    #   def lcp_dynamic_required_features
+    #     out = []
+    #     out << "auditing"      if options[:auditing]
+    #     out << "custom_fields" if options[:custom_fields]
+    #     out
+    #   end
+    #
+    # Include order: `Prerequisites` must come before any explicit `def`
+    # in the host generator. `FormatSupport` (which adds only a
+    # `class_option`, not a Thor task) may come either before or after.
+    module Prerequisites
+      def self.included(base)
+        base.extend ClassMethods
+
+        # Defining `check_lcp_prerequisites!` via `base.define_method`
+        # (rather than as a plain module instance method) is intentional:
+        # only methods on the generator class itself appear in
+        # `public_instance_methods(false)`, which is what Thor uses to
+        # enumerate tasks. Module-body `def`s are inherited but invisible
+        # to Thor's task discovery — exactly what helper methods like
+        # `lcp_format_missing_prereqs` (below) need.
+        base.send :define_method, :check_lcp_prerequisites! do
+          static  = self.class.lcp_required_features
+          dynamic = respond_to?(:lcp_dynamic_required_features) ? Array(lcp_dynamic_required_features) : []
+          required = (static + dynamic).map(&:to_s).uniq
+          return if required.empty?
+
+          missing = required.reject { |f| FeatureRegistry.installed?(f, destination_root) }
+          return if missing.empty?
+
+          raise Thor::Error, lcp_format_missing_prereqs(missing)
+        end
+      end
+
+      # Helper — kept as a module-body `def` so Thor does NOT register it
+      # as a task. Visible as an instance method on the host generator
+      # via normal `include` resolution.
+      def lcp_format_missing_prereqs(missing)
+        lines = [ "Missing prerequisite feature(s): #{missing.join(', ')}", "", "This generator requires:" ]
+        missing.each do |feat|
+          provides = FeatureRegistry::FEATURES.dig(feat, :provides_models) || []
+          suffix   = provides.any? ? " (provides: #{provides.join(', ')})" : ""
+          lines << "  - lcp_ruby:#{feat}#{suffix}"
+        end
+        lines << ""
+        lines << "Run them in order, or run `bundle exec rake lcp_ruby:doctor` to see the full dependency graph."
+        lines.join("\n")
+      end
+
+      module ClassMethods
+        # Declare hard prerequisites — features whose `provides_models` must
+        # all exist before this generator may run. Multiple calls accumulate.
+        def requires_features(*names)
+          @lcp_required_features = ((@lcp_required_features || []) + names.flatten.map(&:to_s)).uniq
+        end
+
+        def lcp_required_features
+          @lcp_required_features || []
+        end
+      end
+    end
+  end
+end