A GitHub release viewer for npm packages. Track release notes across your favorite packages in one place.

Forged in Gas Town

Stage: Development (MVP) Health Score: 8/10

• Package Tracking - Add npm packages to monitor their GitHub releases
• Release Timeline - Mobile-first timeline view grouped by date
• Package Picker - Filter releases by selected packages
• Sync Engine - Fetch releases from GitHub with rate limit awareness
• AI Summaries - Generate concise release note summaries using Groq LLM
• Design System - Consistent visual language across components

• PatchNotes.Data - EF Core models, SQLite database, GitHub API client, Groq LLM client
• PatchNotes.Api - ASP.NET Core Web API (port 5031)
• PatchNotes.Sync - Console app to fetch releases from GitHub
• patchnotes-web - React frontend with TanStack Router & Query

• .NET 10 SDK
• Node.js 18+
• direnv (recommended for secrets management)

The project uses direnv for environment-based configuration. Create a secrets file at ~/.secrets/patchnotes/.env.local:

# Required for API authentication
APIKEY=your-api-key

# Required for GitHub API (increases rate limit)
GITHUB__TOKEN=your-github-token

# Required for AI summaries
GROQ__APIKEY=your-groq-api-key

# Optional: customize the LLM model (default: llama-3.3-70b-versatile)
# GROQ__MODEL=llama-3.3-70b-versatile

Get a Groq API key at https://console.groq.com/keys

The app uses Stytch for B2C authentication.

Add these environment variables to the frontend (via .env or Vite config):

VITE_STYTCH_PROJECT_ID=your-project-id
VITE_STYTCH_PUBLIC_TOKEN=your-public-token

1. Create a Stytch account at https://stytch.com/
2. Create a new Consumer project
3. Configure allowed redirect URLs for your domains
4. Copy the Project ID and Public Token to your environment

dotnet build

dotnet ef database update --context SqliteContext --project PatchNotes.Data --startup-project PatchNotes.Api

cd PatchNotes.Sync
dotnet run -- --seed

cd PatchNotes.Api
dotnet run

API available at: http://localhost:5031

cd patchnotes-web
npm install
npm run dev

Frontend available at: http://localhost:5173

# List packages
curl http://localhost:5031/api/packages

# Get releases (last 7 days)
curl http://localhost:5031/api/releases

# Get releases for specific packages
curl "http://localhost:5031/api/releases?packages=react,vue&days=30"

# Add a package
curl -X POST http://localhost:5031/api/packages \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{"npmName": "lodash"}'

# Get AI summary of a release
curl -X POST http://localhost:5031/api/releases/1/summarize

cd PatchNotes.Sync
dotnet run

Exit codes: 0=success, 1=partial failure, 2=fatal error

cd PatchNotes.Sync
dotnet run -- --seed

PatchNotes/
├── PatchNotes.Api/           # Web API
├── PatchNotes.Data/          # Data layer
│   ├── Migrations/           # EF Core migrations
│   ├── GitHub/               # GitHub API client
│   └── Groq/                 # Groq LLM client
├── PatchNotes.Sync/          # Sync console app
└── patchnotes-web/           # React frontend
    └── src/
        ├── components/
        │   ├── package-picker/   # Package selection UI
        │   ├── releases/         # Release timeline components
        │   └── ui/               # Shared UI components
        ├── pages/                # Route pages
        ├── api/                  # TanStack Query hooks
        └── routes/               # TanStack Router config

Backend:

• .NET 10 / ASP.NET Core
• Entity Framework Core + SQLite
• GitHub API integration

Frontend:

• React 18 + TypeScript
• TanStack Router (type-safe routing)
• TanStack Query (data fetching)
• Vite (build tool)

The project uses separate EF Core migrations for SQLite (development) and SQL Server (production).

Creating a new migration (when you change entity models):

# Set SQL Server connection string (required)
export ConnectionStrings__PatchNotes="Server=...;Database=...;User Id=...;Password=..."

# Generate migrations for both providers
./scripts/add-migration.sh MigrationName

This creates migrations in:

• PatchNotes.Data/Migrations/Sqlite/ - Local development
• PatchNotes.Data/Migrations/SqlServer/ - Production

Important: CI will fail if you change models without creating migrations. The has-pending-model-changes check ensures migrations are always committed with model changes.

For more details, see PatchNotes.Data/README.md.

Backend:

dotnet test PatchNotes.slnx

Frontend:

cd patchnotes-web
npm test

The project uses GitHub Actions for CI. All PRs must pass:

• dotnet build and dotnet test
• npm run lint and npm run format:check
• npm run build (includes TypeScript type checking)

Backend (.NET):

• Follow standard C# conventions
• Use async/await for I/O operations
• Keep controllers thin, business logic in services

Frontend (TypeScript):

• Use TypeScript strict mode
• Prefer TanStack Query for data fetching
• Follow the existing component structure

1. Create a feature branch from main
2. Make your changes with clear commit messages
3. Ensure all CI checks pass
4. Request review

MIT