Skip to content

copilot-instructions.md

Latest commit

 

History

History
75 lines (52 loc) · 2.87 KB

copilot-instructions.md

File metadata and controls

75 lines (52 loc) · 2.87 KB

html2rss-web AI Agent Instructions

Overview

  • Ruby web app that converts websites into RSS 2.0 feeds.
  • Built with Roda backend + Astro frontend, using the html2rss gem (+ html2rss-configs).
  • Frontend: Modern Astro-based UI with component architecture, 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

Astro & Starlight

  1. https://docs.astro.build/en/getting-started/
  2. https://starlight.astro.build/getting-started/

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 Astro components in frontend/src/. Keep it simple.
  • ✅ CSS: Use frontend styles provided by Astro Starlight.
  • ✅ 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