lcp 0.1.0

data/docs/guides/host-controller-integration.md

@@ -0,0 +1,473 @@
+# Host Controller Integration Guide
+
+LCP Ruby gives you three escape hatches when the standard "everything in YAML" model doesn't fit:
+
+1. **Connect LCP to an existing AR model** — `bind_to:` attaches LCP metadata, presenters, and permissions to a model your host app already owns.
+2. **Take over a presenter's CRUD** — `controller:` routes a presenter's slug to your own controller, while keeping LCP search, layout, breadcrumbs, and views.
+3. **Override a single action** — `action_controllers:` lets you replace just `new`/`create` (or any subset) and leave the rest to LCP.
+
+This guide walks through each pattern with worked examples.
+
+## When to use which
+
+| Need | Pattern |
+|------|---------|
+| Existing host AR model + want LCP forms/permissions | `bind_to:` |
+| Custom multi-step flow (wizard, payment, approval) | `controller:` |
+| Override new/create only (e.g., extra setup step) | `action_controllers:` |
+| Existing controller, want LCP nav + permissions only | `controller:` + skip `CrudHelpers` |
+| Standalone page outside LCP (docs viewer, admin tool) | Plain `ApplicationController` + own layout |
+| Pure LCP standard CRUD | none — just YAML |
+
+## Pattern 1: `bind_to:` — LCP forms for an existing model
+
+Your host app already has `::Employee` with its own migrations, callbacks, and HR business logic. You want LCP forms, permissions, and an index table for it without recreating the model in LCP's database.
+
+### Step 1: Define the model in YAML
+
+```yaml
+# config/lcp_ruby/models/employee.yml
+model:
+  name: employee
+  bind_to: "::Employee"
+  fields:
+    - { name: name, type: string }
+    - { name: email, type: email }
+    - { name: department_id, type: integer }
+    - name: status
+      type: enum
+      enum_values: [active, inactive, on_leave]
+  associations:
+    - { type: belongs_to, name: department }
+  options:
+    label_method: name
+```
+
+What happens at boot:
+- `::Employee` is resolved via `constantize` and registered in `LcpRuby.registry` under the model name `employee`.
+- No table is created (`SchemaManager` is skipped).
+- `to_label` is defined on `::Employee` returning `employee.name` (used by association selects and breadcrumbs).
+- The fields you list become the **allowlist** for `readable: all` / `writable: all` permissions. Critical: `encrypted_password`, `reset_token`, etc. are NOT exposed unless explicitly listed.
+
+### Step 2: Add a presenter and permissions
+
+```yaml
+# config/lcp_ruby/presenters/employees.yml
+presenter:
+  name: employees
+  model: employee
+  slug: employees
+  index:
+    table_columns:
+      - { field: name }
+      - { field: email }
+      - { field: department }
+      - { field: status }
+```
+
+```yaml
+# config/lcp_ruby/permissions/employee.yml
+permissions:
+  model: employee
+  roles:
+    admin:
+      crud: [index, show, create, update, destroy]
+      fields: { readable: all, writable: all }
+      scope: all
+```
+
+### Step 3: Search support — opt in to Ransack
+
+If your presenter declares `search` parameters or `advanced_filter`, LCP will refuse to boot unless `::Employee` exposes `ransackable_attributes`. Two options:
+
+**Option A — let LCP define them from your fields:**
+```yaml
+model:
+  name: employee
+  bind_to: "::Employee"
+  bind_to_apply: [ransack]
+  fields: [...]
+```
+
+**Option B — define them yourself in the host class:**
+```ruby
+class Employee < ApplicationRecord
+  def self.ransackable_attributes(_auth = nil)
+    %w[id name email department_id status]
+  end
+end
+```
+
+LCP detects which approach you used and validates it at boot.
+
+### Step 4: Optionally apply other LCP features
+
+LCP doesn't touch your host class by default. You can opt into specific features via `bind_to_apply`:
+
+```yaml
+model:
+  name: employee
+  bind_to: "::Employee"
+  bind_to_apply: [ransack, soft_delete, auditing, validations]
+  fields: [...]
+```
+
+| Feature | What it does |
+|---------|--------------|
+| `validations` | Adds field validations from YAML to the host class |
+| `soft_delete` | Includes `Discard::Model` (requires `discarded_at` column) |
+| `auditing` | Adds audit log callbacks |
+| `userstamps` | Adds `created_by_id` / `updated_by_id` callbacks |
+| `workflow` | Applies workflow state machine |
+| `custom_fields` | Enables runtime custom fields (requires `custom_data` JSON) |
+
+See the [reference](../reference/host-controller-integration.md#bind_to_apply) for the full list.
+
+### Important: associations are metadata-only
+
+YAML `associations:` on `bind_to:` models are **never applied as AR macros**. They're used for presenter display, FK permitting in `permitted_params`, and association selects — but the host class must declare its own `belongs_to`/`has_many` in Ruby.
+
+```ruby
+class Employee < ApplicationRecord
+  belongs_to :department
+  # LCP YAML association is just metadata; this Ruby line is the real one.
+end
+```
+
+Why: re-declaring AR associations from YAML would overwrite reflections but leave stale callbacks (e.g., `optional: false` adds a presence validation that persists after re-declaring with `optional: true`). It's safer to let the host own associations.
+
+## Pattern 2: `controller:` — Custom controller for a complex workflow
+
+A checkout flow needs session state, external payment API calls, and conditional redirects between steps. Standard CRUD doesn't fit, but you still want LCP's layout, permission checks, breadcrumbs, and search infrastructure.
+
+### Step 1: Declare the controller in the presenter
+
+```yaml
+# config/lcp_ruby/presenters/checkout.yml
+presenter:
+  name: checkout
+  model: order
+  slug: checkout
+  controller: "checkouts"
+```
+
+All routes for `/checkout/...` now point to `::CheckoutsController` instead of LCP's `ResourcesController`.
+
+### Step 2: Generate the controller
+
+```bash
+rails generate lcp_ruby:host_controller checkout
+```
+
+This scaffolds `app/controllers/checkouts_controller.rb` with all 9 LCP concerns, all 7 CRUD actions, and a `permitted_params` skeleton.
+
+### Step 3: Customize what you need
+
+```ruby
+class CheckoutsController < ApplicationController
+  include LcpRuby::Controller::ErrorHandling
+  include LcpRuby::Controller::Authentication
+  include LcpRuby::Controller::PresenterSetup
+  include LcpRuby::Controller::Authorization
+  include LcpRuby::Controller::PathHelpers
+  include LcpRuby::Controller::Search
+  include LcpRuby::Controller::CrudHelpers
+
+  layout "lcp_ruby/application"
+
+  def new
+    @record = Order.new
+    authorize @record
+    setup_form_view_objects(@record)
+    render "lcp_ruby/resources/new"
+  end
+
+  def create
+    @record = Order.new(permitted_params)
+    authorize @record
+    if @record.save
+      PaymentGateway.initiate(@record)              # ← custom logic
+      redirect_to checkout_payment_path(@record)    # ← custom redirect
+    else
+      setup_form_view_objects(@record)
+      render "lcp_ruby/resources/new", status: :unprocessable_content
+    end
+  end
+end
+```
+
+The route `/checkout/new` and `/checkout/:id/edit` still appear in the LCP nav and breadcrumbs. Permissions are evaluated by `current_evaluator` from the `checkout` presenter's permissions YAML.
+
+### What stays with LCP
+
+Even with `controller:`, these routes still go to LCP's controllers:
+- Saved filters: `/checkout/saved-filters/*`
+- Custom fields: `/checkout/custom-fields/*`
+- Single actions: `POST /checkout/:id/actions/:action_name`
+- Workflow transitions: `POST /checkout/:id/transitions/:name`
+- Approval tasks: `POST /checkout/:id/approval_tasks/...`
+
+### Read-only custom controllers
+
+If your presenter has `read_only: true`, only `index` and `show` routes are generated for the custom controller. Write actions fall through to the catch-all (which respects LCP's `read_only` and returns 404 / hides UI).
+
+## Pattern 3: `action_controllers:` — Override a single action
+
+A host app uses LCP for the standard `index`, `show`, `edit`, `update`, `destroy` of orders, but needs a fully custom `new`/`create` that asks for a customer address in an external system before creating the record.
+
+```yaml
+# config/lcp_ruby/presenters/orders.yml
+presenter:
+  name: orders
+  model: order
+  slug: orders
+  action_controllers:
+    new: "orders/wizard#new"
+    create: "orders/wizard#create"
+    # index, show, edit, update, destroy → LCP ResourcesController
+```
+
+```ruby
+# app/controllers/orders/wizard_controller.rb
+module Orders
+  class WizardController < ApplicationController
+    include LcpRuby::Controller::PresenterSetup
+    include LcpRuby::Controller::Authorization
+    include LcpRuby::Controller::PathHelpers
+    include LcpRuby::Controller::CrudHelpers
+
+    def new
+      @customer = ExternalCRM.fetch_customer(params[:customer_id])
+      @record = Order.new(customer_id: @customer.id)
+      authorize @record
+      render "lcp_ruby/resources/new"
+    end
+
+    def create
+      @record = Order.new(permitted_params)
+      authorize @record
+      if @record.save
+        redirect_to resource_path(@record)
+      else
+        render "lcp_ruby/resources/new", status: :unprocessable_content
+      end
+    end
+  end
+end
+```
+
+The other actions (`/orders`, `/orders/:id`, `/orders/:id/edit`, etc.) still go through LCP's `ResourcesController` automatically. No additional configuration needed.
+
+## Pattern 4: Existing controller in LCP nav (gradual adoption)
+
+The host app has a working `/reports` controller. The team wants it to appear in the LCP sidebar and respect LCP's role visibility, without rewriting the controller.
+
+```yaml
+# config/lcp_ruby/presenters/reports.yml
+presenter:
+  name: reports
+  model: report
+  slug: reports
+  controller: "reports"
+  read_only: true
+```
+
+```ruby
+# app/controllers/reports_controller.rb
+class ReportsController < ApplicationController
+  include LcpRuby::Controller::PresenterSetup   # for breadcrumbs and nav highlighting
+
+  def index
+    @reports = Report.for_user(current_user).page(params[:page])
+    # Render your own view, not LCP's
+  end
+
+  def show
+    @report = Report.find(params[:id])
+  end
+end
+```
+
+The route appears in the LCP nav (via the `reports` view group/page), permissions are checked against the `reports` permission file, and `current_presenter` is available — but the controller renders your custom views and uses your own data flow.
+
+## Pattern 5: Standalone controller outside LCP
+
+Sometimes you need a controller that lives alongside the LCP app but doesn't participate in the presenter/permission system at all — a documentation viewer, an admin dashboard, an API endpoint for a third-party integration. These controllers don't have an LCP model, presenter, or slug.
+
+### The decision: what to inherit from
+
+| Inherit from | What you get | What you skip | Best for |
+|---|---|---|---|
+| `LcpRuby::ApplicationController` | Engine layout with nav, theme, auth, all 9 concerns | Nothing — you must explicitly skip what you don't need | Controllers that should look like LCP pages |
+| `ApplicationController` + cherry-picked concerns | Your host layout + specific LCP features | Everything not included | Controllers needing some LCP features |
+| `ApplicationController` (no concerns) | Plain Rails, no LCP dependencies | All LCP features | Fully independent pages |
+
+### Example: DocsController (plain ApplicationController)
+
+The showcase app's documentation viewer renders project markdown files. It has no model, no permissions, and should be accessible without login:
+
+```ruby
+class DocsController < ApplicationController
+  layout "docs"  # standalone layout, not LCP engine layout
+
+  DOCS_ROOT = Rails.root.join("..", "..", "docs").freeze
+
+  def show
+    relative = request.path.delete_prefix("/docs/")
+    file = DOCS_ROOT.join("#{relative}.md").cleanpath
+
+    unless file.to_s.start_with?(DOCS_ROOT.to_s) && file.exist?
+      raise ActionController::RoutingError, "Not found"
+    end
+
+    raw = file.read
+    @title = raw.lines.first&.match(/^#+\s*(.+)/)&.captures&.first
+    @html = render_markdown(raw)
+  end
+end
+```
+
+Route (outside engine mount):
+```ruby
+Rails.application.routes.draw do
+  get "docs/*path", to: "docs#show"    # before engine mount
+  mount LcpRuby::Engine => "/showcase"
+end
+```
+
+### Why not inherit from `LcpRuby::ApplicationController`?
+
+It would seem natural to inherit from the engine controller to get the nav and theme. But it pulls in three layers of dependencies:
+
+**Layer 1 — Authentication.** The `Authentication` concern adds a `before_action :authenticate_user!`. With `:built_in` auth, this calls `warden.authenticate(scope: :user)` and redirects unauthenticated users to the login page. You can skip it:
+
+```ruby
+skip_before_action :authenticate_user!
+```
+
+This works because Warden middleware (`Warden::Manager`) only provides the `request.env["warden"]` object — it does **not** block requests on its own. The blocking is done by the controller callback, which `skip_before_action` removes. A common misconception is that Warden middleware rejects unauthenticated requests at the Rack level; it doesn't.
+
+**Layer 2 — Presenter Setup.** The `PresenterSetup` concern resolves the current presenter and model from `:lcp_slug`. Without a slug, it raises `MetadataError`. You must skip it:
+
+```ruby
+skip_before_action :set_presenter_and_model
+skip_before_action :authorize_presenter_access
+```
+
+**Layer 3 — Layout helpers.** The engine layout (`lcp_ruby/application.html.erb`) calls helpers like `menu_layout`, `menu_defined?`, `current_theme_default`, `lcp_ruby.preferences_theme_path`. These are defined by `PresenterSetup` and engine route helpers. Without PresenterSetup, the layout crashes with `NoMethodError`.
+
+So to use the engine layout, you'd need:
+
+```ruby
+class DocsController < LcpRuby::ApplicationController
+  skip_before_action :authenticate_user!
+  skip_before_action :set_presenter_and_model
+  skip_before_action :authorize_presenter_access
+  layout "lcp_ruby/application"  # works only if helpers are stubbed
+
+  helper_method :menu_layout, :menu_defined?
+  def menu_layout = "top"
+  def menu_defined? = true
+end
+```
+
+This is fragile — any new helper the layout uses will break your controller. The standalone layout approach is more robust.
+
+### Making LCP pages public (without a custom controller)
+
+If you want a standard LCP presenter page (not a custom controller) to be accessible without login, use `public: true` on the view group:
+
+```yaml
+# config/lcp_ruby/views/public_catalog.yml
+view_group:
+  model: product
+  primary: public_catalog
+  public: true          # ← skips authentication for this view group
+  views:
+    - presenter: public_catalog
+```
+
+The `Authentication` concern checks `current_request_public?` which looks up the view group's `public?` flag. If true, it sets an anonymous user and proceeds without Warden authentication.
+
+## Using the `lcp_ruby:host_controller` generator
+
+The fastest path to a working controller:
+
+```bash
+# All concerns, all CRUD actions, LCP views
+rails generate lcp_ruby:host_controller orders
+
+# Minimal setup — just nav context, no CRUD logic
+rails generate lcp_ruby:host_controller reports --concerns=setup --actions=index,show
+
+# Wizard controller — only new and create, custom views
+rails generate lcp_ruby:host_controller orders_wizard \
+  --concerns=setup,auth,paths \
+  --actions=new,create \
+  --views=custom
+```
+
+The generator:
+- Auto-resolves concern dependencies transitively (e.g., `--concerns=search` pulls in `PresenterSetup`, `Authentication`, and `Authorization`).
+- Emits includes in the correct topological order.
+- Creates a `permitted_params` skeleton from the presenter's writable fields (or a TODO comment if metadata isn't loadable).
+- Prints a presenter YAML suggestion at the end.
+
+See the [reference](../reference/host-controller-integration.md#generator-lcp_rubyhost_controller) for all options.
+
+## Concern picker — what to include
+
+| Goal | Concerns to include |
+|------|---------------------|
+| Reuse LCP forms and templates fully | `all` |
+| Custom views, but want LCP nav and breadcrumbs | `setup`, `paths`, `views` |
+| Custom views + LCP permissions | `setup`, `auth`, `paths`, `views` |
+| LCP search, but custom queries | `setup`, `auth`, `search`, `paths` |
+| Just need `current_presenter` in the controller | `setup` |
+
+## Testing host controllers
+
+Host controllers test like any Rails controller. To exercise the LCP integration end-to-end, use a request spec:
+
+```ruby
+require "rails_helper"
+
+RSpec.describe CheckoutsController, type: :request do
+  before do
+    sign_in admin_user  # your host auth
+    Rails.application.reload_routes!  # if your test fixtures load presenters dynamically
+  end
+
+  it "renders index via LCP layout" do
+    get "/checkout"
+    expect(response).to have_http_status(:ok)
+  end
+end
+```
+
+If your custom controller includes `LcpRuby::Controller::PresenterSetup`, then `current_presenter`, `current_model_definition`, etc. are all available in the test as well.
+
+## Common pitfalls
+
+**Forgetting to define associations in Ruby on `bind_to:` models.** YAML associations are metadata-only. The host class must declare `belongs_to :department` in Ruby — otherwise `record.department` will raise `NoMethodError`.
+
+**Skipping `Authorization` but using `policy_scope` in the controller.** `policy_scope` comes from the `Authorization` concern (via Pundit). If you skip it, use `@model_class.where(...)` directly.
+
+**Custom views without `--views=custom`.** If you want to render your own templates (not LCP's), generate with `--views=custom`. Otherwise the generator emits `render "lcp_ruby/resources/index"` which expects the LCP view contract (see [reference](../reference/host-controller-integration.md#view-instance-variable-contract)).
+
+**Mismatched concern order.** Each concern checks its dependencies in `included do` and raises a clear error at class load time. If you see `Authorization requires PresenterSetup to be included first`, just reorder your `include` statements.
+
+**Custom controller `controller#action` format.** The validator requires lowercase, snake_case: `"orders/wizard#new"` works, `"Orders::Wizard#New"` does not.
+
+**Thinking Warden middleware blocks unauthenticated requests.** It doesn't. `Warden::Manager` middleware only populates `request.env["warden"]` — it's the `authenticate_user!` controller callback (from `LcpRuby::Controller::Authentication`) that redirects unauthenticated users. `skip_before_action :authenticate_user!` is sufficient to make a controller action public.
+
+**Using engine layout without PresenterSetup.** The engine layout (`lcp_ruby/application.html.erb`) calls helpers defined by the `PresenterSetup` concern: `menu_layout`, `menu_defined?`, `current_theme_default`, etc. If you skip `set_presenter_and_model`, the layout will crash. Either include `PresenterSetup` with a valid slug, stub the helpers, or use your own layout.
+
+**403 Forbidden with empty body in tests.** This is almost never Warden/Devise — it's `ActionDispatch::HostAuthorization` (Rails middleware) rejecting requests without a valid `Host` header. Warden redirects (302) or returns 401 — it never returns 403 + empty body. Fix: set `app.host! "localhost"` in integration tests, or `host! "localhost"` in request specs. See the [debugging guide](debugging/controllers.md#mysterious-403-from-actiondispatchhostauthorization) for details.
+
+## Related references
+
+- [Host Controller Integration Reference](../reference/host-controller-integration.md) — Full attribute and concern reference
+- [Permissions Reference](../reference/permissions.md) — Configuring CRUD, field-level, and scope permissions
+- [Presenter DSL Reference](../reference/presenter-dsl.md) — Ruby DSL alternative to YAML
+- [Architecture](../architecture.md) — Internal request flow and module structure

data/docs/guides/impersonation.md

@@ -0,0 +1,83 @@
+# Impersonation ("View as Role X")
+
+Impersonation allows authorized users (e.g., admins) to view the application as if they had a different role, without changing their actual identity. This is useful for testing permissions, debugging access issues, and verifying what other roles see.
+
+## Setup
+
+Impersonation is controlled by two settings: `impersonator_roles` (who can impersonate) and `impersonatable_roles` (which target roles appear in the dropdown).
+
+```ruby
+# config/initializers/lcp_ruby.rb
+LcpRuby.configure do |config|
+  config.impersonator_roles = ["admin"]
+end
+```
+
+Only users whose real role includes one of the listed `impersonator_roles` can activate impersonation. When the list is empty (default), impersonation is disabled entirely.
+
+By default the dropdown lists every role found across permission files. To restrict the targets — for example to hide internal roles like `service_account` — set `impersonatable_roles` to an explicit whitelist:
+
+```ruby
+LcpRuby.configure do |config|
+  config.impersonator_roles    = ["admin"]
+  config.impersonatable_roles  = ["viewer", "editor", "manager"]  # nil = "all"
+end
+```
+
+> **Deprecated:** `config.impersonation_roles = …` still works as an alias for `impersonator_roles` (with a deprecation warning). New code should use the explicit names.
+
+## How It Works
+
+1. **Activation:** An authorized user selects a role from the "View as" dropdown in the navigation bar, or sends a POST request to `/impersonate` with `role` parameter.
+
+2. **Effect:** The permission system evaluates all access checks using the impersonated role instead of the user's real role. This affects:
+   - Presenter access (which pages are visible)
+   - CRUD permissions
+   - Field-level access (readable/writable fields)
+   - Custom action availability
+   - Row-level scopes
+   - Menu filtering
+
+3. **Identity preserved:** The user's real identity is never changed. Only the role used for permission evaluation is overridden. Audit logs still record the real user.
+
+4. **Deactivation:** Click "Stop impersonation" in the yellow banner, or send a DELETE request to `/impersonate`.
+
+## UI Elements
+
+When impersonation is available but not active, a "View as" dropdown appears in the navigation bar listing all roles defined across permission files. Selecting a role and clicking "Impersonate" activates impersonation.
+
+When impersonation is active, a yellow banner appears at the top of every page showing:
+- The impersonated role name
+- A "Stop impersonation" button
+
+## Routes
+
+The engine adds two routes for impersonation:
+
+| Method | Path | Action |
+|--------|------|--------|
+| POST | `/impersonate` | Set impersonation (param: `role`) |
+| DELETE | `/impersonate` | Clear impersonation |
+
+Both routes redirect back to the root path with a flash message.
+
+## Security
+
+- Only users with a real role in `config.impersonator_roles` can impersonate
+- The real user identity is never changed — only the permission evaluator's role is overridden
+- All authorization still runs server-side via Pundit
+- If a user impersonates a role that cannot access the current page, they are redirected with an access denied message
+- Impersonation state is stored in the session (`session[:lcp_impersonate_role]`)
+
+## Example
+
+```ruby
+# config/initializers/lcp_ruby.rb
+LcpRuby.configure do |config|
+  config.impersonator_roles = ["admin", "super_admin"]
+end
+```
+
+With this configuration, users with the `admin` or `super_admin` role can impersonate any other role. A `viewer` or `sales_rep` user will not see the impersonation controls.
+
+Source: `app/controllers/lcp_ruby/impersonation_controller.rb`, `lib/lcp_ruby/authorization/impersonated_user.rb`, `lib/lcp_ruby/configuration.rb`