tramway 2.0.4.1 → 2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3804eec9b0082cb874e06824d35b7c649aae6ec8389e7713df6fe9137f006370
-  data.tar.gz: 998791faeeb3a3bf0c7b50eb3d971c6ebd47571b4ad06989e3edfc3a8941b139
+  metadata.gz: '08ab219884f2a424e7adce93a5733871510a88193f31a36999994340585a7a34'
+  data.tar.gz: 3fe496c333ffc32c8d1d4aaf979766ed767256f6ba80b86fc9a527edecdf24ec
 SHA512:
-  metadata.gz: 722661f6f48ec385c0661d6d7ec1abe6be3ebeb6caafc2126753fc9ed02bd31fc4ed767b5490b4c1b31c5fd3256c0ead680236ac2870ccbf83164165f465b333
-  data.tar.gz: fed120c6dfc5fcad5010d14777b16632c175a84a903ed1aa346c60053e63eb2e21fb317fb3ed5b7b714bdb06d142ae24c6b95913411f9dbc77b31b1033b02a1f
+  metadata.gz: 3bd350c148342fcc1e199eb94164d548e3732f889ae4a5c843907c4b668e9870285cfc63090b8ce68751b96028a52d0aad41c5d82fe140751ca950f8f40ae36d
+  data.tar.gz: 3cbad4c74dcb1f1418d4ab04f2b4795f2a6c2d39963873e311e69e97db127bd739b07272c70129c56ed0d3c095a1ab180847bcc74579d90681ec1b0a5e859240

data/docs/AGENTS.md

