multitenancy-rails 0.0.2

data/docs/api.md

@@ -0,0 +1,130 @@
+# API Reference
+
+## `Multitenancy` (module)
+
+| Method | Description |
+|--------|-------------|
+| `Multitenancy.root` | Rails application root. |
+| `Multitenancy.themes_root` | Path to `themes/` directory. |
+| `Multitenancy.themes` | Array of `Theme` instances, one per `themes/<name>/` directory. Memoized. |
+| `Multitenancy.reset!` | Clear memoized themes. Useful in tests. |
+| `Multitenancy.config` | Global `Config` instance. |
+
+Themes are discovered lazily on first access to `.themes` — at Rails boot time they're bootstrapped from the Railtie.
+
+## `Multitenancy::Config`
+
+| Attribute | Default | Purpose |
+|-----------|---------|---------|
+| `paths` | 20+ standard Rails paths | Autoload directories to register per theme. |
+
+Default `paths`:
+
+```ruby
+%w[
+  app/controllers app/channels app/helpers app/services app/structs
+  app/models app/mailers app/presenters app/decorators app/queries
+  app/resources app/serializers app/transformers app/validators
+  app/workers app/jobs app/notifications app/policies lib
+]
+```
+
+Customize in an initializer:
+
+```ruby
+Multitenancy.config.paths = %w[app/controllers app/models lib]
+```
+
+## `Multitenancy::Theme`
+
+Represents one theme directory.
+
+| Method | Description |
+|--------|-------------|
+| `#name` | Theme name (basename of the directory). |
+| `#path` | `Pathname` to the theme's root. |
+| `#namespace` | The dynamically-created `Themes::<Name>` module. |
+| `#engine` | The dynamically-created `Themes::<Name>::Engine` class. |
+| `#bootstrap(app)` | Creates the namespace, builds the engine, registers paths. Called by the Railtie. |
+
+You rarely construct `Theme`s yourself — iterate `Multitenancy.themes` instead.
+
+## `Multitenancy::Controller`
+
+`ActiveSupport::Concern`. Include in theme application controllers.
+
+```ruby
+# themes/storefront/app/controllers/application_controller.rb
+module Themes::Storefront
+  class ApplicationController < ::ApplicationController
+    include Multitenancy::Controller
+  end
+end
+```
+
+Configures:
+
+- `prepend_view_path engine.root.join('app/views')` — theme views win.
+- `layout 'application'` — use the theme's layout.
+- `before_action { engine.importmap_reloader&.execute_if_updated }` — reload on JS changes in dev.
+
+### Private: `_prefixes`
+
+Overridden to strip the theme namespace prefix from `controller_path`, so view lookup works naturally:
+
+```
+Themes::Storefront::HomeController → home/index  (not themes/storefront/home/index)
+```
+
+## `Multitenancy::Stim`
+
+Internal — the mixin included into each theme's engine class. It configures:
+
+- `isolate_namespace`
+- `called_from` (for `Rails::Engine#root`)
+- `paths["app/views"]`
+- `paths["app/assets"]`
+- `paths["config/locales"]`
+- `paths["app/javascript"]`
+
+You should not need to interact with it directly.
+
+## `Multitenancy::Integrations`
+
+Namespace for optional-gem integrations. Each is a class with a `.call(app)` class method.
+
+| Integration | Guarded by | What it does |
+|-------------|------------|--------------|
+| `Rails` | always | Bootstraps every theme (creates namespace, engine, path registration). |
+| `FactoryBot` | `defined?(::FactoryBot)` | Adds each theme's `spec/factories/` to FactoryBot's paths. |
+| `RSpec` | `defined?(::RSpec)` | Expands `rspec themes/<name>` to `themes/<name>/spec`; auto-discovers all theme specs by default. |
+| `Minitest` | `defined?(::Rails::TestUnit::Runner)` | Same discovery behavior for Minitest. |
+| `Importmap` | `defined?(::Importmap::Map)` | Creates per-theme importmaps; removes theme paths from main app's importmap; wires dev reloader. |
+| `TailwindCss` | `defined?(::Tailwindcss::Commands)` | Discovers theme Tailwind inputs, sets builds dirs, excludes raw inputs from Propshaft. |
+
+## Load hook
+
+An `ActiveSupport.on_load(:multitenancy)` hook fires after bootstrap completes:
+
+```ruby
+# config/initializers/multitenancy_custom.rb
+ActiveSupport.on_load(:multitenancy) do |multitenancy|
+  # multitenancy is the Multitenancy module
+  # Multitenancy.themes is fully populated at this point
+end
+```
+
+## Generator
+
+```bash
+bin/rails generate multitenancy THEME_NAME [--importmap] [--tailwindcss]
+```
+
+See [generator.md](generator.md).
+
+## Rake tasks
+
+- `multitenancy:tailwindcss:build`
+- `multitenancy:tailwindcss:watch`
+
+See [rake-tasks.md](rake-tasks.md).

