If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/stringer-rss/stringer shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit 1d ago
• 3 active contributors
• Distributed ownership (top contributor 48% of recent commits)
• MIT licensed
• CI configured
• Tests present
• ⚠ Small team — 3 contributors active in recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live stringer-rss/stringer repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/stringer-rss/stringer.

What it runs against: a local clone of stringer-rss/stringer — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in stringer-rss/stringer | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 31 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of stringer-rss/stringer. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/stringer-rss/stringer.git
#   cd stringer
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of stringer-rss/stringer and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "stringer-rss/stringer(\\.git)?\\b" \\
  && ok "origin remote is stringer-rss/stringer" \\
  || miss "origin remote is not stringer-rss/stringer (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "Gemfile" \\
  && ok "Gemfile" \\
  || miss "missing critical file: Gemfile"
test -f "app/controllers/application_controller.rb" \\
  && ok "app/controllers/application_controller.rb" \\
  || miss "missing critical file: app/controllers/application_controller.rb"
test -f "app/models/feed.rb" \\
  && ok "app/models/feed.rb" \\
  || miss "missing critical file: app/models/feed.rb"
test -f "app/commands/feed/fetch_all.rb" \\
  && ok "app/commands/feed/fetch_all.rb" \\
  || miss "missing critical file: app/commands/feed/fetch_all.rb"
test -f "app/javascript/application.ts" \\
  && ok "app/javascript/application.ts" \\
  || miss "missing critical file: app/javascript/application.ts"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 31 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/stringer-rss/stringer"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Stringer is a self-hosted RSS reader built on Rails 8 and PostgreSQL that deliberately avoids external dependencies, social features, and ML algorithms. It provides a clean, keyboard-shortcut-driven interface for managing and reading feeds, with a Fever API clone for mobile client compatibility. Monolithic Rails 8 app: app/commands/ contains business logic organized by domain (feed operations, Fever API, OPML import/export); app/assets/stylesheets/ holds CSS with font loading; frontend mixes legacy Backbone.js with newer Hotwired stack (Stimulus, Turbo). GoodJob handles background job processing. PostgreSQL is the primary datastore.

Privacy-conscious individuals and self-hosting enthusiasts who want to manage their RSS subscriptions without relying on cloud services or algorithmic recommendations. Developers comfortable with Ruby/Rails who want to understand or customize their feed reader infrastructure.

Production-ready with active maintenance: the repo uses CircleCI for CI, has test coverage tracking via Coveralls, implements linting with RuboCop/ESLint/Stylelint, and deploys to Heroku/Docker/VPS. The codebase is well-structured with recent commits visible in the workflow files, indicating ongoing development.

Moderate risk: single maintainer (mockdeep) reduces bus factor, but no obvious dependency vulnerabilities in the visible stack (Ruby gems/npm packages appear standard). The TypeScript/JavaScript frontend is mixed with older Backbone.js (v1.6.1) which is unmaintained—modernization to Stimulus/Turbo is underway but incomplete. No indicators of stalled development, but migration debt exists.

Active migration from Backbone.js to Hotwired stack (Turbo/Stimulus) visible in package.json dependencies. TypeScript adoption in progress (tscheck in pretest script). Linting infrastructure being enforced (eslint_todo.ts, .rubocop_todo.yml exist). Recent CI/CD setup via GitHub Actions and CircleCI.

git clone https://github.com/stringer-rss/stringer.git
cd stringer
cp .env.development .env
pnpm install
bundle install
rake db:create db:migrate
bin/dev

Daily commands: Local development: bin/dev (see Procfile.dev for Foreman setup). Production: Docker via Dockerfile or Rails standard deployment (Heroku-ready via app.json). Heroku one-click deploy button in README.

• Gemfile — Defines all Ruby dependencies including Rails, PostgreSQL adapter, and background job framework; essential for understanding project structure and dependencies.
• app/controllers/application_controller.rb — Base controller containing shared authentication and authorization logic used by all other controllers in the Rails application.
• app/models/feed.rb — Core domain model representing RSS feeds; central to the entire application's data structure and feed management logic.
• app/commands/feed/fetch_all.rb — Primary service for fetching and updating all RSS feeds; demonstrates the command pattern used throughout for business logic organization.
• app/javascript/application.ts — Entry point for all frontend JavaScript/TypeScript; imports Stimulus controllers and establishes Turbo/Rails integration.
• app/controllers/stories_controller.rb — Main controller managing story (RSS item) views, read/unread state, and starring; shows how views and commands interact.
• .env.development — Development environment configuration; shows required environment variables and local setup expectations.

