Skip to content

copilot-instructions.md

Latest commit

 

History

History
75 lines (52 loc) · 2.83 KB

copilot-instructions.md

File metadata and controls

75 lines (52 loc) · 2.83 KB

html2rss-web AI Agent Instructions

Overview

  • Ruby web app that converts websites into RSS 2.0 feeds.
  • Built with Roda backend + Preact frontend, using the html2rss gem (+ html2rss-configs).
  • Frontend: Vite-built Preact UI, served alongside Ruby backend.

Documentation website of core dependencies

Search these pages before using them. Find examples, plugins, UI components, and configuration options.

Roda

  1. https://roda.jeremyevans.net/documentation.html

Preact & Vite

  1. https://preactjs.com/guide/v10/getting-started/
  2. https://vite.dev/guide/

html2rss

  1. If available, find source locally in: ../html2rss.
  2. source code on github: https://github.com/html2rss/html2rss

Test and Linters

  1. https://docs.rubocop.org/rubocop/cops.html
  2. https://docs.rubocop.org/rubocop-rspec/cops_rspec.html
  3. https://rspec.info/features/3-13/rspec-expectations/built-in-matchers/
  4. https://www.betterspecs.org/

Fix rubocop RSpec/MultipleExpectations adding rspec tag :aggregate_failures.

Core Rules

  • ✅ Organise Roda routes via dedicated modules (e.g. Html2rss::Web::Routes::*), keeping the main app class thin.
  • ✅ Keep helper modules minimal: define entrypoints with class << self and push implementation helpers under private; avoid module_function unless mirroring existing conventions.
  • ✅ Validate all inputs. Pass outbound requests through SSRF filter.
  • ✅ Add caching headers where appropriate (Rack::Cache).
  • ✅ Errors: friendly messages for users, detailed logging internally.
  • ✅ Frontend: Use Preact components in frontend/src/. Keep it simple.
  • ✅ CSS: Use the app-owned frontend styles in frontend/src/styles/.
  • ✅ Specs: RSpec for Ruby, build tests for frontend.
  • ✅ When a spec needs to tweak environment variables, wrap the example in ClimateControl.modify so state is restored automatically.

Don't

  • ❌ Don't use Ruby's URI class or addressable gem directly. Strictly use Html2rss::Url only.
  • ❌ Don't bypass SSRF filter or weaken CSP.
  • ❌ Don't add databases, ORMs, or background jobs.
  • ❌ Don't leak stack traces or secrets in responses.
  • ❌ Don't reach into private API with send(...); expose what you need at the module level instead.
  • ❌ Don't modify frontend/dist/ - it's generated by build process.
  • ❌ NEVER expose the auth token a user provides.

Environment

  • RACK_ENV – environment
  • AUTO_SOURCE_ENABLED, AUTO_SOURCE_USERNAME, AUTO_SOURCE_PASSWORD, AUTO_SOURCE_ALLOWED_ORIGINS
  • HEALTH_CHECK_USERNAME, HEALTH_CHECK_PASSWORD
  • SENTRY_DSN (optional)

Verification Steps

  • Run ruby -c app.rb to check syntax
  • Run bundle exec rspec to verify tests
  • Check bundle install removes unused dependencies

Style

  • Add # frozen_string_literal: true
  • Follow RuboCop style
  • YARD doc comments for public methods