data/docs/generator.md

@@ -0,0 +1,88 @@
+# Generator
+
+```bash
+bin/rails generate multitenancy THEME_NAME [options]
+```
+
+Scaffolds a new theme under `themes/<theme_name>/` with a minimal but runnable structure.
+
+## Options
+
+| Flag | Adds |
+|------|------|
+| `--importmap` | `app/javascript/<name>/application.js` and a sample Stimulus controller. |
+| `--tailwindcss` | `app/assets/tailwind/<name>/application.css` with a Tailwind v4 `@import` and a default theme block. |
+
+Flags can be combined:
+
+```bash
+bin/rails g multitenancy storefront --importmap --tailwindcss
+```
+
+## What gets created
+
+### Always
+
+```
+themes/<name>/
+├── app/controllers/application_controller.rb
+├── app/controllers/home_controller.rb
+├── app/views/layouts/application.html.erb
+├── app/views/home/index.html.erb
+├── config/routes.rb
+└── config/locales/en.yml
+```
+
+- `ApplicationController` subclasses the main app's `::ApplicationController` and includes `Multitenancy::Controller`.
+- `HomeController` has a single `index` action.
+- `routes.rb` has `root to: 'home#index'`.
+
+### With `--tailwindcss`
+
+```
+themes/<name>/
+└── app/assets/tailwind/<name>/application.css
+```
+
+```css
+@import 'tailwindcss';
+
+@theme {
+  /* design tokens here */
+}
+```
+
+A `bin/rails multitenancy:tailwindcss:build` run compiles this to `themes/<name>/app/assets/builds/<name>/application.css`, and it's hooked into `assets:precompile` so production deploys compile it automatically.
+
+### With `--importmap`
+
+```
+themes/<name>/
+└── app/javascript/<name>/
+    ├── application.js        # Stimulus entrypoint
+    └── controllers/
+        ├── application.js    # Stimulus Application instance
+        ├── hello_controller.js  # Example controller
+        └── index.js             # Eager-register controllers
+```
+
+The theme's layout is wired to draw the theme-scoped importmap and `javascript_importmap_tags` tag:
+
+```erb
+<%= javascript_importmap_tags "<name>/application" %>
+```
+
+In development, changes to JS files trigger the theme's importmap reloader automatically (wired by the `Multitenancy::Controller` concern).
+
+## Prerequisites for flags
+
+- `--tailwindcss` requires `tailwindcss-rails ~> 4.4`. The gem targets Tailwind CSS v4 (CSS-first config).
+- `--importmap` requires `importmap-rails` in your Gemfile.
+
+If a flag's gem isn't present, the generator skips that part silently — but the theme still works, you just won't get the asset/JS scaffolding.
+
+## After generating
+
+1. Mount the theme in `config/routes/multitenancy.rb` (see [getting-started.md](getting-started.md)).
+2. If you used `--tailwindcss`, run `bin/rails multitenancy:tailwindcss:build` once to generate the compiled CSS.
+3. If you used `--importmap`, pin any shared libraries in the theme's layout or in the main `config/importmap.rb`.