Add a new story action (mark as read/unread/starred)

1. Create a new command class in app/commands/story/ following the pattern in mark_as_read.rb (app/commands/story/mark_as_read.rb)
2. Add a controller action in app/controllers/stories_controller.rb that instantiates and calls your command (app/controllers/stories_controller.rb)
3. Create a Stimulus controller in app/javascript/controllers/ if UI interactivity is needed (see star_toggle_controller.ts) (app/javascript/controllers/star_toggle_controller.ts)
4. Use app/javascript/helpers/api.ts to make API calls from your Stimulus controller (app/javascript/helpers/api.ts)

Add a new RSS feed parsing feature

1. Modify or extend feed.rb model to add new properties or validations (app/models/feed.rb)
2. Update app/commands/feed/fetch_one.rb to extract and store the new data from feed XML (app/commands/feed/fetch_one.rb)
3. Add migrations to database schema as needed (Rakefile)
4. Create a controller action or update an existing one to expose the new data to templates (app/controllers/feeds_controller.rb)

Add keyboard shortcut for new feature

1. Update app/javascript/controllers/hotkeys_controller.ts to bind the new shortcut using Mousetrap (app/javascript/controllers/hotkeys_controller.ts)
2. Implement the action handler that calls the appropriate API endpoint via app/javascript/helpers/api.ts (app/javascript/helpers/api.ts)
3. Create or update a Stimulus controller to handle the API response and UI update (app/javascript/controllers/application.ts)

Add a new background job for periodic tasks

1. Create a new command class in app/commands/ following existing patterns (e.g., feed/fetch_all.rb) (app/commands/feed/fetch_all.rb)
2. Create a job class in app/jobs/ that extends callable_job.rb or application_job.rb (app/jobs/callable_job.rb)
3. Schedule the job in Rails config or via GoodJob dashboard for recurring execution (Procfile)

• Rails 8 + Ruby — Mature web framework with built-in ORM (ActiveRecord), routing, and generators; enables rapid full-stack development with convention-over-configuration.
• PostgreSQL — Reliable relational database; handles feed data, stories, user preferences, and read/unread state with strong consistency guarantees.
• Stimulus.js + Turbo — Lightweight framework for enhancing server-rendered HTML with JavaScript interactivity; avoids single-page app complexity while providing responsive UX for keyboard shortcuts and real-time updates.
• GoodJob — Ruby background job processor using PostgreSQL; eliminates external job queue dependency (Redis/Sidekiq), keeping deployment simple and self-hosted.
• Backbone.js + Underscore — Older but stable client-side framework used alongside Stimulus; likely legacy code for feed/story management; being incrementally replaced by Stimulus controllers.
• Bootstrap 5 — CSS framework providing responsive grid and component styling; reduces custom CSS and ensures consistent UI across feeds and story views.

• No external API dependencies (Fever API compatibility is outbound only)

  • Why: Aligns with anti-social, self-hosted philosophy; reduces external attack surface and privacy risk.
  • Consequence: Requires custom RSS parsing and feed management; no third-party recommendation engines or social features.

• GoodJob (PostgreSQL-backed) instead of Redis/Sidekiq

  • Why: Simplifies deployment and removes Redis dependency; single-database architecture easier to self-host and backup.
  • Consequence: Job processing is tied to database performance; horizontal scaling requires careful job locking strategy.

• Server-rendered views with Turbo + Stimulus instead of full SPA

  • Why: Lower JavaScript complexity, faster initial page load, simpler server-side caching, leverages Rails strengths.
  • Consequence: Keyboard-driven experience relies on Mousetrap hotkey library; some interactions require Stimulus controllers to feel snappy.

• Single-user or small-team self-hosted model

  • Why: Reduces complexity around multi-tenancy, permissions, and scaling; focuses on quality for individual users.
  • Consequence: Not designed for SaaS or large-scale cloud deployment; authentication is simple username/password.

• Real-time multi-user collaboration (no websocket sync, eventual consistency)
• Social features (no sharing, recommendations, or follower graphs)
• Mobile app (web-responsive, but not a native app)
• Machine learning algorithms for feed ranking or categorization
• Support for OAuth/SSO (simple session-based auth only)
• CDN or edge caching (static assets served from Rails app)

