Skip to content

Commit 68c8e29

Browse files
gildesmaraisgildesmarais
committed
dev: improve DX for development & contributing
1 parent c9b5c90 commit 68c8e29

File tree

8 files changed

+300
-5
lines changed

8 files changed

+300
-5
lines changed

‎.cursor/rules/read-copilot-instructions.mdc‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
---
2+
description: Read and follow .github/copilot-instructions.md for this repo
3+
alwaysApply: true
4+
---
5+
6+
Before assisting, open and read `.github/copilot-instructions.md`.
7+
Follow it as the authoritative source for coding practices, docs style, security, and compliance for this project.
8+
9+
If the file is missing, say so, ask to create it, and proceed with safe defaults.
10+
When “Copilot” is mentioned in that file, interpret it as referring to **you (Cursor)**.
11+
Summarize the relevant sections into your working context before you act.
12+

‎.devcontainer/devcontainer.json‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
{
2+
"name": "html2rss-web",
3+
"image": "mcr.microsoft.com/devcontainers/ruby:3.4",
4+
"features": {
5+
"ghcr.io/devcontainers/features/git:1": {},
6+
"ghcr.io/devcontainers/features/github-cli:1": {}
7+
},
8+
"customizations": {
9+
"vscode": {
10+
"extensions": [
11+
"redhat.vscode-yaml",
12+
"esbenp.prettier-vscode",
13+
"github.copilot",
14+
"github.copilot-chat",
15+
"shopify.ruby-lsp"
16+
],
17+
"settings": {
18+
"ruby.rubocop.executePath": "bundle exec",
19+
"ruby.format": "rubocop",
20+
"ruby.lint": {
21+
"rubocop": true
22+
},
23+
"files.associations": {
24+
"*.erb": "erb"
25+
}
26+
}
27+
}
28+
},
29+
"postCreateCommand": "make setup",
30+
"postStartCommand": "echo '🚀 html2rss-web Development Environment Ready!' && echo '' && echo '📋 Quick Start Commands:' && echo ' make dev # Start development server' && echo ' make test # Run tests' && echo ' make lint # Run linter' && echo ' make fix # Auto-fix linting issues' && echo ' make help # Show all commands' && echo '' && echo '🌐 Server will be available at: http://localhost:3000' && echo '📁 Project files are in: /workspaces/html2rss-web' && echo '' && echo '💡 Tip: Use Ctrl+C to stop the development server' && echo ''",
31+
"forwardPorts": [
32+
3000
33+
],
34+
"portsAttributes": {
35+
"3000": {
36+
"label": "html2rss-web",
37+
"onAutoForward": "notify"
38+
}
39+
},
40+
"remoteUser": "vscode"
41+
}

‎.github/copilot-instructions.md‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
# html2rss-web AI Agent Instructions
2+
3+
## Overview
4+
5+
- Ruby web app that converts websites into RSS 2.0 feeds.
6+
- Built with **Roda**, using the **html2rss** gem (+ `html2rss-configs`).
7+
- **Principle:** _All features must work without JavaScript._ JS is only progressive enhancement.
8+
9+
## Core Rules
10+
11+
- ✅ Use **Roda routing with `hash_branch`**. Keep routes small.
12+
- ✅ Put logic into `helpers/` or `app/`, not inline in routes.
13+
- ✅ Validate all inputs. Pass outbound requests through **SSRF filter**.
14+
- ✅ Add caching headers where appropriate (`Rack::Cache`).
15+
- ✅ Errors: friendly messages for users, detailed logging internally.
16+
- ✅ CSS: Water.css + small overrides in `public/styles.css`.
17+
- ✅ Specs: RSpec, unit + integration, use VCR for external requests.
18+
19+
## Don’t
20+
21+
- ❌ Don’t depend on JS for core flows.
22+
- ❌ Don’t bypass SSRF filter or weaken CSP.
23+
- ❌ Don’t add databases, ORMs, or background jobs.
24+
- ❌ Don’t leak stack traces or secrets in responses.
25+
26+
## Project Structure
27+
28+
- `app.rb` – main Roda app
29+
- `app/` – core modules (config, cache, ssrf, health)
30+
- `routes/` – route handlers (`hash_branch`)
31+
- `helpers/` – pure helper modules (`module_function`)
32+
- `views/` – ERB templates
33+
- `public/` – static assets (CSS/JS, minimal)
34+
- `config/feeds.yml` – feed definitions
35+
- `spec/` – RSpec tests + VCR cassettes
36+
37+
## Environment
38+
39+
- `RACK_ENV` – environment
40+
- `AUTO_SOURCE_ENABLED`, `AUTO_SOURCE_USERNAME`, `AUTO_SOURCE_PASSWORD`, `AUTO_SOURCE_ALLOWED_ORIGINS`
41+
- `HEALTH_CHECK_USERNAME`, `HEALTH_CHECK_PASSWORD`
42+
- `SENTRY_DSN` (optional)
43+
44+
## Style
45+
46+
- Add `# frozen_string_literal: true`
47+
- Follow RuboCop style
48+
- YARD doc comments for public methods

