plutonium 0.23.4 → 0.23.5

data/docs/modules/generator.md

@@ -0,0 +1,288 @@
+---
+title: Generator Module
+---
+
+# Generator Module
+
+The Generator module provides comprehensive code generation and scaffolding capabilities for Plutonium applications. It offers a suite of Rails generators that automate the creation of packages, resources, authentication setups, and other common development patterns.
+
+::: tip
+The Generator module is located in `lib/generators/pu/`.
+:::
+
+## Overview
+
+- **Code Scaffolding**: Automated generation of models, controllers, policies, and definitions.
+- **Package Creation**: Portal and feature package generators with proper structure.
+- **Resource Management**: Complete resource scaffolding with CRUD operations.
+- **Authentication Setup**: Rodauth integration with multi-account support.
+- **Interactive CLI**: TTY-powered interactive prompts for generator options.
+
+## Core Generators
+
+### Installation Generator (`pu:core:install`)
+
+Sets up the base requirements for a Plutonium application.
+
+::: code-group
+```bash [Command]
+rails generate pu:core:install
+```
+```text [Generated Structure]
+config/
+├── packages.rb          # Package loading configuration
+└── initializers/
+    └── plutonium.rb     # Plutonium configuration
+
+packages/                # Package directory
+└── .keep
+
+app/
+├── controllers/
+│   ├── application_controller.rb    # Enhanced with Plutonium
+│   ├── plutonium_controller.rb      # Base Plutonium controller
+│   └── resource_controller.rb       # Resource CRUD controller
+└── models/
+    └── application_record.rb        # Enhanced with Plutonium::Resource::Record
+
+app/views/
+└── layouts/
+    └── resource.html.erb            # Ejected layout for customization
+```
+:::
+
+### Package Generators
+
+#### Portal Generator (`pu:pkg:portal`)
+
+Creates a complete portal package, which acts as a user-facing entry point to your application, often with its own authentication.
+
+::: code-group
+```bash [Command]
+# Creates an "admin" portal with authentication
+rails generate pu:pkg:portal admin
+
+# Creates a "customer" portal with public access
+rails generate pu:pkg:portal customer --public
+```
+```text [Generated Structure]
+packages/admin_portal/
+├── lib/
+│   └── engine.rb                    # Portal engine with entity scoping
+├── config/
+│   └── routes.rb                    # Portal-specific routes
+└── app/
+    ├── controllers/
+    │   └── admin_portal/
+    │       ├── concerns/controller.rb # Portal controller concern
+    │       ├── plutonium_controller.rb
+    │       ├── resource_controller.rb
+    │       └── dashboard_controller.rb
+    ├── policies/
+    │   └── admin_portal/
+    └── definitions/
+        └── admin_portal/
+```
+```ruby [Authentication Integration]
+# Automatic Rodauth integration is added to the controller concern
+# packages/admin_portal/app/controllers/admin_portal/concerns/controller.rb
+
+module AdminPortal
+  module Concerns
+    module Controller
+      extend ActiveSupport::Concern
+      include Plutonium::Portal::Controller
+      # Generated based on generator selection (e.g., :admin)
+      include Plutonium::Auth::Rodauth(:admin)
+    end
+  end
+end
+```
+:::
+
+#### Package Generator (`pu:pkg:package`)
+
+Creates a standard feature package for encapsulating domain logic.
+
+::: code-group
+```bash [Command]
+rails generate pu:pkg:package blogging
+```
+```text [Generated Structure]
+packages/blogging/
+├── lib/
+│   └── engine.rb        # Package engine
+└── app/
+    ├── models/
+    │   └── blogging/
+    ├── controllers/
+    │   └── blogging/
+    ├── policies/
+    │   └── blogging/
+    ├── definitions/
+    │   └── blogging/
+    └── interactions/
+        └── blogging/
+```
+:::
+
+### Resource Generators
+
+#### Scaffold Generator (`pu:res:scaffold`)
+
+Creates a complete resource with a model, controller, policy, and definition, including full CRUD operations.
+
+::: code-group
+```bash [Command]
+# Generate a new resource with attributes, placing it in the 'blogging' package
+rails generate pu:res:scaffold Post title:string content:text author:references published:boolean --dest=blogging
+```
+```ruby [Generated Model]
+# packages/blogging/app/models/blogging/post.rb
+class Blogging::Post < Blogging::ResourceRecord
+  belongs_to :author, class_name: 'UserManagement::User'
+
+  validates :title, presence: true
+  validates :content, presence: true
+end
+```
+```ruby [Generated Policy]
+# packages/blogging/app/policies/blogging/post_policy.rb
+class Blogging::PostPolicy < Blogging B::ResourcePolicy
+  def create?
+    user.present?
+  end
+
+  def update?
+    user == record.author
+  end
+end
+```
+```ruby [Generated Definition]
+# packages/blogging/app/definitions/blogging/post_definition.rb
+class Blogging::PostDefinition < Blogging::ResourceDefinition
+  # Display configuration
+  display :title, :author, :published, :created_at
+
+  # Search configuration
+  search :title, :content
+
+  # Filter configuration
+  filter :published, with: :boolean
+  filter :author, with: :select
+end
+```
+:::
+
+### Authentication Generators
+
+#### Rodauth Account Generator (`pu:rodauth:account`)
+
+Generates the necessary files for a Rodauth authentication setup for a given account type.
+
+::: code-group
+```bash [Command]
+# Generate a 'user' account with common features
+rails generate pu:rodauth:account user --features login logout create-account verify-account reset-password remember
+```
+```text [Generated Structure]
+app/
+├── controllers/
+│   └── rodauth/
+│       └── user_controller.rb
+├── mailers/
+│   └── user_mailer.rb
+├── models/
+│   └── user.rb
+└── rodauth/
+    ├── user_rodauth.rb
+    └── user_rodauth_plugin.rb
+db/
+└── migrate/
+    └── ..._create_users.rb
+```
+:::
+
+#### Rodauth Admin Generator (`pu:rodauth:admin`)
+
+A specialized generator for creating a secure admin account with enhanced features like MFA and audit logging.
+
+::: code-group
+```bash [Command]
+rails generate pu:rodauth:admin admin
+```
+```ruby [Generated Plugin]
+# app/rodauth/admin_rodauth_plugin.rb
+class AdminRodauthPlugin < RodauthPlugin
+  configure do
+    enable :login, :logout, :remember,
+           :otp, :recovery_codes, :lockout,
+           :active_sessions, :audit_logging,
+           :password_grace_period, :internal_request
+
+    # ... and other secure defaults
+  end
+end
+```
+:::
+
+### Ejection Generators
+
+#### Layout Ejection (`pu:eject:layout`)
+
+Ejects Plutonium layouts for customization:
+
+```bash
+rails generate pu:eject:layout --dest=admin_portal
+```
+
+#### Shell Ejection (`pu:eject:shell`)
+
+Ejects shell components and assets:
+
+```bash
+rails generate pu:eject:shell --dest=admin_portal
+```
+
+## Generator Configuration
+
+### Interactive Mode
+
+Many generators support interactive prompts:
+
+```bash
+# Interactive package selection
+rails generate pu:res:scaffold Post title:string
+# Prompts: "Select destination feature: [blogging, user_management, main_app]"
+
+# Non-interactive mode
+rails generate pu:res:scaffold Post title:string --dest=blogging
+```
+
+## Development Workflow Integration
+
+### IDE Integration
+
+Add generator shortcuts to your IDE:
+
+```json
+// .vscode/tasks.json
+{
+  "tasks": [
+    {
+      "label": "Generate Resource",
+      "type": "shell",
+      "command": "rails generate pu:res:scaffold ${input:resourceName}",
+      "group": "build"
+    },
+    {
+      "label": "Generate Portal",
+      "type": "shell",
+      "command": "rails generate pu:pkg:portal ${input:portalName}",
+      "group": "build"
+    }
+  ]
+}
+```
+
+The Generator module provides a comprehensive foundation for rapid application development with Plutonium, automating repetitive tasks while maintaining flexibility and customization options.

