ariadna 1.3.1 → 2.0.0

data/data/skills/rails-backend/SKILL.md

@@ -0,0 +1,169 @@
+---
+name: rails-backend
+description: Ruby on Rails backend conventions — models, controllers, jobs, API design. Use when implementing Rails backend code, creating models, writing controllers, or designing APIs.
+---
+
+# Rails Backend Skill
+
+Opinionated conventions for Rails backend code. Architecture is built on a single principle: **place the domain model at the center.** Controllers, jobs, and the console are all boundaries that orchestrate domain logic — they contain no business logic themselves.
+
+**Sub-files:**
+- [MODELS.md](MODELS.md) — Concern architecture, associations, scoping, callbacks
+- [CONTROLLERS.md](CONTROLLERS.md) — REST conventions, strong params, concerns
+- [JOBS.md](JOBS.md) — _now/_later pattern, multi-tenancy context
+- [API.md](API.md) — JSON responses, serialization, versioning
+
+---
+
+## Core Philosophy
+
+### Domain Model at the Center
+
+```
+Controller ──┐
+             ▼
+Console ──► Domain Model ◄── Job
+             ▲
+Script  ─────┘
+```
+
+`card.close` works identically whether called from a controller, job, console, or test. The domain model is the single source of truth for business behavior.
+
+### No New Architectural Artifacts
+
+No service objects, form objects, interactors, or command pattern libraries. Building blocks:
+
+- **Models** — domain entities and operations (ActiveRecord and plain Ruby)
+- **Concerns** — organize model behavior into cohesive modules
+- **Controllers** — HTTP boundary only
+- **Jobs** — async boundary; delegate to model methods
+- **Views** — render domain state (templates, not view components)
+
+When something doesn't fit in an entity, create a plain Ruby object with a semantic name — not a new architectural pattern. A `Signup` class, not a `SignupService`. A `Notifier`, not a `NotificationInteractor`.
+
+### Preference for Rails Defaults
+
+Minitest over RSpec · view templates over view components · ActiveRecord callbacks over observer patterns · `Current` over dependency injection · concerns over decorator libraries.
+
+---
+
+## Domain Model Overview
+
+```
+Account (tenant/organization)
+  └── Users (members with roles)
+  └── Boards (project spaces)
+       └── Columns (workflow stages)
+       └── Cards (tasks/issues)
+            └── Comments, Assignments, Tags
+```
+
+---
+
+## Multi-Tenancy
+
+URL path-based tenancy — account ID extracted from path by middleware, sets `Current.account`.
+
+```ruby
+class Current < ActiveSupport::CurrentAttributes
+  attribute :session, :user, :identity, :account
+
+  def session=(value)
+    super(value)
+    self.identity = session.identity if value.present?
+  end
+
+  def identity=(identity)
+    super(identity)
+    self.user = identity.users.find_by(account: account) if identity.present?
+  end
+end
+```
+
+Setting `Current.session` cascades: resolves `identity`, then resolves `user` for the current account.
+
+- Always use `Current.user` instead of passing `@user` as a parameter
+- Always use `Current.account` for tenant scoping
+- In tests: `Current.session = sessions(:david)` sets up the full chain
+
+---
+
+## No Service Objects
+
+Controllers already fulfill the application service role from DDD — they sit at the boundary and orchestrate domain entities. Adding service objects creates a redundant layer.
+
+**The real danger: anemic domain models.** When business logic lives in service objects instead of domain entities, models become empty data holders and logic scatters across a flat list of service classes with no object-oriented structure.
+
+```ruby
+# Bad: service object drains logic from the model
+class CloseCardService
+  def call = @card.update!(status: "closed") && EventService.new(@card).call
+
+# Good: logic belongs in the domain entity
+module Card::Closeable
+  def close(user: Current.user)
+    transaction { create_closure!(user:); track_event :closed, creator: user }
+  end
+end
+```
+
+**Decision tree: where does logic belong?**
+
+- Acts on one entity's state → put in model/concern
+- Coordinates 2-3 entities, triggered by HTTP → controller handles it
+- Coordinates 2-3 entities, domain concept → plain Ruby object (`Signup`, not `SignupService`)
+- Runs async → job delegates to model method
+
+---
+
+## Code Style Conventions
+
+### Conditional Returns
+
+Prefer expanded conditionals over guard clauses in the middle of methods. Guard clauses are acceptable at the very start when the method body is non-trivial.
+
+```ruby
+# Avoid mid-method returns
+def process
+  return [] unless ids
+  find(ids)
+end
+
+# Prefer
+def process
+  if ids then find(ids) else [] end
+end
+```
+
+### Method Ordering
+
+1. Class methods (top)
+2. Public methods (`initialize` first)
+3. Private methods — indented under `private`, no blank line after `private`
+
+```ruby
+private
+  def method_one; end
+  def method_two; end
+```
+
+Private methods are ordered by invocation — top-to-bottom following execution flow.
+
+### Bang Methods
+
+Only use `!` for methods that have a non-bang counterpart (`save`/`save!`). Do not use `!` to flag destructive actions with no non-bang version.
+
+---
+
+## Common Gotchas
+
+1. **Business logic in controllers** — move it to models
+2. **Custom route actions** — use `resource :closure` not `post :close`
+3. **Logic in jobs** — jobs are thin wrappers; logic lives in model methods
+4. **Association declaration order** — declare `belongs_to :board` before `belongs_to :account, default: -> { board.account }`
+5. **Finding cards by `:id`** — cards use `:number`: `accessible_cards.find_by!(number: params[:card_id])`
+6. **Multi-step operations without transactions** — always wrap in `transaction do`
+
+---
+
+See [MODELS.md](MODELS.md) for ActiveRecord patterns, [CONTROLLERS.md](CONTROLLERS.md) for HTTP conventions, [JOBS.md](JOBS.md) for background job patterns, and [API.md](API.md) for API design.

