cccux 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a2c04acd4a7bdb9bf56dd8bec3bff97fa96b47f311d99ad99ecc43f788ea86d2
+  data.tar.gz: 3aa15d6e9ede2db1c97356a67628a7c03f8ecee8b73af4578a86667d023ed0c6
+SHA512:
+  metadata.gz: 67c23f642f404f7b04de4f7f28394d12bb46812fc4f63f126aaa8dea8087257cf353472cb4c9e924d497f381877fb94250144667c3c140eec23cb9f1ab2fc066
+  data.tar.gz: beb6ffdf77cafdfa83dd9e9f55a44c0aa45674c107cd4e24b100588577e337e1c67e0c299dcf839e7e9bef41b6e2f90cad1add1a4bb34fa6ab0914300c5c4972

data/CHANGELOG.md

@@ -0,0 +1,67 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2025-07-07
+
+### Added
+
+#### Core Features
+- **Role-Based Access Control (RBAC)**: Complete RBAC system with Users, Roles, and RoleAbilities models
+- **Admin Interface**: Comprehensive admin controllers for managing users, roles, and permissions
+- **CanCanCan Integration**: Seamless integration with CanCanCan authorization framework
+- **Unified Ownership System**: Simplified ownership model supporting both direct and contextual ownership
+
+#### Models
+- `Cccux::User` - User management with role assignments
+- `Cccux::Role` - Role definition and management
+- `Cccux::RoleAbility` - Permission configuration with flexible ownership patterns
+- `Cccux::UserRole` - Join table for user-role associations
+
+#### Controllers
+- `Cccux::UsersController` - User management interface
+- `Cccux::RolesController` - Role creation and editing
+- `Cccux::RoleAbilitiesController` - Permission configuration interface
+- `Cccux::ApplicationControllerConcern` - Authorization concern for host applications
+
+#### Setup and Configuration
+- **Automated Setup Task**: `rails cccux:setup` for one-command installation
+- **Status Task**: `rails cccux:status` for configuration verification
+- **View Conversion Tool**: `rails cccux:convert_views[directory]` for automated view helper conversion
+- **ApplicationController Integration**: Automatic configuration of authorization concerns
+
+#### View Helpers
+- `link_if_can_show` - Conditional show links based on permissions
+- `link_if_can_edit` - Conditional edit links based on permissions
+- `link_if_can_create` - Conditional create links based on permissions
+- `button_if_can_destroy` - Conditional delete buttons based on permissions
+- Support for nested resource routes and complex authorization patterns
+
+#### Authorization Features
+- **Flexible Ownership Configuration**: Support for multiple ownership patterns via UI
+- **Contextual Permissions**: Users can have permissions within specific contexts (e.g., store managers)
+- **Fallback Mechanisms**: Multiple ownership detection methods (custom `owned_by?`, `user_id`, `creator_id`)
+- **Security by Default**: Deny access when no permissions are configured
+
+#### Documentation
+- Comprehensive README with setup instructions and examples
+- Unified Ownership Guide explaining the simplified permission model
+- Generators documentation for scaffolding
+- Controller setup examples and best practices
+
+### Technical Details
+- **Rails Compatibility**: Supports Rails 7.1+ 
+- **Ruby Compatibility**: Requires Ruby 3.0+
+- **Database Agnostic**: Works with any Rails-supported database
+- **Engine Architecture**: Implemented as a Rails engine for easy integration
+- **Zeitwerk Compatible**: Fully compatible with Rails' autoloading system
+
+### Migration Path
+- Automatic migration from complex contextual/owned permission types to unified "owned" type
+- Backward compatibility maintained during transition period
+- Clear upgrade path for existing installations
+
+[0.1.0]: https://github.com/bagus1/cccux/releases/tag/v0.1.0 

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright Bagus1
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,382 @@
+# CCCUX - Simplified Role-Based Authorization Engine
+
+CCCUX is a Rails engine that provides comprehensive role-based authorization with CanCanCan integration. It's designed to be **incredibly simple** - just add one line to your controllers and configure permissions through the web interface.
+
+## Features
+
+- **One-Line Controller Setup**: Just add `load_and_authorize_resource` to any controller
+- **No Model Code Required**: Models need no special concerns or methods
+- **UI-Driven Configuration**: Set up complex ownership patterns through the web interface
+- **Automatic Setup**: Configures your ApplicationController automatically
+- **CanCanCan Integration**: Built on the proven CanCanCan authorization library
+- **Flexible Ownership**: Handle simple user ownership or complex manager hierarchies
+- **Admin Interface**: Clean, intuitive interface for role and permission management
+- **Rails 8 Compatible**: Works with Rails 8 and modern Rails applications
+
+## Quick Start
+
+### 1. Install the Engine
+
+Add to your Gemfile:
+```ruby
+gem 'cccux', path: 'path/to/cccux'
+```
+
+Run:
+```bash
+bundle install
+```
+
+### 2. Run the Setup Task
+
+```bash
+rails cccux:setup
+```
+
+**What the setup task does:**
+
+1. **Checks for Devise**: Verifies Devise is installed, guides you through installation if needed
+2. **Mounts the Engine**: Adds `mount Cccux::Engine => '/cccux'` to your routes
+3. **Configures ApplicationController**: Automatically adds the CCCUX authorization concern to your ApplicationController
+4. **Creates Database Tables**: Runs migrations for roles, permissions, and user assignments
+5. **Seeds Default Data**: Creates default roles (Guest, Basic User, Role Manager, Administrator)
+6. **Creates Admin User**: Sets up a "Role Manager" user account for admin access
+
+The setup task automatically configures your `ApplicationController` with:
+- CanCanCan integration
+- CCCUX Ability class
+- Error handling for authorization failures
+- View helpers for authorization checks
+
+### 3. Add Authorization to Controllers
+
+**The only requirement: Add `load_and_authorize_resource` to your controllers**
+
+#### Basic Controller
+```ruby
+class ProductsController < ApplicationController
+  load_and_authorize_resource
+  
+  def index
+    @products = @products.order(:name)
+  end
+  
+  def show
+    # @product is automatically loaded and authorized
+  end
+end
+```
+
+#### Nested Resource Controller
+```ruby
+class OrdersController < ApplicationController
+  # Load parent resource when present
+  load_and_authorize_resource :store, if: -> { params[:store_id].present? }
+  
+  # Load main resource through parent or directly
+  load_and_authorize_resource :order, through: :store, if: -> { params[:store_id].present? }
+  load_and_authorize_resource :order, unless: -> { params[:store_id].present? }
+  
+  def index
+    if params[:store_id].present?
+      @orders = @store.orders.order(:created_at)
+    else
+      @orders = @orders.order(:created_at)
+    end
+  end
+end
+```
+
+### 4. Configure Permissions
+
+Start your server and navigate to `http://localhost:3000/cccux`:
+
+1. **Model Discovery**: Click "Model Discovery" to automatically detect your models and create permissions
+2. **Roles Management**: Go to "Roles" to see default roles and create custom ones
+3. **Assign Permissions**: Configure which roles can perform which actions on your models
+
+## Permission Configuration
+
+CCCUX supports two access types:
+
+### Global Access
+- **What it does**: Access to all records everywhere
+- **Use case**: Administrators, managers with broad access
+- **Configuration**: Select "Global" access type
+
+### Owned Access
+- **What it does**: Access to records you own or have access to via relationships
+- **Use case**: Users editing their own records, managers accessing records in their scope
+- **Configuration**: Select "Owned" access type and configure ownership settings
+
+## Ownership Configuration Examples
+
+### Simple User Ownership
+**Scenario**: Users can only edit products they created
+
+- **Access Type**: Owned
+- **Ownership Model**: (leave blank)
+- **Foreign Key**: (leave blank - auto-detects `user_id`)
+- **User Key**: (leave blank - defaults to `user_id`)
+
+### Manager Ownership
+**Scenario**: Store managers can edit all orders in stores they manage
+
+- **Access Type**: Owned
+- **Ownership Model**: `StoreManager`
+- **Foreign Key**: `store_id`
+- **User Key**: `user_id`
+
+This configuration tells CCCUX: "Find all StoreManager records where user_id matches the current user, get their store_id values, and allow access to orders with those store_id values."
+
+### Complex Hierarchies
+**Scenario**: Regional managers can edit products in all stores in their region
+
+- **Access Type**: Owned
+- **Ownership Model**: `RegionalManager`
+- **Foreign Key**: `region_id`
+- **User Key**: `user_id`
+
+## Model Requirements
+
+**Models need NO special code!** CCCUX works with standard Rails models:
+
+```ruby
+class Order < ApplicationRecord
+  belongs_to :store
+  belongs_to :user
+  # That's it! No concerns, no special methods needed
+end
+
+class Product < ApplicationRecord
+  belongs_to :user
+  # Works with simple user_id ownership
+end
+
+class Store < ApplicationRecord
+  belongs_to :created_by, class_name: 'User'
+  has_many :store_managers
+  # CCCUX handles complex ownership through configuration
+end
+```
+
+**How it works:**
+- CCCUX automatically detects `user_id` and `creator_id` columns for simple ownership
+- Complex ownership patterns are handled through the UI configuration
+- The CCCUX Ability class dynamically queries your join tables based on your settings
+
+## View Helpers
+
+CCCUX provides convenient view helpers that automatically handle authorization checks:
+
+### Authorization-Aware Helpers
+
+```erb
+<!-- These helpers only render if user has permission -->
+<%= link_if_can_show @product, "View Product", product_path(@product) %>
+<%= link_if_can_edit @product, "Edit Product", edit_product_path(@product) %>
+<%= link_if_can_create Product.new, "New Product", new_product_path %>
+<%= button_if_can_destroy @product, "Delete", product_path(@product), method: :delete %>
+```
+
+### Traditional CanCanCan Helpers
+
+You can also use standard CanCanCan patterns:
+
+```erb
+<% if can? :read, @product %>
+  <%= link_to "View Product", product_path(@product) %>
+<% end %>
+
+<% if can? :update, @product %>
+  <%= link_to "Edit Product", edit_product_path(@product) %>
+<% end %>
+
+<% if can? :create, Product %>
+  <%= link_to "New Product", new_product_path %>
+<% end %>
+
+<% if can? :destroy, @product %>
+  <%= link_to "Delete", product_path(@product), method: :delete, 
+              confirm: "Are you sure?" %>
+<% end %>
+```
+
+### Converting Existing Views
+
+CCCUX includes a development tool to convert existing Rails views to use authorization helpers:
+
+```bash
+# Convert all views in a directory
+rails cccux:convert_views[app/views/products]
+rails cccux:convert_views[app/views/stores]
+
+# See conversion examples
+rails cccux:view_examples
+```
+
+**What it converts:**
+- `link_to` patterns → `link_if_can_show`, `link_if_can_edit`
+- `button_to` delete patterns → `button_if_can_destroy`  
+- "New" links → `link_if_can_create`
+- Complex nested conditionals → context-aware helpers
+- Handles nested resource routes automatically
+
+**Example conversion:**
+```erb
+<!-- BEFORE -->
+<% if @project %>
+  <%= link_to "Edit Task", edit_project_task_path(@project, @task) %>
+<% else %>
+  <%= link_to "Edit Task", edit_task_path(@task) %>
+<% end %>
+
+<!-- AFTER -->
+<%= link_if_can_edit @task, "Edit Task", @project ? edit_project_task_path(@project, @task) : edit_task_path(@task) %>
+```
+
+This conversion tool saves significant time when adding CCCUX to existing applications.
+
+## Admin Interface
+
+Navigate to `/cccux` to access the admin interface:
+
+- **Dashboard**: Overview of roles, users, and permissions
+- **Roles**: Create and manage roles with drag-and-drop priority ordering
+- **Permissions**: View and create permissions for your models
+- **Users**: Assign roles to users
+- **Model Discovery**: Automatically detect new models and create permissions
+
+## Error Handling
+
+CCCUX automatically handles authorization errors:
+
+- **Access Denied**: Redirects to root path with appropriate error message
+- **Record Not Found**: Handles missing records gracefully
+- **Admin Access**: Restricts admin interface to Role Managers only
+
+## Testing
+
+Test your authorization with standard Rails testing:
+
+```ruby
+class ProductsControllerTest < ActionDispatch::IntegrationTest
+  setup do
+    @user = users(:one)
+    @product = products(:one)
+    sign_in @user
+  end
+
+  test "should get index when authorized" do
+    @user.add_role('Basic User')
+    get products_url
+    assert_response :success
+  end
+
+  test "should deny access when not authorized" do
+    get products_url
+    assert_redirected_to root_path
+  end
+end
+```
+
+## Advanced Usage
+
+### Custom Ability Logic
+
+If you need custom authorization logic, you can override the `current_ability` method in your controller:
+
+```ruby
+class ProductsController < ApplicationController
+  load_and_authorize_resource
+  
+  private
+  
+  def current_ability
+    # Add custom context for complex scenarios
+    context = {}
+    context[:store_id] = params[:store_id] if params[:store_id]
+    @current_ability ||= Cccux::Ability.new(current_user, context)
+  end
+end
+```
+
+### Multiple Role Assignment
+
+Users can have multiple roles, and permissions are cumulative:
+
+```ruby
+user.add_role('Basic User')
+user.add_role('Store Manager')
+user.roles # => ['Basic User', 'Store Manager']
+```
+
+### Checking Roles in Code
+
+```ruby
+current_user.has_role?('Role Manager')  # => true/false
+current_user.roles                      # => ['Basic User', 'Store Manager']
+```
+
+## Setup Task Details
+
+The `rails cccux:setup` task performs these steps:
+
+1. **Devise Check**: Ensures Devise is installed and configured
+2. **Route Mounting**: Adds CCCUX routes to your application
+3. **ApplicationController Configuration**: Automatically adds the CCCUX concern
+4. **Database Setup**: Creates all necessary tables and indexes
+5. **Default Data**: Seeds roles, permissions, and creates admin user
+6. **Status Verification**: Confirms all components are properly configured
+
+The setup task is idempotent - you can run it multiple times safely.
+
+## Why CCCUX is Simple
+
+Traditional authorization solutions require:
+- Complex model concerns and methods
+- Manual ability class configuration
+- Custom ownership logic in every model
+- Lots of boilerplate code
+
+**CCCUX eliminates all of this:**
+- ✅ One line per controller: `load_and_authorize_resource`
+- ✅ No model code required
+- ✅ UI-driven configuration
+- ✅ Automatic setup and integration
+- ✅ Works with standard Rails patterns
+
+## Troubleshooting
+
+### Common Issues
+
+**"Access denied" for everything:**
+- Check that your models have been discovered (visit `/cccux/permissions`)
+- Verify user has appropriate roles assigned
+- Ensure permissions are configured for the role
+
+**Controllers not authorizing:**
+- Make sure `load_and_authorize_resource` is added to the controller
+- Check that the setup task configured your ApplicationController
+
+**Complex ownership not working:**
+- Verify ownership model, foreign key, and user key are correct
+- Check that the join table exists and has the expected columns
+- Test the ownership configuration in the Rails console
+
+### Getting Help
+
+1. Check the `/cccux/status` page for configuration issues
+2. Review the Rails logs for authorization errors
+3. Use the Rails console to test permissions: `current_user.can?(:read, Product)`
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes with tests
+4. Submit a pull request
+
+## License
+
+This project is licensed under the MIT License.