data/docs/modules/index.md

@@ -0,0 +1,167 @@
+---
+title: Plutonium Modules
+---
+
+# Plutonium Modules
+
+Plutonium is built as a collection of focused, interconnected modules that extend Rails with powerful conventions and capabilities. Each module tackles a specific aspect of application development—from managing data and business logic to creating beautiful user interfaces.
+
+This modular design means you can learn and use only what you need, while still benefiting from the seamless integration across the entire framework.
+
+---
+
+## Architecture Modules
+The foundational components that structure and organize your Plutonium application.
+
+<div class="grid grid-cols-1 md:grid-cols-2 gap-4">
+  <div class="card">
+    <a href="./core" class="block p-4">
+      <h3 class="font-bold">Core Module</h3>
+      <p class="text-sm">The foundation that powers everything—base controllers, essential utilities, and framework integration points.</p>
+    </a>
+  </div>
+  <div class="card">
+    <a href="./controller" class="block p-4">
+      <h3 class="font-bold">Controller Module</h3>
+      <p class="text-sm">Smart HTTP request handling with built-in CRUD operations, authorization, and multi-tenancy support.</p>
+    </a>
+  </div>
+  <div class="card">
+    <a href="./routing" class="block p-4">
+      <h3 class="font-bold">Routing Module</h3>
+      <p class="text-sm">Intelligent resource routing that automatically creates nested routes, handles entity scoping, and manages interactive actions.</p>
+    </a>
+  </div>
+  <div class="card">
+    <a href="./package" class="block p-4">
+      <h3 class="font-bold">Package Module</h3>
+      <p class="text-sm">Organize your application into self-contained, reusable packages using enhanced Rails Engines.</p>
+    </a>
+  </div>
+  <div class="card">
+    <a href="./portal" class="block p-4">
+      <h3 class="font-bold">Portal Module</h3>
+      <p class="text-sm">Create distinct application interfaces for different user types while managing multi-tenancy and access control.</p>
+    </a>
+  </div>
+  <div class="card">
+    <a href="./authentication" class="block p-4">
+      <h3 class="font-bold">Authentication Module</h3>
+      <p class="text-sm">Secure, flexible authentication powered by Rodauth with support for multiple account types and strategies.</p>
+    </a>
+  </div>
+  <div class="card">
+    <a href="./configuration" class="block p-4">
+      <h3 class="font-bold">Configuration Module</h3>
+      <p class="text-sm">Centralized configuration management for customizing every aspect of your Plutonium application.</p>
+    </a>
+  </div>
+</div>
+
+## Business Logic Modules
+The tools for defining your application's data structures, business rules, and operations.
+
+<div class="grid grid-cols-1 md:grid-cols-2 gap-4">
+  <div class="card">
+    <a href="./resource_record" class="block p-4">
+      <h3 class="font-bold">Resource Record Module</h3>
+      <p class="text-sm">The heart of your application—define models, their behavior, and how they interact with the world.</p>
+    </a>
+  </div>
+  <div class="card">
+    <a href="./interaction" class="block p-4">
+      <h3 class="font-bold">Interaction Module</h3>
+      <p class="text-sm">Encapsulate complex business logic into clean, testable, and reusable service objects.</p>
+    </a>
+  </div>
+  <div class="card">
+    <a href="./action" class="block p-4">
+      <h3 class="font-bold">Action Module</h3>
+      <p class="text-sm">Define custom operations that users can perform on resources, with automatic UI generation and routing.</p>
+    </a>
+  </div>
+  <div class="card">
+    <a href="./query" class="block p-4">
+      <h3 class="font-bold">Query Module</h3>
+      <p class="text-sm">Powerful, declarative data querying with built-in filtering, searching, and sorting capabilities.</p>
+    </a>
+  </div>
+  <div class="card">
+    <a href="./policy" class="block p-4">
+      <h3 class="font-bold">Policy Module</h3>
+      <p class="text-sm">Comprehensive authorization and access control built on the robust Action Policy framework.</p>
+    </a>
+  </div>
+</div>
+
+## User Interface Modules
+Everything you need to create beautiful, consistent, and functional user interfaces.
+
+<div class="grid grid-cols-1 md:grid-cols-2 gap-4">
+  <div class="card">
+    <a href="./ui" class="block p-4">
+      <h3 class="font-bold">UI Module</h3>
+      <p class="text-sm">The foundation for all UI components, providing core rendering logic and display patterns.</p>
+    </a>
+  </div>
+  <div class="card">
+    <a href="./display" class="block p-4">
+      <h3 class="font-bold">Display Module</h3>
+      <p class="text-sm">Rich components for presenting data in various formats—from simple text to complex visualizations.</p>
+    </a>
+  </div>
+  <div class="card">
+    <a href="./form" class="block p-4">
+      <h3 class="font-bold">Form Module</h3>
+      <p class="text-sm">Powerful form builder with automatic field generation, validation handling, and complex input types.</p>
+    </a>
+  </div>
+  <div class="card">
+    <a href="./table" class="block p-4">
+      <h3 class="font-bold">Table Module</h3>
+      <p class="text-sm">Feature-rich data tables with sorting, filtering, pagination, and bulk operations out of the box.</p>
+    </a>
+  </div>
+</div>
+
+## Development & Tooling Modules
+Accelerate your development workflow with powerful generators and utilities.
+
+<div class="grid grid-cols-1 md:grid-cols-2 gap-4">
+  <div class="card">
+    <a href="./generator" class="block p-4">
+      <h3 class="font-bold">Generator Module</h3>
+      <p class="text-sm">Comprehensive code generators for scaffolding every component of your Plutonium application.</p>
+    </a>
+  </div>
+  <div class="card">
+    <a href="./helper" class="block p-4">
+      <h3 class="font-bold">Helper Module</h3>
+      <p class="text-sm">A rich collection of view helpers and utilities that simplify template development and UI creation.</p>
+    </a>
+  </div>
+</div>
+
+## Coming Soon
+These modules are actively being developed and will be available in future releases.
+
+<div class="grid grid-cols-1 md:grid-cols-2 gap-4">
+  <div class="card">
+    <div class="p-4">
+      <h3 class="font-bold">Testing Module <span class="text-xs font-mono text-gray-400">In Development</span></h3>
+      <p class="text-sm">Comprehensive testing utilities and patterns specifically designed for Plutonium applications.</p>
+    </div>
+  </div>
+  <div class="card">
+    <div class="p-4">
+      <h3 class="font-bold">Asset Module <span class="text-xs font-mono text-gray-400">In Development</span></h3>
+      <p class="text-sm">Advanced tools for managing assets, dependencies, and the modern JavaScript/CSS pipeline.</p>
+    </div>
+  </div>
+  <div class="card">
+    <div class="p-4">
+      <h3 class="font-bold">Theme Module <span class="text-xs font-mono text-gray-400">In Development</span></h3>
+      <p class="text-sm">A comprehensive theming system for deep customization of your application's look and feel.</p>
+    </div>
+  </div>
+</div>