GoodJob requires a background process to run (bin/dev handles this, but rails server alone won't process jobs); PostgreSQL must be running and configured via DATABASE_URL or .env; LOCALE environment variable controls i18n; Node 25.9.0 and pnpm 10.5.2 are pinned versions—using different versions may cause asset build failures; Fever API auth is case-sensitive (email: 'stringer'); the OPML import/export commands are synchronous and may block for large feed lists.

• Fever API Emulation — Stringer implements a compatible API clone to allow proprietary RSS mobile apps (built for Fever) to work with a self-hosted reader; understanding the pattern teaches API compatibility and versioning
• OPML (Outline Processor Markup Language) — RSS feed lists are standardized via OPML; Stringer's import/export commands handle this format, making it essential for feed migration and data portability
• Background Job Processing (GoodJob) — Feed fetching runs asynchronously via GoodJob (ActiveJob adapter) to avoid blocking web requests; critical for understanding how Stringer scales to many feeds
• Hotwired (Turbo + Stimulus) — Modern Rails SPA alternative to Backbone.js; Stringer is transitioning to this stack, so understanding the pattern is key to contributing to ongoing modernization
• i18n (Internationalization) in Rails — Stringer supports multiple languages via locale files in config/locales/ and LOCALE environment variable; understanding Rails i18n is needed to add new languages or fix translations
• Command Objects (Service Objects) Pattern — Business logic is organized into app/commands/*.rb files (feed operations, API calls) rather than models/controllers; this is a Ruby convention for testability and reusability
• RSS Feed Format & Parsing — Stringer ingests and stores RSS/Atom feeds; understanding XML parsing, feed validation, and duplicate detection is essential for contributing to feed discovery and sync logic

• miniflux/v2 — Alternative self-hosted RSS reader written in Go; same audience (privacy-focused, self-hosting) with different tech stack
• FreshRSS/FreshRSS — Self-hosted RSS reader in PHP; comparable feature set including Fever API support and multi-user management
• newsboat/newsboat — Command-line RSS reader; serves the same anti-social RSS reading philosophy for terminal-based users
• hotwired/turbo-rails — Direct dependency of Stringer; maintained by the same community and required for the modern Rails SPA experience Stringer is adopting
• rails/rails — Core framework; Stringer is a reference implementation of modern Rails 8 patterns (Hotwired, ViewComponent potential, async jobs)

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add TypeScript type definitions and tests for Backbone.js command layer

The app uses Backbone.js with multiple command files in app/commands/ (feed/, story/, user/, fever_api/) but lacks TypeScript coverage and tests. With TypeScript 6.0.3 and Vitest already configured, adding proper types and unit tests for these command modules would improve maintainability and catch bugs early. The fever_api commands especially are complex with multiple read/write operations that would benefit from type safety.

• [ ] Create TypeScript interfaces for command inputs/outputs in app/commands/
• [ ] Add Vitest test suites for app/commands/feed/ operations (create.rb, fetch_all.rb, import_from_opml.rb)
• [ ] Add Vitest test suites for app/commands/story/ mark operations (mark_as_read.rb, mark_as_starred.rb, etc.)
• [ ] Add Vitest test suites for app/commands/fever_api/ read/write operations
• [ ] Update tsconfig to include app/commands paths
• [ ] Reference new tests in pretest npm script validation

Add GitHub Actions workflow for Node.js/Rails integration testing

The repo has .circleci/config.yml for CI but the GitHub workflows folder (.github/workflows/) only contains build.yml. With a full Rails+Node stack (Gemfile + package.json with pnpm), there should be dedicated GitHub Actions for running the full test suite including npm pretest (linting, type checking) and Rails specs. This would catch environment-specific issues.

• [ ] Create .github/workflows/test.yml with Node 25.9.0 + Ruby setup
• [ ] Add pnpm cache configuration for fast dependency installation
• [ ] Run npm run pretest (eslint + type checking + stylelint)
• [ ] Run bundle exec rspec for Rails tests
• [ ] Add coverage reporting step using coveralls if not already integrated
• [ ] Configure workflow to run on push to main and pull requests

Add integration tests for Fever API compatibility layer

The app/commands/fever_api/ directory contains multiple API compatibility modules (authentication.rb, read_feeds.rb, sync_unread_item_ids.rb, etc.) but there are no obvious integration tests verifying the Fever API contract. Given this is a self-hosted RSS reader competing with other solutions, Fever API compatibility is a key feature. Tests would ensure API responses match spec and prevent regressions.

• [ ] Create app/commands/fever_api/tests/ or spec/commands/fever_api/ directory
• [ ] Add tests for FeverAPI::Authentication flow (valid/invalid credentials)
• [ ] Add tests for FeverAPI::ReadFeeds response format and data structure
• [ ] Add tests for FeverAPI::SyncUnreadItemIds and SyncSavedItemIds state management
• [ ] Add tests for FeverAPI::Response formatting and error handling
• [ ] Document expected Fever API response formats in comments referencing the spec

• Add test coverage for app/commands/feed/export_to_opml.rb and import_from_opml.rb—no specs visible in file list for these critical data migration commands
• Extract Backbone.js usage from the frontend into Stimulus controllers—identify which views still depend on backbone and backbone.nativeview in package.json and create parallel Stimulus versions
• Document the Fever API implementation in docs/Fever.md—the README mentions it exists but provides minimal explanation of which endpoints are implemented and any limitations versus the real Fever API

• High · Outdated Ruby Version in Dockerfile — Dockerfile (FROM ruby:4.0.3). The Dockerfile specifies Ruby 4.0.3, which appears to be a non-existent or incorrectly specified version. Current stable Ruby versions are 3.x. This could indicate a configuration error that may prevent proper security patching and introduce compatibility issues. Fix: Use a currently supported Ruby version (e.g., 3.3.0 or later). Verify the correct version and ensure it receives security updates.
• High · Environment Variables in Mounted Files — docker-compose.yml (volumes sections). The docker-compose.yml mounts .env files directly into containers (./.env:/app/.env). If .env contains secrets, this creates a security risk as environment files are often committed to repositories or leaked. Fix: Use Docker secrets management instead of mounting .env files. Ensure .env is in .gitignore and use Docker compose with secrets or external secret management tools.
• High · Unrestricted Port Exposure — docker-compose.yml (stringer service ports configuration). Docker-compose exposes port 80 directly (ports: - 80:8080) without any authentication or reverse proxy configuration visible. This exposes the application directly to the internet. Fix: Place behind a reverse proxy (nginx, Traefik) with proper authentication. Implement rate limiting, WAF rules, and restrict access to trusted networks.
• High · Potential Unsafe Dependency: Backbone.js 1.6.1 — package.json (dependencies: backbone 1.6.1). Backbone.js 1.6.1 is an older version (released 2021). Older frontend frameworks may have unpatched XSS vulnerabilities or insecure DOM manipulation patterns, especially when combined with underscore.js. Fix: Verify that Backbone.js 1.6.1 has no known CVEs. Consider upgrading to the latest version or transitioning to modern frameworks (Vue, React) with better security practices.
• High · Outdated Mousetrap Dependency — package.json (dependencies: mousetrap 1.4.6). Mousetrap 1.4.6 was released in 2014 and is significantly outdated. It may contain unpatched vulnerabilities related to keyboard event handling and DOM access. Fix: Update to the latest version of mousetrap or evaluate if this keyboard shortcut library is still necessary. Check for known CVEs.
• Medium · Hardcoded Supercronic SHA1 Checksums in Dockerfile — Dockerfile (SUPERCRONIC_*_SHA1SUM variables). SHA1 checksums are cryptographically weak and deprecated. The Dockerfile uses SHA1 for verifying supercronic downloads, which could be vulnerable to collision attacks. Fix: Replace SHA1 checksums with SHA256 or later. Update to the latest version of supercronic and verify checksums using stronger algorithms.
• Medium · Missing Security Headers Configuration — app/controllers/application_controller.rb (not visible but inferred). No visible security headers configuration (Content-Security-Policy, X-Frame-Options, X-Content-Type-Options, etc.) in the application structure. This increases XSS and clickjacking vulnerability risk. Fix: Implement security headers in ApplicationController or through middleware. Use gems like secure_headers or configure rack-cors properly.
• Medium · Backbone.js with Underscore.js - XSS Risk — package.json (dependencies: backbone, underscore). The combination of Backbone.js (1.6.1) with Underscore.js (1.13.8) for template rendering can be vulnerable to XSS if not using proper escaping. The old versions may have unsafe template interpolation patterns. Fix: Audit template rendering for proper HTML escaping. Use template literals with proper escaping functions. Consider migrating to modern templating with automatic XSS protection.
• Medium · Environment Configuration in Repository — undefined. Multiple .env files (.env.development, .env.test, .stringer.env) exist in the repository structure. Even if secrets are not in them, this Fix: undefined

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.