data/Rakefile

@@ -0,0 +1,8 @@
+require "bundler/setup"
+
+APP_RAKEFILE = File.expand_path("test/dummy/Rakefile", __dir__)
+load "rails/tasks/engine.rake"
+
+load "rails/tasks/statistics.rake"
+
+require "bundler/gem_tasks"

data/app/assets/config/cccux_manifest.js

@@ -0,0 +1 @@
+//= link_directory ../stylesheets/cccux .css

data/app/assets/stylesheets/cccux/application.css

@@ -0,0 +1,102 @@
+/*
+ * This is a manifest file that'll be compiled into application.css, which will include all the files
+ * listed below.
+ *
+ * Any CSS and SCSS file within this directory, lib/assets/stylesheets, vendor/assets/stylesheets,
+ * or any plugin's vendor/assets/stylesheets directory can be referenced here using a relative path.
+ *
+ * You're free to add application-wide styles to this file and they'll appear at the bottom of the
+ * compiled file so the styles you add here take precedence over styles defined in any other CSS/SCSS
+ * files in this directory. Styles in this file should be added after the last require_* statement.
+ * It is generally better to create a new file per style scope.
+ *
+ *= require_tree .
+ *= require_self
+ */
+
+/* Action Button Styles */
+.cccux-btn {
+    padding: 0.375rem 0.75rem;
+    text-decoration: none;
+    border-radius: 4px;
+    font-size: 0.875rem;
+    border: none;
+    cursor: pointer;
+    display: inline-block;
+    text-align: center;
+}
+
+.cccux-btn-view {
+    background: #17a2b8;
+    color: white;
+}
+
+.cccux-btn-view:hover {
+    background: #138496;
+    color: white;
+    text-decoration: none;
+}
+
+.cccux-btn-edit {
+    background: #ffc107;
+    color: #212529;
+}
+
+.cccux-btn-edit:hover {
+    background: #e0a800;
+    color: #212529;
+    text-decoration: none;
+}
+
+.cccux-btn-delete {
+    background: #dc3545;
+    color: white;
+}
+
+.cccux-btn-delete:hover {
+    background: #c82333;
+    color: white;
+}
+
+.cccux-btn-create {
+    background: #007bff;
+    color: white;
+    padding: 0.75rem 1.5rem;
+    font-weight: bold;
+    border-radius: 6px;
+}
+
+.cccux-btn-create:hover {
+    background: #0056b3;
+    color: white;
+    text-decoration: none;
+}
+
+/* Button Group Utilities */
+.cccux-btn-group {
+    display: flex;
+    gap: 0.5rem;
+}
+
+.cccux-btn-group-center {
+    display: flex;
+    gap: 0.5rem;
+    justify-content: center;
+}
+
+.cccux-btn-group-end {
+    display: flex;
+    gap: 0.5rem;
+    justify-content: flex-end;
+}
+
+/* Size Variants */
+.cccux-btn-sm {
+    padding: 0.25rem 0.5rem;
+    font-size: 0.75rem;
+}
+
+.cccux-btn-lg {
+    padding: 0.75rem 1.5rem;
+    font-size: 1rem;
+}