data/docs/getting-started.md

@@ -0,0 +1,111 @@
+# Getting Started
+
+## Install
+
+```ruby
+# Gemfile
+gem 'multitenancy-rails'
+```
+
+```bash
+bundle install
+```
+
+## Generate your first theme
+
+```bash
+bin/rails generate multitenancy storefront
+```
+
+Optional flags:
+
+```bash
+bin/rails generate multitenancy storefront --tailwindcss --importmap
+```
+
+The generator creates `themes/storefront/` with a minimal Rails app structure:
+
+```
+themes/storefront/
+├── app/
+│   ├── controllers/application_controller.rb   # includes Multitenancy::Controller
+│   ├── controllers/home_controller.rb
+│   ├── views/layouts/application.html.erb
+│   └── views/home/index.html.erb
+├── config/
+│   ├── routes.rb
+│   └── locales/en.yml
+```
+
+See [generator.md](generator.md) for the full list of flags and what they add.
+
+## Mount your themes
+
+The gem does not mount themes for you — you decide how they reach the request path.
+
+### Path-based
+
+`config/routes.rb`:
+
+```ruby
+Rails.application.routes.draw do
+  draw(:multitenancy)
+  root 'home#index'
+end
+```
+
+`config/routes/multitenancy.rb`:
+
+```ruby
+Multitenancy.themes.each do |theme|
+  mount theme.engine, at: "/#{theme.name}"
+end
+```
+
+`http://localhost:3000/storefront` → `Themes::Storefront::HomeController#index`.
+
+### Subdomain-based
+
+```ruby
+# config/routes/multitenancy.rb
+Multitenancy.themes.each do |theme|
+  constraints subdomain: theme.name do
+    mount theme.engine, at: '/'
+  end
+end
+```
+
+`http://storefront.lvh.me:3000/` → `Themes::Storefront::HomeController#index`.
+
+## Verify
+
+```bash
+bin/rails runner 'pp Multitenancy.themes.map(&:name)'
+# => ["storefront"]
+
+bin/rails server
+```
+
+Visit the mount point — you should see the scaffolded `home/index` view.
+
+## What you get per theme
+
+Each theme is a fully isolated `Rails::Engine`:
+
+- Namespaced under `Themes::<Name>` — classes don't collide with main app
+- Its own view path (prepended to the lookup chain)
+- Its own route namespace
+- Its own `app/assets/` and `app/javascript/` (if importmap enabled)
+- Its own locales (`config/locales/en.yml`)
+- Its own RSpec / Minitest / FactoryBot directories (auto-discovered)
+
+What you **don't** get automatically:
+
+- Database isolation. Every theme talks to the same database. Scope via `tenant_id` columns or schemas yourself if you need that.
+- Request-scoped tenant context. The theme is determined by the mount point, not by runtime lookup. If you need `Current.tenant`, add it as a `before_action`.
+
+## Next steps
+
+- [Themes](themes.md) — anatomy of a theme, namespace rules, view resolution quirks
+- [Integrations](integrations.md) — ES modules, Stimulus, Tailwind v4, spec discovery
+- [API reference](api.md)

data/docs/integrations.md