‎.gitignore‎

Lines changed: 65 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,65 @@
1-
tmp/*
2-
!tmp/.keep
3-
.yardoc
4-
coverage
5-
spec/examples.txt
1+
# See https://help.github.com/articles/ignoring-files for more about ignoring files.
2+
#
3+
# If you find yourself ignoring temporary files generated by your text editor
4+
# or operating system, you probably want to add a global ignore instead:
5+
# git config --global core.excludesfile '~/.gitignore_global'
6+
7+
# Ignore bundler config.
8+
/.bundle
9+
10+
# Ignore the default SQLite database.
11+
/db/*.sqlite3
12+
/db/*.sqlite3-journal
13+
14+
# Ignore all logfiles and tempfiles.
15+
/log/*
16+
/tmp/*
17+
!/log/.keep
18+
!/tmp/.keep
19+
20+
# Ignore pidfiles, but keep the directory.
21+
/tmp/pids/*
22+
!/tmp/pids/
23+
!/tmp/pids/.keep
24+
25+
# Ignore uploaded files in development.
26+
/storage/*
27+
!/storage/.keep
28+
29+
# Ignore master key for decrypting credentials and more.
30+
/config/master.key
31+
32+
# Ignore environment variables
33+
.env
34+
.env.local
35+
.env.development.local
36+
.env.test.local
37+
.env.production.local
38+
39+
# Ignore coverage reports
40+
/coverage/
41+
42+
# Ignore VCR cassettes (they should be committed)
43+
# /spec/fixtures/vcr_cassettes/
44+
45+
# Ignore IDE files
46+
.vscode/
47+
.idea/
48+
*.swp
49+
*.swo
50+
*~
51+
52+
# Ignore OS generated files
53+
.DS_Store
54+
.DS_Store?
55+
._*
56+
.Spotlight-V100
57+
.Trashes
58+
ehthumbs.db
59+
Thumbs.db
60+
61+
# Ignore rack cache
62+
/tmp/rack-cache-*
63+
64+
# Ignore simplecov
65+
/coverage/

‎Makefile‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
# frozen_string_literal: true
2+
3+
.PHONY: help test lint fix setup dev clean
4+
5+
# Default target
6+
help: ## Show this help message
7+
@echo "html2rss-web Development Commands"
8+
@echo "================================="
9+
@echo ""
10+
@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-15s\033[0m %s\n", $$1, $$2}'
11+
12+
setup: ## Full development setup
13+
@echo "Setting up development environment..."
14+
bundle install
15+
@if [ ! -f .env ]; then \
16+
cp .env.example .env 2>/dev/null || echo "RACK_ENV=development" > .env; \
17+
echo "Created .env file"; \
18+
fi
19+
@mkdir -p tmp/rack-cache-body tmp/rack-cache-meta
20+
@echo "Setup complete!"
21+
22+
dev: ## Start development server
23+
@echo "Starting development server..."
24+
@echo "Server will be available at: http://localhost:3000"
25+
@echo "Press Ctrl+C to stop"
26+
@bin/dev
27+
28+
test: ## Run tests
29+
bundle exec rspec
30+
31+
lint: ## Run linter
32+
bundle exec rubocop
33+
34+
fix: ## Auto-fix linting issues
35+
bundle exec rubocop -a
36+
37+
clean: ## Clean temporary files
38+
@rm -rf tmp/rack-cache-* coverage/
39+
@echo "Clean complete!"

‎README.md‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,45 @@ The functionality of scraping websites and building the RSS feeds is provided by
1818

1919
For full documentation, please see the [html2rss-web documentation](https://html2rss.github.io/web-application/).
2020

21+
## Development
22+
23+
### Quick Start with GitHub Codespaces
24+
25+
The easiest way to get started is using GitHub Codespaces:
26+
27+
1. Fork this repository
28+
2. Click "Code" → "Codespaces" → "Create codespace on [your-username]/html2rss-web"
29+
3. Wait for the codespace to build (it will automatically run `bundle install`)
30+
4. The development server will be available at the forwarded port (usually 3000)
31+
32+
### Local Development
33+
34+
1. **Clone and setup:**
35+
```bash
36+
git clone https://github.com/html2rss/html2rss-web.git
37+
cd html2rss-web
38+
make setup
39+
```
40+
41+
2. **Start development server:**
42+
```bash
43+
make dev
44+
```
45+
46+
The application will be available at `http://localhost:3000`.
47+
48+
### Development Commands
49+
50+
| Command | Description |
51+
| ------------ | --------------------------- |
52+
| `make help` | Show all available commands |
53+
| `make setup` | Full development setup |
54+
| `make dev` | Start development server |
55+
| `make test` | Run tests |
56+
| `make lint` | Run linter |
57+
| `make fix` | Auto-fix linting issues |
58+
| `make clean` | Clean temporary files |
59+
2160
## Contributing
2261

2362
Contributions are welcome! Please see the [contributing guide](https://html2rss.github.io/get-involved/contributing) for more information.

‎bin/dev‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
#!/usr/bin/env bash
2+
# frozen_string_literal: true
3+
4+
# Development server startup script
5+
set -e
6+
7+
# Load environment variables if .env file exists
8+
if [ -f .env ]; then
9+
export $(cat .env | grep -v '^#' | xargs)
10+
fi
11+
12+
# Set default environment
13+
export RACK_ENV=${RACK_ENV:-development}
14+
15+
echo "Starting html2rss-web in development mode..."
16+
echo "Environment: $RACK_ENV"
17+
echo "Port: ${PORT:-3000}"
18+
19+
# Start the development server
20+
bundle exec rackup -p ${PORT:-3000} -o 0.0.0.0

‎bin/setup‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
#!/usr/bin/env bash
2+
# frozen_string_literal: true
3+
4+
# Development environment setup script
5+
set -e
6+
7+
echo "Setting up html2rss-web development environment..."
8+
9+
# Check if Ruby version is correct
10+
ruby_version=$(ruby -v | cut -d' ' -f2 | cut -d'p' -f1)
11+
echo "Ruby version: $ruby_version"
12+
13+
# Install dependencies
14+
echo "Installing dependencies..."
15+
bundle install
16+
17+
# Create .env file if it doesn't exist
18+
if [ ! -f .env ]; then
19+
echo "Creating .env file from .env.example..."
20+
cp .env.example .env
21+
echo "Please edit .env file with your configuration"
22+
fi
23+
24+
# Create necessary directories
25+
echo "Creating necessary directories..."
26+
mkdir -p tmp/rack-cache-body
27+
mkdir -p tmp/rack-cache-meta
28+
29+
# Run tests to verify setup
30+
echo "Running tests to verify setup..."
31+
bundle exec rspec
32+
33+
echo "Setup complete! You can now run:"
34+
echo " bin/dev # Start development server"
35+
echo " bundle exec rspec # Run tests"
36+
echo " bundle exec rubocop # Run linter"

0 commit comments

Comments
 (0)