debshots/AGENTS.md

175 lines
4.7 KiB
Markdown

# AGENTS.md - Debshots Development Guide
This file provides guidance for AI agents working in the debshots codebase.
## Project Overview
Debshots is a Ruby on Rails 8 application that powers screenshots.debian.net. It provides package screenshots for Debian/Ubuntu package managers.
## Build/Lint/Test Commands
### Setup
```bash
bundle install # Install Ruby dependencies
bun install # Install JavaScript dependencies
rails db:create db:migrate # Create and migrate database
```
### Development
```bash
bin/dev # Start development server (runs foreman)
rails server # Alternative: start Rails server
rails console # Open Rails console
```
### Testing
```bash
rails test # Run all tests
rails test test/models/screenshot_test.rb # Run single test file
rails test -n test_name # Run single test method
rails test test/models/ test/controllers/ # Run tests in directory
```
### Linting
```bash
rubocop # Run RuboCop linter
rubocop -a # Auto-fix RuboCop offenses
```
### Frontend Build
```bash
bun run build # Build JavaScript with esbuild
bun run build:css # Build CSS with Sass
```
### Database
```bash
rails db:migrate # Run migrations
rails db:rollback # Rollback last migration
rails db:reset # Reset database
rails db:seed # Seed database
```
## Code Style Guidelines
### General
- Ruby version: 3.x
- Rails version: 8.x
- Always use `frozen_string_literal: true` at the top of Ruby files
### Naming Conventions
- **Files**: snake_case (e.g., `user_session.rb`)
- **Classes/Modules**: CamelCase (e.g., `UserSession`)
- **Methods/variables**: snake_case (e.g., `user_name`, `active_user?`)
- **Database columns**: snake_case (e.g., `created_at`, `user_id`)
- **Constants**: SCREAMING_SNAKE_CASE
### RuboCop Configuration
The project uses `rubocop-rails-omakase` with these overrides in `.rubocop.yml`:
- Line length: max 99 characters
- Encoding: disabled
- `Lint/MixedRegexpCaptureTypes`: disabled
- `Metrics/MethodLength`: max 30
- `Style/IfUnlessModifier`: disabled
### Formatting
- Use 2 spaces for indentation (no tabs)
- Use single-quoted strings unless interpolation needed
- Use `%w[]` for word arrays
- Use `%i[]` for symbol arrays
### Imports/Dependencies
- Prefer standard Rails patterns over explicit requires
- Gemfile groups: `:development`, `:test`, `:development, :test`
### Views
- Use Slim templates (`.slim` extension)
- Use Foundation CSS framework
- Use Turbo/Hotwire for SPA-like behavior
### Models
- Inherit from `ApplicationRecord`
- Use Shrine for file attachments (not Paperclip)
- Use `pg_search` for PostgreSQL full-text search
### Controllers
- Inherit from `ApplicationController`
- Use strong parameters
- Follow RESTful routing
### Testing
- Uses Minitest (not RSpec)
- Fixtures in `test/fixtures/*.yml`
- System tests use Capybara with Selenium
- Devise test helpers available via `Devise::Test::ControllerHelpers`
### Error Handling
- Use `rescue_from` in controllers for handled exceptions
- Use `Rails.logger.error` for logging
- Use custom exceptions in `lib/` for domain errors
### Authentication/Authorization
- Uses Devise for authentication
- Uses CanCanCan for authorization (see `Ability` model)
- OAuth via OmniAuth with `omniauth_openid_connect` for salsa.debian.net
### Key Gems
- **File uploads**: Shrine
- **Auth**: Devise + OmniAuth
- **AuthZ**: CanCanCan
- **Images**: MiniMagick, ImageProcessing
- **DB**: PostgreSQL + pg_search
- **Search**: Full-text via pg_search
## File Structure
```
app/
controllers/ # Rails controllers
models/ # ActiveRecord models
views/ # Slim templates
helpers/ # View helpers
assets/ # JS/CSS/images
config/
environments/ # Environment configs
routes.rb # Routing
db/
migrate/ # Migrations
schema.rb # Schema
lib/ # Library code
test/ # Minitest tests
models/ # Model tests
controllers/ # Controller tests
system/ # System/feature tests
fixtures/ # Test fixtures
```
## Common Tasks
### Generate a model
```bash
rails generate model User name:string email:string
rails db:migrate
```
### Generate a controller
```bash
rails generate controller Admin
```
### Run a specific rake task
```bash
rails rake namespace:task_name
```
### Create admin user
```bash
rails console
User.new(email: 'admin@example.com', password: 'secret').save
```
## Notes
- Application uses Docker for deployment (see Dockerfile, docker-compose.yml)
- CI uses Woodpecker (see `.woodpecker.yml`)
- Legacy: Previously used Paperclip, migrated to Shrine