AGENTS.md#

Repository summary#

• Ruby gem that provides a BlueFactory feed implementation.
• Main entrypoint: lib/bskypostroulettefeed.rb.
• Feed definition and server configuration live in lib/bskypostroulettefeed/feed/.
• Tests use Minitest in test/.
• Linting/formatting uses StandardRB via standard gem.
• Build/release tasks come from bundler/gem_tasks.

Setup#

• Install dependencies: bin/setup (runs bundle install).
• Use bundle exec for all Ruby tooling.
• Ruby version must satisfy the gemspec requirement (>= 3.2.0).

Common commands#

• Default checks: bundle exec rake (runs tests + StandardRB).
• Tests (all): bundle exec rake test.
• Tests (single file): bundle exec rake test TEST=test/test_bskypostroulettefeed.rb.
• Tests (single test name): bundle exec ruby -Itest test/test_bskypostroulettefeed.rb -n test_name.
• Lint/format: bundle exec standardrb.
• Lint via rake: bundle exec rake standard.
• Build gem: bundle exec rake build.
• Install gem locally: bundle exec rake install.
• Interactive console: bin/console.
• Run feed server (local dev): bin/dev-feed (requires env vars).

Environment variables#

• PUBLISHER_DID: DID used by BlueFactory publisher.
• HOSTNAME: hostname for feed endpoints.
• Configure via shell env before running bin/dev-feed.

Code layout#

• lib/bskypostroulettefeed.rb defines the gem module.
• lib/bskypostroulettefeed/version.rb stores VERSION.
• lib/bskypostroulettefeed/feed/ contains feed config and implementation.
• sig/ stores RBS type signatures.
• test/ contains Minitest suites and test_helper.

Formatting and linting (StandardRB)#

• Use StandardRB conventions; do not manually fight the formatter.
• Run bundle exec standardrb after edits that touch Ruby files.
• Prefer StandardRB defaults (2-space indent, no semicolons).
• Let StandardRB manage trailing commas and hash formatting.

Requires and file loading#

• Use # frozen_string_literal: true at top of Ruby files.
• Order requires as: stdlib, gem dependencies, then require_relative.
• Prefer require_relative for internal library files.
• Keep require blocks minimal and scoped to file needs.

Naming conventions#

• Modules/classes: CamelCase (PostRouletteFeed, Bskypostroulettefeed).
• Methods/variables: snake_case.
• Constants: SCREAMING_SNAKE_CASE.
• Files: snake_case, mirroring module paths.
• Test classes: Test* subclasses of Minitest::Test.
• Test methods: test_* names.

Types and signatures#

• Public API changes should be reflected in sig/*.rbs.
• Keep RBS modules/classes aligned with Ruby implementation.
• Use String, Integer, Array[String] style RBS types.
• If adding new public classes, add matching RBS stubs.

Error handling#

• Define custom errors under Bskypostroulettefeed::Error when needed.
• Raise specific errors rather than generic StandardError.
• Avoid rescuing broad exceptions unless you re-raise with context.
• Include actionable messages for runtime errors.

Configuration and environment#

• Use ENV.fetch when a variable is required.
• Use ENV["NAME"] when optional.
• Keep configuration centralized in lib/bskypostroulettefeed/feed/config.rb.

Feed implementation guidance#

• Feed#get_posts should return a hash with posts: array.
• display_name and description should return plain strings.
• Keep network calls isolated; prefer small helper methods.

Testing style#

• Require test_helper at the top of test files.
• Use refute_nil, assert, assert_equal, etc. from Minitest.
• Prefer small, focused tests over large integration cases.
• Use fixture helpers in test/ if new ones are introduced.

Dependencies#

• Add runtime dependencies in bskypostroulettefeed.gemspec.
• Add dev/test dependencies in Gemfile.
• Prefer adding only what is needed to keep the gem slim.

Documentation updates#

• Update README.md when public usage or CLI behavior changes.
• Update CHANGELOG.md for noteworthy changes.

Git and release notes#

• Use bundle exec rake build to verify packaging.
• Avoid running bundle exec rake release unless instructed.
• Do not update gemspec metadata unless asked.

Editor and agent rules#

• No .cursor/rules/, .cursorrules, or Copilot instructions found.
• If such files are added later, follow them for their scope.

Writing new files#

• Match existing folder structure (lib/, test/, sig/).
• Keep file names aligned with module names.

Performance and clarity#

• Favor clear, readable Ruby over micro-optimizations.
• Keep methods short and single-purpose.
• Extract helpers when logic grows beyond a few lines.

Security and secrets#

• Never commit API keys or tokens.
• Use environment variables or local config files for secrets.

Optional tooling (if needed)#

• Use bundle exec rake -T to list available rake tasks.
• Use bundle exec irb -r ./lib/bskypostroulettefeed for quick REPL.

Quick troubleshooting#

• Run bundle exec rake if unsure which checks to run.
• If StandardRB fails, fix offenses then re-run.
• If tests fail, run single tests with -n for isolation.

Conventions to keep#

• Maintain # frozen_string_literal: true in Ruby source.
• Keep require_relative paths consistent and minimal.
• Keep module nesting aligned with folder structure.
• Avoid monkey-patching global classes unless requested.

Versioning#

• Update lib/bskypostroulettefeed/version.rb for releases.
• Keep version as a semantic version string.

BlueFactory specifics#

• BlueFactory.add_feed is configured in feed/config.rb.
• BlueFactory::Server.run! is used in bin/dev-feed.
• Keep feed registration centralized in config.

New tests checklist#

• Add tests under test/ and name files test_*.rb.
• Ensure new tests run under bundle exec rake test.

Summary for agents#

• Use StandardRB and Minitest.
• Use bundle exec and update RBS with API changes.
• Ask before running release-related commands.