lcp 0.1.0

data/docs/guides/menu.md

@@ -0,0 +1,373 @@
+# Menu Guide
+
+This guide walks you through setting up custom navigation menus for your LCP Ruby application.
+
+## Default Behavior (No menu.yml)
+
+Without a `menu.yml`, LCP Ruby auto-generates a flat top bar from your view groups, sorted by their `navigation.position`:
+
+```
+[ Projects ] [ Tasks ] [ Settings ]
+```
+
+This works well for small applications with a few models.
+
+**Two quick wins before writing menu.yml:**
+
+- **Control order without menu.yml.** Set `navigation: { position: N }` on each view-group YAML in `config/lcp_ruby/views/<name>.yml` — lower numbers come first; default is 99. Auto-generated view groups (those without explicit YAML) start at position 900+ so any user-defined `position` always wins.
+- **Set the post-login landing page.** By default `/` redirects to the first navigable view group (alphabetical for ties). To send users to a specific dashboard or presenter, set `config.landing_page = "<slug>"` in `config/initializers/lcp_ruby.rb`. See [engine-configuration.md#landing_page](../reference/engine-configuration.md#landing_page) for the per-role hash form.
+
+## Adding a menu.yml
+
+Create `config/lcp_ruby/menu.yml` to customize navigation:
+
+### Step 1: Simple Top Bar
+
+```yaml
+menu:
+  top_menu:
+    - view_group: projects
+    - view_group: tasks
+    - view_group: settings
+```
+
+This produces the same flat top bar, but now you control the order.
+
+### Step 2: Add Dropdown Grouping
+
+Group related items into dropdowns:
+
+```yaml
+menu:
+  top_menu:
+    - view_group: projects
+    - label: "Administration"
+      icon: shield
+      children:
+        - view_group: users
+        - view_group: settings
+```
+
+The "Administration" item becomes a hover dropdown containing "Users" and "Settings".
+
+### Step 3: Add Custom Links
+
+Link to pages outside the LCP engine:
+
+```yaml
+menu:
+  top_menu:
+    - view_group: projects
+    - label: "Dashboard"
+      icon: home
+      url: /dashboard
+    - label: "Tools"
+      children:
+        - view_group: tasks
+        - separator: true
+        - label: "Reports"
+          url: /reports
+```
+
+### Step 4: Switch to Sidebar
+
+Replace `top_menu` with `sidebar_menu`:
+
+```yaml
+menu:
+  sidebar_menu:
+    - view_group: projects
+    - label: "Work"
+      icon: briefcase
+      children:
+        - view_group: tasks
+    - view_group: settings
+      position: bottom
+```
+
+Groups become collapsible sections. Items with `position: bottom` are pinned to the sidebar bottom.
+
+### Right-aligned top-bar items
+
+In `top_menu`, use `position: right` on a top-level item to move it to a right-aligned zone (after a flex spacer, before the theme toggle). Typical use: profile, settings, log out, notifications.
+
+```yaml
+menu:
+  top_menu:
+    - view_group: dashboard
+    - view_group: reports
+    - url: /profile/me
+      label: "My Profile"
+      icon: user
+      position: right
+    - label: "Log out"
+      icon: log-out
+      url: /logout
+      position: right
+```
+
+Multiple right-aligned items render in YAML definition order. `position: right` applies only to top-level `top_menu` items; dropdown children ignore it. See the reference for the full [`position` semantics table](../reference/menu.md#position).
+
+### Step 5: Combined Layout
+
+Use both for a top bar + sidebar:
+
+```yaml
+menu:
+  top_menu:
+    - label: "Dashboard"
+      url: /dashboard
+    - label: "Reports"
+      url: /reports
+
+  sidebar_menu:
+    - view_group: projects
+    - view_group: tasks
+    - view_group: settings
+      position: bottom
+```
+
+## Role-Based Visibility
+
+Restrict menu items to specific roles:
+
+```yaml
+menu:
+  sidebar_menu:
+    - view_group: projects
+    - view_group: tasks
+    - label: "Admin"
+      icon: shield
+      visible_when:
+        role: [admin]
+      children:
+        - view_group: users
+        - view_group: audit_log
+```
+
+The "Admin" section and all its children are hidden from non-admin users.
+
+## Hiding View Groups from Navigation
+
+Some view groups exist for routing and view switching but should not appear in navigation:
+
+```yaml
+# config/lcp_ruby/views/audit_log.yml
+view_group:
+  model: audit_log
+  primary: audit_log
+  navigation: false
+  views:
+    - presenter: audit_log
+```
+
+The `navigation: false` setting:
+- Removes the view group from auto-generated navigation
+- Prevents auto-append in `:auto` mode
+- Does not affect direct URL access (e.g., `/audit-log` still works)
+
+## Strict Mode
+
+For production apps where you want full control:
+
+```ruby
+# config/initializers/lcp_ruby.rb
+LcpRuby.configure do |config|
+  config.menu_mode = :strict
+end
+```
+
+In strict mode:
+- `menu.yml` is required (raises error if missing)
+- No view groups are auto-appended
+- View groups must use `navigation: false` (not `navigation: {position: 1}`)
+
+## Auto-Append Behavior
+
+In `:auto` mode with `menu.yml`, any navigable view groups not referenced in the menu are automatically appended to `top_menu`. This ensures new models are visible without manual menu updates.
+
+To prevent a view group from being auto-appended, set `navigation: false` on it.
+
+### When does auto-append fire?
+
+Boot log tells you on every restart:
+
+```
+[LcpRuby] Auto-appended 4 view groups to top_menu: alpha, bravo, charlie, delta.
+Add them to config/lcp_ruby/menu.yml for custom ordering or dropdown placement,
+or set `navigation: { auto_append: false }` on the view group to hide it from the menu.
+```
+
+The line is silent when nothing was appended (menu.yml references every navigable view group) and never appears in `:strict` mode. Treat it as a gentle reminder of what's growing alphabetically at the end of your top bar.
+
+## Adding entities to the menu
+
+The entity generator's `--menu` flag inserts a `- view_group: <name>` entry directly into `menu.yml` at scaffold time, so you don't have to context-switch into the menu file after generating a model:
+
+```bash
+# Top-level entry in the top bar
+rails g lcp_ruby:entity Student name:string --label-method=name --menu=ROOT
+
+# Inside a dropdown (auto-creates if "School" doesn't exist yet)
+rails g lcp_ruby:entity Course title:string --label-method=title --menu=School
+
+# Same dropdown, nested as the second entry — no auto-create on re-use
+rails g lcp_ruby:entity Teacher name:string --label-method=name --menu=School
+
+# Sidebar top-level, pinned to the bottom (settings-style)
+rails g lcp_ruby:entity Settings name:string --label-method=name --menu=sidebar:ROOT:bottom
+
+# Top bar, right-aligned (profile/notification style)
+rails g lcp_ruby:entity Notifications title:string --label-method=title --menu=top:ROOT:right
+
+# Add an icon (Lucide names; attaches to the entry, or the dropdown if auto-created)
+rails g lcp_ruby:entity Role name:string --label-method=name --menu=sidebar:Admin --menu-icon=lock
+```
+
+**Grammar:** `--menu=[<section>:]ROOT|<DropdownLabel>[:bottom|:right]`. Section defaults to `top` when both sections are seeded, else the only seeded section. `ROOT` means top-level in that section; any other word names a dropdown (existing or to-be-created). `:bottom` is valid only with `--menu=sidebar:ROOT`; `:right` is valid only with `--menu=top:ROOT`.
+
+**Pre-conditions:** `menu.yml` must include `# lcp:menu <section>` insertion markers — these are seeded by `rails generate lcp_ruby:install --menu-layout=top|sidebar|both` (default `both`) and by `lcp new`. Apps generated before the marker convention can opt in by pasting the marker line manually:
+
+```yaml
+menu:
+  top_menu:
+    - view_group: items
+    # lcp:menu top  # entity generator marker - do not edit/delete
+```
+
+The generator's preflight catches missing markers, malformed grammar, ambiguous dropdown labels, etc., and aborts **before** writing the model/presenter/permissions, so a failed `--menu` doesn't leave half-generated files on disk. On success, it backs up the pre-mutation file to `.menu.yml.bak`, applies the edit, and re-validates the menu in-process — a validation failure leaves the new menu.yml on disk for inspection alongside the backup.
+
+If `--menu` is omitted, the post-install message recommends it. In `:auto` mode, the view group is auto-appended alphabetically to `top_menu` as usual; in `:strict` mode, it stays invisible until you wire it in by hand.
+
+## Organizing Large Dropdowns with Sub-Groups
+
+When a dropdown grows beyond 10-15 items, use sub-groups to organize them:
+
+```yaml
+menu:
+  top_menu:
+    - label: "Features"
+      icon: star
+      children:
+        - view_group: fields
+        - view_group: models
+        - separator: true
+        - label: "Search & Filters"
+          children:
+            - view_group: advanced_search
+            - view_group: saved_filters
+            - view_group: query_language
+        - label: "Workflow"
+          children:
+            - view_group: workflows
+            - view_group: approval_tasks
+            - view_group: job_executions
+        - separator: true
+        - view_group: audit_log
+```
+
+Sub-groups appear as flyout submenus in the top menu and as nested collapsible sections in the sidebar.
+
+**Depth limit:** Maximum 2 levels of `children:` nesting. The top-level group is level 1, sub-groups inside it are level 2. Deeper nesting raises a `MetadataError` at boot time.
+
+Sub-groups support all the same features as top-level groups: `visible_when` role constraints, badges, separators, and mixed child types.
+
+## Adding Badges
+
+Badges display dynamic data (counts, labels, icons) on menu items. They require two parts: a **data provider** that fetches the data, and a **rendering form** that displays it.
+
+### Step 1: Create a Data Provider
+
+Create a class in `app/lcp_services/data_providers/` that responds to `call(user:)`:
+
+```ruby
+# app/lcp_services/data_providers/open_tasks.rb
+module LcpRuby::HostServices::DataProviders
+  class OpenTasks
+    def self.call(user:)
+      count = LcpRuby::Dynamic::Task.where(status: "open").count
+      count > 0 ? count : nil  # nil hides the badge
+    end
+  end
+end
+```
+
+The provider is auto-discovered and registered under `Services::Registry` with the key `open_tasks`.
+
+### Step 2: Add Badge to Menu Item
+
+Reference the provider in your `menu.yml` along with a rendering form:
+
+**Using a built-in renderer (simplest):**
+
+```yaml
+menu:
+  sidebar_menu:
+    - view_group: tasks
+      badge:
+        provider: open_tasks
+        renderer: count_badge
+```
+
+Built-in renderers: `count_badge` (red pill with number), `text_badge` (text label), `icon_badge` (icon).
+
+**Using a template:**
+
+```yaml
+- view_group: inbox
+  badge:
+    provider: unread_messages
+    template: "{count} new"
+```
+
+If the provider returns `{ "count" => 5 }`, the badge displays "5 new". For simple values, use `{value}`.
+
+**Using a partial:**
+
+```yaml
+- view_group: system_health
+  badge:
+    provider: health_status
+    partial: "badges/health_indicator"
+```
+
+The partial receives a `data` local variable with the provider's return value.
+
+### Step 3: Customize Appearance
+
+Pass `options` to renderers:
+
+```yaml
+- view_group: alerts
+  badge:
+    provider: alert_count
+    renderer: text_badge
+    options:
+      color: "#dc3545"
+```
+
+### Writing a Custom Badge Renderer
+
+Custom badge renderers are standard `Display::BaseRenderer` subclasses:
+
+```ruby
+# app/renderers/priority_badge.rb
+module LcpRuby::HostRenderers
+  class PriorityBadge < LcpRuby::Display::BaseRenderer
+    def render(value, options = {}, record: nil, view_context: nil)
+      return nil unless value.is_a?(Hash)
+      level = value["level"]
+      color = level == "high" ? "#dc3545" : "#ffc107"
+      view_context.content_tag(:span, level.upcase,
+        class: "lcp-menu-badge lcp-menu-badge-text",
+        style: "background:#{color}")
+    end
+  end
+end
+```
+
+Then reference it in YAML: `renderer: priority_badge`.
+
+### Staleness Note
+
+Badges are rendered server-side on each page load. For real-time updates, consider wrapping badge output in a Turbo Frame with periodic refresh.

data/docs/guides/monitoring.md

@@ -0,0 +1,254 @@
+# Monitoring Guide
+
+This guide walks through setting up monitoring for your LCP Ruby application.
+
+## Quick Setup
+
+**Step 1:** Run the generator to create error log model, presenter, permissions, and dashboard:
+
+```bash
+rails generate lcp_ruby:monitoring
+```
+
+**Step 2:** (Optional) Add Prometheus client for metric collection:
+
+```ruby
+# Gemfile
+gem "prometheus-client"
+```
+
+**Step 3:** Restart the server. The error log table is created automatically.
+
+That's it. Visit `/lcp_health` for health status, `/metrics` for Prometheus metrics, `/monitoring` for the dashboard, and `/error-logs` to browse errors.
+
+## Health Check
+
+The health endpoint at `GET /lcp_health` returns:
+- **200** — database connected and metadata loaded
+- **503** — database down or boot failed
+
+Response includes individual check results: `{"status": "ok", "checks": {"database": true, "booted": true}}`.
+
+### Kubernetes Probe Configuration
+
+```yaml
+livenessProbe:
+  httpGet:
+    path: /lcp_health
+    port: 3000
+  initialDelaySeconds: 30
+  periodSeconds: 10
+
+readinessProbe:
+  httpGet:
+    path: /lcp_health
+    port: 3000
+  initialDelaySeconds: 5
+  periodSeconds: 5
+```
+
+## Prometheus + Grafana
+
+### Scrape Configuration
+
+```yaml
+# prometheus.yml
+scrape_configs:
+  - job_name: lcp_ruby
+    metrics_path: /metrics
+    static_configs:
+      - targets: ['localhost:3000']
+```
+
+### Useful PromQL Queries
+
+```promql
+# Request rate (requests/second over 5 minutes)
+rate(lcp_ruby_requests_total[5m])
+
+# P95 latency
+histogram_quantile(0.95, rate(lcp_ruby_request_duration_seconds_bucket[5m]))
+
+# Error rate
+rate(lcp_ruby_errors_total[5m])
+
+# Cache hit rate
+sum(rate(lcp_ruby_cache_operations_total{operation="hit"}[5m])) /
+sum(rate(lcp_ruby_cache_operations_total{operation=~"hit|miss"}[5m]))
+
+# Requests per view group
+sum by (view_group) (rate(lcp_ruby_requests_total[5m]))
+
+# Requests per model
+sum by (model) (rate(lcp_ruby_requests_total[5m]))
+```
+
+## Monitoring Dashboard
+
+The generated dashboard at `/monitoring` displays:
+- **Models Loaded** — gauge from `lcp_ruby_models_loaded`
+- **Total Requests** — counter from `lcp_ruby_requests_total`
+- **Error Count** — counter from `lcp_ruby_errors_total`
+- **Recent Errors** — list from the `lcp_error_log` model
+
+Customize the dashboard by editing `config/lcp_ruby/pages/monitoring_dashboard.yml`. You can add more KPI cards, charts, or list widgets.
+
+## Custom Collectors
+
+Create collectors in `app/lcp_metrics/` to expose application-specific metrics:
+
+```ruby
+# app/lcp_metrics/business_metrics.rb
+class BusinessMetrics < LcpRuby::Metrics::Collector
+  gauge :active_orders, "Number of active orders"
+  gauge :revenue_today, "Revenue today in cents"
+  cache_ttl 60  # collect at most every 60 seconds
+
+  def collect
+    set(:active_orders, Order.where(status: "active").count)
+    set(:revenue_today, Order.where("created_at >= ?", Date.today).sum(:total_cents))
+  end
+end
+```
+
+Collectors are auto-discovered at boot and called on each `/metrics` request. Each `collect` call has a 5-second timeout and results are cached for `cache_ttl` seconds.
+
+### Event Subscriptions
+
+Collectors can also subscribe to AS::Notifications events for real-time counting:
+
+```ruby
+# app/lcp_metrics/payment_metrics.rb
+class PaymentMetrics < LcpRuby::Metrics::Collector
+  counter :payment_total, "Payment attempts", labels: [:gateway, :result]
+
+  subscribe "payment.processed" do |event|
+    increment(:payment_total, labels: {
+      gateway: event.payload[:gateway],
+      result: event.payload[:success] ? "success" : "failure"
+    })
+  end
+end
+```
+
+Subscriptions are activated at boot and cleaned up on `LcpRuby.reset!` (important for test isolation).
+
+## Large Deployments
+
+For high-traffic apps where `/metrics` adds latency or exposes internal data:
+
+```ruby
+LcpRuby.configure do |c|
+  c.metrics_endpoint = false  # Disable built-in /metrics route
+end
+```
+
+Then mount Prometheus middleware in the host app with authentication:
+
+```ruby
+# config/routes.rb (host app)
+authenticate :admin do
+  mount Prometheus::Middleware::Exporter, at: "/metrics"
+end
+```
+
+LCP Ruby metrics are automatically in the shared `Prometheus::Client.registry`.
+
+## Error Log
+
+### Viewing Errors
+
+Navigate to `/error-logs` to browse errors. The index shows error class, subsystem, message, occurrence count, and last occurrence time. Click any error to see the full stack trace and context.
+
+### Cleanup
+
+Register the model extension to add a `cleanup_before` scope:
+
+```ruby
+# config/initializers/lcp_ruby.rb
+LcpRuby.configure do |c|
+  c.on_model_ready("lcp_error_log") { |m| m.include(LcpErrorLogExtension) }
+end
+```
+
+Then clean up old errors:
+
+```ruby
+# In a rake task or background job
+LcpRuby.registry.model_for("lcp_error_log").cleanup_before(30.days.ago).delete_all
+```
+
+## Instrumenting Rescue Blocks
+
+Add `record_error` to your own rescue blocks:
+
+```ruby
+def risky_operation
+  external_api.call
+rescue ExternalApi::TimeoutError => e
+  LcpRuby.record_error(e, subsystem: "external_api", operation: "sync_orders")
+  nil  # graceful fallback
+end
+```
+
+This logs the error to Prometheus counters and (if enabled) the error log table. In dev/test, ensure your rescue block re-raises so bugs are caught early:
+
+```ruby
+rescue ExternalApi::TimeoutError => e
+  raise unless Rails.env.production?
+  LcpRuby.record_error(e, subsystem: "external_api", operation: "sync_orders")
+  nil
+end
+```
+
+## Testing
+
+### Testing Custom Collectors
+
+```ruby
+RSpec.describe BusinessMetrics do
+  it "collects active order count" do
+    create(:order, status: "active")
+    collector = described_class.new
+    collector.collect
+    # Verify via Prometheus registry if available,
+    # or just ensure collect doesn't raise
+  end
+end
+```
+
+### Testing Event Subscriptions
+
+```ruby
+RSpec.describe PaymentMetrics do
+  it "increments counter on payment event" do
+    collector = described_class.new
+    subs = described_class.activate_subscriptions!(collector)
+
+    ActiveSupport::Notifications.instrument("payment.processed", {
+      gateway: "stripe", success: true
+    })
+    # Verify metric was incremented
+  ensure
+    subs&.each { |s| ActiveSupport::Notifications.unsubscribe(s) }
+  end
+end
+```
+
+### Verifying Events in Tests
+
+```ruby
+it "fires request.lcp_ruby event" do
+  events = []
+  sub = ActiveSupport::Notifications.subscribe("request.lcp_ruby") do |*args|
+    events << ActiveSupport::Notifications::Event.new(*args)
+  end
+
+  get "/tasks"
+
+  expect(events.size).to eq(1)
+  expect(events.first.payload[:action]).to eq("index")
+ensure
+  ActiveSupport::Notifications.unsubscribe(sub)
+end
+```