@@ -0,0 +1,162 @@
+# AGENTS.md: Tramway Code Generation Standards
+
+This document guides AI-assisted code generation for Rails applications built with **Tramway**. It is designed for founders, designers, PMs, and engineers who rely on AI tools (ChatGPT/Copilot/etc.) to build maintainable Rails code that fits Tramway’s conventions without a senior engineer reworking everything.
+
+**Core Principle:** Generated code should feel like curated documentation—simple, explicit, and aligned with Tramway’s defaults. Prefer composable ViewComponents, Tailwind-friendly markup, and Rails-native patterns over bespoke architectures.
+
+---
+
+## Project Overview
+
+Tramway extends Rails with:
+- **CRUD** actions that can be configured in `config/initializers/tramway.rb`.
+- **Generators** that wire Tailwind, ViewComponent, and pagination defaults (`bin/rails g tramway:install`).
+- **ViewComponents** for reusable UI pieces.
+- **Tailwind safelist** utilities to keep dynamic classes in the build.
+
+Generated code should:
+- Lean on Rails conventions and Tramway generators instead of hand-rolled setup.
+- Use domain language (e.g., `Participant`, `Dashboard`) over generic terms.
+- Keep logic in the right layer: models for data/validations, controllers for HTTP, components for repeatable UI, views for simple rendering.
+- Be readable without comments; short methods, guard clauses, and clear naming.
+
+---
+
+## Quick Start Workflow (Preferred)
+
+1) **Install Tramway defaults**
+
+```bash
+bin/rails g tramway:install
+```
+
+- The install generator appends missing gems, copies Tailwind safelist config, ensures `app/assets/tailwind/application.css` imports Tailwind, and writes an `AGENTS.md` guide in the project root.
+
+---
+
+## Technology Stack & Gems
+
+Tramway expects and installs:
+- `rails` (7+), `kaminari`, `view_component`, `haml-rails`, `dry-initializer`, `tailwindcss-rails`.
+- Prefer Haml for views unless a component template uses ERB.
+- Keep JavaScript minimal; use Stimulus if needed, avoid SPAs.
+
+Do **not** introduce alternative architectures (contexts/operation gems) unless explicitly requested.
+
+---
+
+## File Structure & Organization
+
+Follow Rails defaults. When extracting logic, namespace under the owning model or component:
+
+```
+app/
+  components/               # ViewComponent classes and templates
+    participants/
+      card_component.rb
+      card_component.html.erb
+  controllers/
+    participants_controller.rb
+  decorators/               # Tramway Decorator pattern
+    participant_decorator.rb
+  forms/                    # Tramway Form pattern
+    participant_form.rb
+  models/
+    participant.rb
+  views/
+    participants/
+      show.html.haml
+config/
+  initializers/
+      tramway.rb              # Tramway configuration
+  tailwind.config.js        # Safelist managed by tramway:install
+```
+
+---
+
+## Rules
+
+- Use Tramway Entities and Tramway actions (index, show, create) by default unless custom behavior is needed. Configure in `config/initializers/tramway.rb`.
+- Normalize input with `normalizes` (from Tramway) for attributes like email, phone, etc.
+- Use Tramway Navbar for navigation
+- Use Tramway Flash for user notifications.
+- Use Tramway Table for tabular data display.
+- Use Tramway Button for buttons.
+- Use `tramway_form_for` and provided inputs in forms.
+- Inherit all components from Tramway::BaseComponent
+
+## Controller Patterns
+
+- Keep actions short and explicit with guard clauses.
+- Delegate heavy lifting to models, jobs, or components.
+- Render components for complex UI rather than partials with logic.
+
+Example:
+```ruby
+class ParticipantsController < ApplicationController
+  def index
+    @participants = tramway_decorate Participant.all.page(params[:page])
+  end
+
+  def new
+    @participant_form = tramway_form Participant.new
+  end
+
+  def create
+    @participant_form = tramway_form Participant.new
+
+    if @participant_form.submit params[:participant]
+      redirect_to participants_path, notice: 'Participant created successfully.'
+    else
+      render :new, status: :unprocessable_entity
+    end
+  end
+
+  def show
+    @participant = tramway_decorate Participant.find(params[:id])
+  end
+
+  def edit
+    @participant_form = tramway_form Participant.find(params[:id])
+  end
+
+  def update
+    @participant_form = tramway_form Participant.find(params[:id])
+
+    if @participant_form.submit params[:participant]
+      redirect_to participant_path(@participant_form), notice: 'Participant updated successfully.'
+    else
+      render :edit, status: :unprocessable_entity
+    end
+  end
+
+  def destroy
+    participant = Participant.find(params[:id])
+    participant.destroy
+
+    redirect_to participants_path, notice: 'Participant deleted successfully.'
+  end
+end
+```
+
+---
+
+## Tailwind Practices
+
+- Keep `config/tailwind.config.js` managed by the generator. If you add dynamic classes, update the `safelist` via the generator template rather than rewriting the config.
+- Add imports to `app/assets/tailwind/application.css`; avoid inline `<style>` blocks.
+
+---
+
+## Configuration
+
+- Use `anyway_config` (installed by Tramway) for configuration, not direct `ENV` reads.
+
+---
+
+## Checklist (Before Shipping)
+
+- [ ] Used Tramway generators instead of manual setup where available.
+- [ ] Controller actions are concise with guard clauses.
+- [ ] Reusable UI is a ViewComponent using Tailwind utilities and accessible semantics.
+- [ ] Tailwind safelist covers dynamic classes.

data/lib/generators/tramway/install/install_generator.rb

@@ -5,54 +5,8 @@ require 'fileutils'
 
 module Tramway
   module Generators
-    # Running `rails generate tramway:install` will invoke this generator
-    #
-    class InstallGenerator < Rails::Generators::Base
-      desc 'Installs Tramway dependencies and Tailwind safelist configuration.'
-
-      def ensure_dependencies
-        missing_dependencies = gem_dependencies.reject do |dependency|
-          gemfile_contains?(dependency[:name])
-        end
-
-        return if missing_dependencies.empty?
-
-        append_to_file 'Gemfile', <<~GEMS
-
-          # Tramway dependencies
-          #{missing_dependencies.pluck(:declaration).join("\n")}
-
-        GEMS
-      end
-
-      def ensure_tailwind_safelist
-        return create_tailwind_config unless File.exist?(tailwind_config_path)
-
-        source_entries = extract_safelist_entries(File.read(gem_tailwind_config_path))
-        target_content = File.read(tailwind_config_path)
-        target_entries = extract_safelist_entries(target_content)
-
-        missing_entries = source_entries - target_entries
-        return if missing_entries.empty?
-
-        File.write(tailwind_config_path, insert_entries(target_content, missing_entries))
-      end
-
-      def ensure_tailwind_application_stylesheet
-        path = tailwind_application_stylesheet_path
-        FileUtils.mkdir_p(File.dirname(path))
-
-        return create_file(path, "#{tailwind_css_import_line}\n") unless File.exist?(path)
-
-        content = File.read(path)
-        return if content.include?(tailwind_css_import_line)
-
-        File.open(path, 'a') do |file|
-          file.write("\n") unless content.empty? || content.end_with?("\n")
-          file.write("#{tailwind_css_import_line}\n")
-        end
-      end
-
+    # nodoc
+    module InstallGeneratorHelpers
       private
 
       def gem_dependencies