@@ -0,0 +1,145 @@
+# Integrations
+
+Every integration in this gem is optional and guard-checked: if the underlying gem isn't in your Gemfile, the integration is silently skipped.
+
+## Importmap (`importmap-rails`)
+
+### Per-theme importmaps
+
+Each theme gets its own `Importmap::Map` stored on `theme.engine.importmap`. Theme pins don't leak into the main app, and vice versa.
+
+The integration also removes theme paths from the main app's importmap config so they don't appear in the root importmap twice:
+
+```
+app.config.importmap.paths.delete_if { |p| p.to_s.start_with?(themes_root) }
+```
+
+### Development hot-reload
+
+A `before_action` in `Multitenancy::Controller` calls `engine.importmap_reloader&.execute_if_updated` on each request. When you edit a file under `themes/<name>/app/javascript/`, the theme's importmap is re-drawn — no server restart needed.
+
+### Drawing the importmap in a layout
+
+```erb
+<%# themes/storefront/app/views/layouts/application.html.erb %>
+<%= javascript_importmap_tags "storefront/application" %>
+```
+
+### Pinning packages
+
+Pin inside the theme's `config/importmap.rb` (same DSL as the main app):
+
+```ruby
+# themes/storefront/config/importmap.rb
+pin 'application', preload: true
+pin '@hotwired/stimulus', to: '@hotwired--stimulus.js'
+pin_all_from 'app/javascript/storefront/controllers', under: 'storefront/controllers'
+```
+
+## Tailwind CSS (`tailwindcss-rails`, v4 only)
+
+### Compilation
+
+Each theme has its own input file (`app/assets/tailwind/<name>/application.css`) compiled to its own output (`app/assets/builds/<name>/application.css`). Tailwind input directories are excluded from Propshaft so unprocessed CSS doesn't leak into the asset pipeline.
+
+### Asset precompile hook
+
+```ruby
+Rake::Task['assets:precompile'].enhance(['multitenancy:tailwindcss:build'])
+```
+
+This is wired automatically by the integration — no setup needed.
+
+### Watch mode (dev)
+
+```bash
+bin/rails multitenancy:tailwindcss:watch
+```
+
+Forks a watcher process per theme, traps `Ctrl-C` to clean up children.
+
+See [rake-tasks.md](rake-tasks.md) for task details.
+
+## RSpec (`rspec-rails`)
+
+### Auto-discovery
+
+Running `rspec` with no args discovers every theme's `spec/` directory:
+
+```bash
+bundle exec rspec
+```
+
+### Explicit paths
+
+Passing an explicit directory expands it to include the matching theme's `spec/`:
+
+```bash
+bundle exec rspec themes/storefront
+# Expands to: themes/storefront/spec
+```
+
+### Nested themes
+
+If `storefront` and `storefront-admin` exist, `rspec themes/storefront` runs both. Disambiguate by going one level deeper:
+
+```bash
+bundle exec rspec themes/storefront-admin
+```
+
+## Minitest (`railties` test runner)
+
+Mirrors the RSpec integration. Theme `test/` directories are auto-discovered:
+
+```bash
+bin/rails test
+```
+
+Explicit paths expand the same way:
+
+```bash
+bin/rails test themes/storefront     # runs themes/storefront/test
+```
+
+## FactoryBot (`factory_bot_rails`)
+
+Theme factories under `themes/<name>/spec/factories/` are added to FactoryBot's definition paths automatically. Build, create, and define as usual:
+
+```ruby
+# themes/storefront/spec/factories/products.rb
+FactoryBot.define do
+  factory :storefront_product, class: 'Themes::Storefront::Product' do
+    name { 'Widget' }
+  end
+end
+```
+
+## Writing a custom integration
+
+Follow the pattern used by every built-in integration: a class under `Multitenancy::Integrations::<Name>` with a `.call(app)` method, guarded against optional-gem absence:
+
+```ruby
+# lib/multitenancy/integrations/my_integration.rb
+module Multitenancy::Integrations
+  class MyIntegration
+    def self.call(app)
+      return unless defined?(::SomeGem)
+
+      Multitenancy.themes.each do |theme|
+        # wire up per-theme stuff here
+      end
+    end
+  end
+end
+```
+
+Hook it into the Railtie in your application:
+
+```ruby
+# config/initializers/multitenancy_custom.rb
+ActiveSupport.on_load(:multitenancy) do
+  Multitenancy::Integrations::MyIntegration.call(Rails.application)
+end
+```
+
+The `:multitenancy` load hook fires after every built-in integration has run, so you can safely inspect `Multitenancy.themes` at that point.