data/data/skills/rails-frontend/ASSETS.md

@@ -0,0 +1,154 @@
+# Assets — CSS, JS Bundling, Design Tokens
+
+## CSS Architecture
+
+**Pure custom CSS — no Tailwind, Bootstrap, or utility frameworks.** Built on modern CSS: custom properties, OKLCH colors, CSS layers, and logical properties.
+
+### Layer Organization
+
+```css
+@layer reset;      /* Browser normalization */
+@layer base;       /* Base element styles */
+@layer components; /* Component-specific styles */
+@layer modules;    /* Feature modules */
+@layer utilities;  /* Utility classes */
+```
+
+### File Organization
+
+```
+app/assets/stylesheets/
+├── _global.css      # Root variables and @layer definitions
+├── base.css         # Base element styling
+├── utilities.css    # Utility classes
+├── buttons.css      # Button components
+├── inputs.css       # Form inputs
+├── cards.css        # Card components
+├── layout.css       # Main layout
+└── [feature].css    # Feature-specific styles
+```
+
+---
+
+## Design Tokens
+
+### Colors — OKLCH
+
+Use OKLCH for perceptual uniformity across light/dark modes. Always use semantic variables:
+
+| Variable | Purpose |
+|----------|---------|
+| `--color-ink` | Primary text |
+| `--color-ink-light` | Secondary text |
+| `--color-canvas` | Background |
+| `--color-link` | Interactive elements (blue) |
+| `--color-positive` | Success (green) |
+| `--color-negative` | Error (red) |
+
+Dark mode via attribute and media query:
+
+```css
+html[data-theme="dark"] { ... }
+@media (prefers-color-scheme: dark) { html:not([data-theme]) { ... } }
+```
+
+### Spacing — Logical Properties
+
+Use `block` (vertical) and `inline` (horizontal) instead of top/bottom/left/right for RTL support:
+
+```css
+--inline-space: 1ch;
+--block-space:  1rem;
+```
+
+Key utilities: `.pad`, `.pad-block`, `.pad-inline`, `.margin`, `.gap`, `.gap-half`
+
+### Typography
+
+```css
+--font-sans: "Adwaita Sans", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+--font-mono: ui-monospace, monospace;
+```
+
+Scale: `--text-xx-small` (0.55rem) through `--text-xx-large` (2.5rem). Always use `rem`, never `px` for font sizes.
+
+---
+
+## Icons
+
+CSS mask-based icon system — icons inherit `currentColor`, easy to style contextually:
+
+```erb
+<%= icon_tag "check" %>
+<%= icon_tag "pencil", class: "txt-subtle" %>
+```
+
+Generates: `<span class="icon icon--check" aria-hidden="true"></span>`
+
+Icon-only buttons — use `aria-label` or `.for-screen-reader` for accessibility:
+
+```erb
+<%= button_to path, class: "btn", aria: { label: "Edit" } do %>
+  <%= icon_tag "pencil" %>
+<% end %>
+```
+
+New SVG requirements: `viewBox="0 0 24 24"`, no fixed `width`/`height`, `fill="currentColor"`, monochrome for mask-image compatibility.
+
+---
+
+## Component Patterns
+
+### Buttons
+
+```css
+.btn                /* Base — rounded pill */
+.btn--positive      /* Green */
+.btn--negative      /* Red/destructive */
+.btn--link          /* Text-only */
+.btn--circle        /* Circular icon button */
+```
+
+### Inputs
+
+All inputs use `font-size: max(16px, 1em)` to prevent iOS auto-zoom.
+
+```erb
+<%= form.text_field :name, class: "input" %>
+<%= form.select :status, options, {}, class: "input input--select" %>
+<%= form.text_area :body, class: "input input--textarea", rows: 1 %>
+```
+
+Auto-resizing textarea (modern browsers): `field-sizing: content`
+
+### Focus & Motion
+
+```css
+--focus-ring: 2px solid var(--color-link);  /* Applied via :focus-visible */
+
+@media (prefers-reduced-motion: reduce) {
+  animation-duration: 0.01ms !important;
+  transition-duration: 0.01ms !important;
+}
+```
+
+Always respect `prefers-reduced-motion`. Always apply focus states on interactive elements.
+
+---
+
+## JS Bundling
+
+Controllers are auto-discovered from `app/javascript/controllers/`. No manual registration.
+
+Importmap (default) or esbuild depending on project setup. Third-party libraries bridged through Stimulus value callbacks — keep the controller as the integration boundary, not inline `<script>` tags.
+
+---
+
+## Rules
+
+- Use semantic color variables, never hard-coded values
+- Use logical properties (`block-start` not `top`, `inline-size` not `width`)
+- Use CSS custom properties for component variants
+- Use `clamp()` for fluid responsive values
+- Test in both light and dark modes
+- Never create z-index values without adding to the defined stack