@@ -91,6 +45,22 @@ module Tramway
         '@import "tailwindcss";'
       end
 
+      def agents_file_path
+        @agents_file_path ||= File.join(destination_root, 'AGENTS.md')
+      end
+
+      def gem_agents_file_path
+        @gem_agents_file_path ||= File.expand_path('../../../../docs/AGENTS.md', __dir__)
+      end
+
+      def agents_template
+        @agents_template ||= File.read(gem_agents_file_path)
+      end
+
+      def agents_section_heading
+        @agents_section_heading ||= agents_template.lines.first&.strip
+      end
+
       def create_tailwind_config
         create_file tailwind_config_path, File.read(gem_tailwind_config_path)
       end
@@ -128,6 +98,79 @@ module Tramway
         line = content[line_start..index]
         line[/^\s*/] || '  '
       end
+
+      def append_agents_template(content)
+        separator = agents_separator(content)
+        File.open(agents_file_path, 'a') do |file|
+          file.write("#{separator}#{agents_template}")
+        end
+      end
+
+      def agents_separator(content)
+        return '' if content.empty?
+
+        content.end_with?("\n") ? "\n" : "\n\n"
+      end
+    end
+
+    # Running `rails generate tramway:install` will invoke this generator
+    #
+    class InstallGenerator < Rails::Generators::Base
+      include InstallGeneratorHelpers
+
+      desc 'Installs Tramway dependencies and Tailwind safelist configuration.'
+
+      def ensure_agents_file
+        return create_file(agents_file_path, agents_template) unless File.exist?(agents_file_path)
+
+        content = File.read(agents_file_path)
+        return if content.include?(agents_section_heading)
+
+        append_agents_template(content)
+      end
+
+      def ensure_dependencies
+        missing_dependencies = gem_dependencies.reject do |dependency|
+          gemfile_contains?(dependency[:name])
+        end
+
+        return if missing_dependencies.empty?
+
+        append_to_file 'Gemfile', <<~GEMS
+
+          # Tramway dependencies
+          #{missing_dependencies.pluck(:declaration).join("\n")}
+
+        GEMS
+      end
+
+      def ensure_tailwind_safelist
+        return create_tailwind_config unless File.exist?(tailwind_config_path)
+
+        source_entries = extract_safelist_entries(File.read(gem_tailwind_config_path))
+        target_content = File.read(tailwind_config_path)
+        target_entries = extract_safelist_entries(target_content)
+
+        missing_entries = source_entries - target_entries
+        return if missing_entries.empty?
+
+        File.write(tailwind_config_path, insert_entries(target_content, missing_entries))
+      end
+
+      def ensure_tailwind_application_stylesheet
+        path = tailwind_application_stylesheet_path
+        FileUtils.mkdir_p(File.dirname(path))
+
+        return create_file(path, "#{tailwind_css_import_line}\n") unless File.exist?(path)
+
+        content = File.read(path)
+        return if content.include?(tailwind_css_import_line)
+
+        File.open(path, 'a') do |file|
+          file.write("\n") unless content.empty? || content.end_with?("\n")
+          file.write("#{tailwind_css_import_line}\n")
+        end
+      end
     end
   end
 end

data/lib/tramway/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Tramway
-  VERSION = '2.0.4.1'
+  VERSION = '2.1'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: tramway
 version: !ruby/object:Gem::Version
-  version: 2.0.4.1
+  version: '2.1'
 platform: ruby
 authors:
 - kalashnikovisme
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-01-06 00:00:00.000000000 Z
+date: 2026-01-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: anyway_config
@@ -234,6 +234,7 @@ files:
 - config/locales/en.yml
 - config/routes.rb
 - config/tailwind.config.js
+- docs/AGENTS.md
 - lib/generators/tramway/install/install_generator.rb
 - lib/kaminari/helpers/tag.rb
 - lib/rules/turbo_html_attributes_rules.rb