data/docs/rake-tasks.md

@@ -0,0 +1,53 @@
+# Rake Tasks
+
+The gem registers tasks under the `multitenancy:` namespace.
+
+## `multitenancy:tailwindcss:build`
+
+Compile Tailwind CSS for every theme.
+
+```bash
+bin/rails multitenancy:tailwindcss:build
+```
+
+- Discovers `themes/<name>/app/assets/tailwind/<name>/application.css` inputs.
+- Writes to `themes/<name>/app/assets/builds/<name>/application.css`.
+- Skips themes without a Tailwind input file.
+- Creates the builds directory if missing (so Propshaft picks up the output).
+
+This task is wired into `assets:precompile`:
+
+```ruby
+Rake::Task['assets:precompile'].enhance(['multitenancy:tailwindcss:build'])
+```
+
+So production deploys compile theme CSS automatically — no additional config.
+
+## `multitenancy:tailwindcss:watch`
+
+Watch mode for development.
+
+```bash
+bin/rails multitenancy:tailwindcss:watch
+```
+
+- Spawns one watcher process per theme.
+- Recompiles on file changes under the theme's Tailwind directory.
+- Traps `SIGINT` / `SIGTERM` to clean up all child PIDs on exit.
+
+Runs in the foreground. Use it alongside `bin/dev` or a separate terminal.
+
+## Prerequisites
+
+Both tasks require `tailwindcss-rails ~> 4.4`. If the gem isn't in your bundle, the tasks are not registered (no error — they just don't exist).
+
+## Troubleshooting
+
+**"Task 'multitenancy:tailwindcss:build' not found"**  
+You're missing `tailwindcss-rails` in your Gemfile. Add it (`gem 'tailwindcss-rails', '~> 4.4'`), `bundle install`, restart.
+
+**Build output not picked up by asset pipeline**  
+The integration excludes `themes/<name>/app/assets/tailwind/` from Propshaft (the raw inputs), but includes `themes/<name>/app/assets/builds/` (the outputs). If you're using Sprockets or Vite, you may need to adjust.
+
+**Themes compile to the same path**  
+Each theme's output is under its own subdirectory (`builds/<theme-name>/application.css`), so collisions are impossible as long as theme directories have distinct names.

data/docs/themes.md