data/data/skills/rails-frontend/COMPONENTS.md

@@ -0,0 +1,253 @@
+# Components — Stimulus Controllers & Presenter Pattern
+
+## Stimulus Controller Architecture
+
+**File naming:** `app/javascript/controllers/{name}_controller.js`
+
+| File | Class | Identifier |
+|------|-------|------------|
+| `upload_preview_controller.js` | `UploadPreviewController` | `upload-preview` |
+| `broadcast_channel_controller.js` | `BroadcastChannelController` | `broadcast-channel` |
+
+Controllers in `app/javascript/controllers/` are auto-discovered. No manual `application.register()` needed.
+
+### Contract-First Declaration
+
+Declare the full interface at the top before any methods:
+
+```javascript
+import { Controller } from "@hotwired/stimulus"
+
+export default class extends Controller {
+  static values  = { url: String, refreshInterval: Number, active: Boolean }
+  static targets = ["output", "spinner", "emptyState"]
+  static outlets = ["filter", "notification"]
+  static classes = ["loading", "hidden"]
+
+  connect() { }
+  disconnect() { }
+}
+```
+
+**Single-purpose controllers.** Compose multiple controllers rather than one large one:
+
+```html
+<div data-controller="clipboard toggle tooltip"
+     data-clipboard-text-value="https://example.com/share/abc123">
+  <button data-action="clipboard#copy toggle#toggle">Copy Link</button>
+</div>
+```
+
+---
+
+## Lifecycle
+
+**Every `connect()` resource must be released in `disconnect()`.** Turbo navigations and morphs trigger these repeatedly:
+
+```javascript
+connect() {
+  this.broadcast = new BroadcastChannel(this.channelValue)
+  this.broadcast.onmessage = this.handleMessage.bind(this)
+  this.refreshTimer = setInterval(() => this.refresh(), 30000)
+}
+
+disconnect() {
+  this.broadcast.close()
+  clearInterval(this.refreshTimer)
+}
+```
+
+| Resource | Setup | Teardown |
+|----------|-------|----------|
+| BroadcastChannel | `new BroadcastChannel()` | `.close()` |
+| Blob URL | `URL.createObjectURL()` | `URL.revokeObjectURL()` |
+| Timer | `setInterval()` / `setTimeout()` | `clearInterval()` / `clearTimeout()` |
+| Observer | `.observe()` | `.disconnect()` |
+| EventListener (window/doc) | `addEventListener()` | `removeEventListener()` |
+
+**Guard `valueChanged` callbacks** — they fire before `connect()` completes; targets may not exist yet:
+
+```javascript
+urlValueChanged(url) {
+  if (!this.hasFrameTarget) return
+  this.frameTarget.src = url
+}
+```
+
+---
+
+## Values (Reactive State)
+
+Values are the single source of truth. Never duplicate state in dataset entries or instance variables.
+
+```javascript
+static values = {
+  url:     String,   // default: ""
+  count:   Number,   // default: 0
+  active:  Boolean,  // default: false
+  filters: Object,   // default: {}
+  items:   Array,    // default: []
+}
+```
+
+React with `{name}ValueChanged`. The `previous` argument is `undefined` on initial load:
+
+```javascript
+pageValueChanged(current, previous) {
+  if (previous !== undefined) this.fetchPage(current)
+  this.counterTarget.textContent = `Page ${current}`
+}
+
+next() { this.pageValue++ }  // Triggers pageValueChanged automatically
+```
+
+Bridge third-party libraries through value callbacks — the value is the source of truth, the callback translates to the library API:
+
+```javascript
+dataValueChanged(data) {
+  if (!this.chart) return
+  this.chart.data = data
+  this.chart.update()
+}
+```
+
+---
+
+## Targets
+
+Target callbacks fire when the DOM changes — essential for Turbo Stream integration:
+
+```javascript
+static targets = ["item", "counter", "emptyState"]
+
+itemTargetConnected(element) {
+  this.updateCount()
+  element.animate([{ opacity: 0 }, { opacity: 1 }], { duration: 200 })
+}
+
+itemTargetDisconnected() { this.updateCount() }
+
+updateCount() {
+  this.counterTarget.textContent = this.itemTargets.length
+  this.emptyStateTarget.hidden = this.itemTargets.length > 0
+}
+```
+
+**Keep target callbacks idempotent** — morphs can trigger `TargetConnected` multiple times:
+
+```javascript
+// Bad — adds duplicate listeners on reconnect
+itemTargetConnected(element) {
+  element.addEventListener("click", this.handleClick)
+}
+
+// Good
+itemTargetConnected(element) {
+  element.handleClick ||= this.handleClick.bind(this)
+  element.removeEventListener("click", element.handleClick)
+  element.addEventListener("click", element.handleClick)
+}
+```
+
+Derive computed state from targets rather than tracking separate values:
+
+```javascript
+get isEmpty()       { return this.itemTargets.length === 0 }
+get selectedItems() { return this.itemTargets.filter(el => el.dataset.selected === "true") }
+```
+
+---
+
+## Outlets (Controller-to-Controller)
+
+Prefer outlets over custom events or `getControllerForElementAndIdentifier` for direct communication:
+
+```javascript
+// dashboard_controller.js
+static outlets = ["chart", "filter"]
+
+apply() {
+  const filters = this.filterOutlet.currentFilters
+  this.chartOutlets.forEach(chart => chart.reload(filters))
+}
+```
+
+```html
+<div data-controller="dashboard"
+     data-dashboard-chart-outlet=".chart-widget"
+     data-dashboard-filter-outlet="#main-filter">
+```
+
+---
+
+## Action Parameters
+
+Pass typed data from HTML without manual `dataset` parsing:
+
+```html
+<button data-action="cart#add"
+        data-cart-id-param="42"
+        data-cart-name-param="Widget"
+        data-cart-price-param="19.99">
+```
+
+```javascript
+add({ params: { id, name, price } }) {
+  this.addItem(id, name, price)  // id = 42 (Number), name = "Widget" (String)
+}
+```
+
+Keyboard filters:
+
+```html
+<textarea data-action="keydown.ctrl+s->editor#save
+                       keydown.meta+s->editor#save
+                       keydown.esc->editor#cancel">
+```
+
+---
+
+## Presenter Pattern
+
+Plain Ruby classes in `app/models/` — no special directory, no inheritance:
+
+```ruby
+class Event::Description
+  include ActionView::Helpers::TagHelper
+  include ERB::Util
+
+  def initialize(event, user) = @event, @user = event, user
+
+  def to_html = to_sentence(creator_tag, card_title_tag).html_safe
+  def to_plain_text = to_sentence(creator_name, quoted(card.title))
+
+  private
+    def creator_tag = tag.span(event.creator.name, class: "creator")
+end
+```
+
+Factory method on the model keeps the API discoverable:
+
+```ruby
+# app/models/event.rb
+def description_for(user) = Event::Description.new(self, user)
+```
+
+```erb
+<%= event.description_for(Current.user).to_html %>
+```
+
+Controller concern for cross-controller instantiation:
+
+```ruby
+module FilterScoped
+  extend ActiveSupport::Concern
+  included do
+    before_action :set_user_filtering
+  end
+  private
+    def set_user_filtering
+      @user_filtering = User::Filtering.new(Current.user, @filter, expanded: expanded_param)
+    end
+end
+```