# 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
yarn 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
yarn build                # Build JavaScript with esbuild
yarn 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