@@ -0,0 +1,159 @@
+# Themes
+
+A theme is a directory under `themes/` that gets bootstrapped into a `Rails::Engine` at boot.
+
+## Anatomy
+
+```
+themes/storefront/
+├── app/
+│   ├── controllers/       # Themes::Storefront::XxxController
+│   ├── models/            # Themes::Storefront::Xxx (optional; main app models are also reachable)
+│   ├── views/             # Resolved first, ahead of main app views
+│   ├── helpers/
+│   ├── services/
+│   ├── jobs/
+│   ├── policies/
+│   ├── assets/
+│   ├── javascript/        # If importmap is enabled
+│   └── ...
+├── config/
+│   ├── routes.rb          # Engine-scoped routes
+│   └── locales/
+├── spec/                  # Auto-discovered by RSpec (if present)
+└── test/                  # Auto-discovered by Minitest (if present)
+```
+
+Only directories that actually exist are registered. You don't need to create empty `app/mailers/` just for the gem to work.
+
+The autoloaded paths by default are:
+
+```
+app/controllers app/channels app/helpers app/services app/structs
+app/models app/mailers app/presenters app/decorators app/queries
+app/resources app/serializers app/transformers app/validators
+app/workers app/jobs app/notifications app/policies lib
+```
+
+Customize in an initializer:
+
+```ruby
+# config/initializers/multitenancy.rb
+Multitenancy.config.paths = %w[app/controllers app/models app/views lib]
+```
+
+## Namespace rules
+
+All Ruby code in a theme lives under `Themes::<Name>`:
+
+```ruby
+# themes/storefront/app/controllers/home_controller.rb
+module Themes::Storefront
+  class HomeController < ApplicationController
+    def index
+      @products = Product.all  # main-app model — no namespacing needed
+    end
+  end
+end
+```
+
+The namespace module is created dynamically at boot. You can rely on it existing:
+
+```ruby
+Themes::Storefront                 # => Themes::Storefront
+Themes::Storefront::Engine         # => Themes::Storefront::Engine
+Themes::Storefront::HomeController # => Themes::Storefront::HomeController
+```
+
+## Engine isolation
+
+Each theme's engine runs through `isolate_namespace(Themes::<Name>)`. That means:
+
+- Routes are scoped (`home_path` in the engine is NOT `Rails.application.routes.url_helpers.home_path`).
+- Helpers don't leak between themes.
+- Generators inside the theme generate into its namespace.
+
+## Controllers
+
+Theme `ApplicationController`s typically include the gem's `Controller` concern:
+
+```ruby
+# themes/storefront/app/controllers/application_controller.rb
+module Themes::Storefront
+  class ApplicationController < ::ApplicationController
+    include Multitenancy::Controller
+  end
+end
+```
+
+The generator does this for you. The concern sets:
+
+- `prepend_view_path` — theme views win over main-app views with the same name.
+- `layout "application"` — uses the theme's `layouts/application.html.erb`.
+- A `before_action` that re-executes the theme's importmap reloader in development when JS files change.
+
+### View resolution quirk
+
+Without the concern, `Themes::Storefront::HomeController` would look up views under `themes/storefront/home/` — a path that doesn't exist, because views are at `home/`. The concern strips the theme namespace prefix from `_prefixes` so view lookup works naturally:
+
+```
+theme module = Themes::Storefront
+controller   = Themes::Storefront::HomeController
+lookup path  = home/  (not themes/storefront/home/)
+```
+
+That means `app/views/home/index.html.erb` inside the theme renders for the index action.
+
+## Models
+
+Shared across themes by default. You can add theme-specific models in `themes/<name>/app/models/`:
+
+```ruby
+# themes/storefront/app/models/product.rb
+module Themes::Storefront
+  class Product < ApplicationRecord
+    self.table_name = 'storefront_products'
+  end
+end
+```
+
+Inside the theme, `Product` means `Themes::Storefront::Product`. To reach the main app's model, use `::Product`.
+
+## Database
+
+All themes share the main app's database connection. If you want per-tenant data, handle it at the model level — a `tenant_id` column plus a default scope, or multiple DB configs in `database.yml` with `connects_to`. The gem doesn't touch this.
+
+## Routes
+
+Each theme's `config/routes.rb` is a standard engine routes file:
+
+```ruby
+# themes/storefront/config/routes.rb
+Themes::Storefront::Engine.routes.draw do
+  root to: 'home#index'
+  resources :products
+end
+```
+
+The main app's `config/routes/multitenancy.rb` decides how each engine gets mounted — see [getting-started.md](getting-started.md).
+
+## Assets & JavaScript
+
+- CSS: each theme has its own `app/assets/` paths registered with Propshaft.
+- JS (importmap): each theme has its own `Importmap::Map` with its own pins, separate from the main app. The `javascript_importmap_tags` helper in the theme's layout draws the theme's importmap.
+- Tailwind: each theme has its own input file and gets its own build output under `app/assets/builds/<theme>/`.
+
+See [integrations.md](integrations.md) for the asset and JS story in detail.
+
+## Locales
+
+`themes/<name>/config/locales/*.yml` is added to `I18n.load_path`. Keys aren't automatically namespaced — if two themes define the same key, the last loaded wins. Scope keys manually if you want them isolated:
+
+```yaml
+# themes/storefront/config/locales/en.yml
+en:
+  themes:
+    storefront:
+      home:
+        title: Welcome to Storefront
+```