StarPunk/CHANGELOG.md

Changelog

All notable changes to StarPunk will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

Unreleased

[0.6.0] - 2025-11-19

Added

• RSS Feed Generation: Standards-compliant RSS 2.0 feed for published notes
• RSS feed module (starpunk/feed.py) with feed generation functions
• GET /feed.xml route for RSS feed access
• Server-side feed caching (5-minute default, configurable)
• ETag support for efficient feed updates
• Cache-Control headers for client-side caching
• RSS feed auto-discovery link in HTML templates
• RSS link in site navigation
• Comprehensive RSS feed test suite (44 tests)

Production Container

• Containerfile: Multi-stage build for optimized image size (174MB)
• Container Orchestration: Podman and Docker Compose compatible
• Health Check Endpoint: GET /health for container monitoring
• Gunicorn WSGI Server: Production-ready with 4 workers
• Security: Non-root user execution (starpunk:1000)
• Volume Mounts: Data persistence for notes and database
• Reverse Proxy Configs: Caddy and Nginx examples with auto-HTTPS
• Container Documentation: Comprehensive deployment guide

Configuration

• FEED_MAX_ITEMS: Maximum items in RSS feed (default: 50)
• FEED_CACHE_SECONDS: Server-side cache duration in seconds (default: 300)
• VERSION: Application version for health checks (default: 0.6.0)
• ENVIRONMENT: Deployment environment (development/production)
• WORKERS: Number of Gunicorn workers (default: 4)
• WORKER_TIMEOUT: Gunicorn worker timeout in seconds (default: 30)
• MAX_REQUESTS: Max requests per worker before restart (default: 1000)

Features

• RSS 2.0 compliant XML generation using feedgen library
• RFC-822 date formatting for RSS pubDate elements
• Intelligent note title extraction (first line or timestamp fallback)
• HTML content in CDATA sections for feed readers
• Atom self-link for feed discovery
• Only published notes included in feed
• Absolute URLs for all feed item links

Testing

• 88% overall test coverage (up from 87%)
• 96% coverage for feed module
• 449/450 tests passing (99.78% pass rate)
• Test isolation with automatic cache clearing
• Unicode and special character handling verified

Standards Compliance

• RSS 2.0 specification compliant
• RFC-822 date format for timestamps
• IndieWeb feed discovery support
• W3C Feed Validator compatible

Container Features

• Multi-stage build optimizes image size (Python 3.11-slim base)
• uv package manager for fast dependency installation
• Health checks verify database connectivity and filesystem access
• Resource limits prevent container resource exhaustion
• Log rotation (10MB max, 3 files) prevents disk space issues
• Automatic restart policy for reliability
• SELinux compatibility with volume mount flags

Deployment

• Podman-compatible with --userns=keep-id for proper permissions
• Docker-compatible with standard volume mounts
• Reverse proxy examples for Caddy (auto-HTTPS) and Nginx
• HTTPS required for IndieAuth in production
• Complete backup and restore procedures documented
• Performance tuning guide for worker configuration

Related Documentation

• ADR-014: RSS Feed Implementation Strategy
• ADR-015: Phase 5 Implementation Approach
• Phase 5 design documentation
• Phase 5 quick reference guide
• Container deployment guide

[0.5.2] - 2025-11-18

Fixed

• Admin Routes: Fixed delete route to return HTTP 404 when attempting to delete nonexistent notes, per ADR-012 (HTTP Error Handling Policy)
• Added existence check to delete route before attempting deletion, consistent with edit route pattern
• Fixed test for delete nonexistent note to match ADR-012 compliance (expect 404 status, not 200 with follow_redirects)

Changed

• Delete route now checks note existence before deletion and returns 404 with "Note not found" flash message for nonexistent notes
• Test suite: 405/406 tests passing (99.75%)

[0.5.1] - 2025-11-18

Fixed

• CRITICAL: Fixed authentication redirect loop caused by cookie name collision between Flask's session and StarPunk's auth token
• Renamed authentication cookie from session to starpunk_session to avoid conflict with Flask's server-side session mechanism used by flash messages
• All authentication flows (dev login, IndieAuth, logout) now work correctly without redirect loops
• Flash messages now display properly without interfering with authentication state

Changed

• BREAKING CHANGE: Authentication cookie renamed from session to starpunk_session
  • Existing authenticated users will be logged out and need to re-authenticate after upgrade
  • This is an unavoidable breaking change required to fix the critical bug

Documentation

• Established cookie naming convention standard (starpunk_* prefix for all application cookies)
• Created implementation report documenting the root cause and fix

[0.5.0] - 2025-11-19

Added

• Development authentication module (starpunk/dev_auth.py) for local testing
• is_dev_mode() function to check development mode status
• create_dev_session() function for authentication bypass in development
• Web interface templates with Microformats2 markup
• Admin dashboard, note editor, and login pages
• Public note display and RSS feed support

Fixed

• Phase 4 test suite now passing (400/406 tests, 98.5% pass rate)
• Template encoding issues (removed corrupted Unicode characters)
• Test database initialization using tmp_path fixtures
• Route URL patterns (trailing slash consistency)
• Template variable naming (g.user_me → g.me)
• Function name mismatches in tests (get_all_notes → list_notes)
• URL builder endpoint name (auth.login → auth.login_form)
• Session verification return type handling in tests
• Flake8 code quality issues (unused imports, f-strings)

Security

• Development authentication includes prominent warning logging
• DEV_MODE validation ensures DEV_ADMIN_ME is set
• Production mode validation ensures ADMIN_ME is set

Testing

• 87% overall test coverage
• All Phase 4 route and template tests functional
• Proper test isolation with temporary databases
• Fixed test context usage (test_request_context)

Code Quality

• All code formatted with Black
• Passes Flake8 validation
• Removed unused imports and fixed f-string warnings

0.4.0 - 2025-11-18

Added

• Authentication module (starpunk/auth.py) with IndieLogin support
• Core authentication functions: initiate_login, handle_callback, create_session, verify_session, destroy_session
• require_auth decorator for protecting admin routes
• Custom authentication exceptions (AuthError, InvalidStateError, UnauthorizedError, IndieLoginError)
• CSRF protection via state tokens
• Secure session management with SHA-256 token hashing
• Session metadata tracking (user agent, IP address)
• Automatic cleanup of expired sessions and state tokens
• URL validation utility function (is_valid_url)
• Comprehensive authentication test suite (37 tests, 96% coverage)

Changed

• Updated sessions table schema to use session_token_hash instead of plaintext tokens
• Added user_agent and ip_address fields to sessions table
• Added redirect_uri field to auth_state table
• Added indexes for authentication performance (session_token_hash, me)

Security

• Token hashing with SHA-256 for secure storage
• CSRF protection with single-use state tokens
• Cryptographically secure token generation (secrets module)
• SQL injection prevention with prepared statements
• Comprehensive security logging

0.3.0 - 2025-11-18

Added

• Notes management module (starpunk/notes.py) with CRUD operations
• Custom exceptions for note operations (NoteError, NoteNotFoundError, InvalidNoteDataError, NoteSyncError)
• File and database synchronization with transaction safety
• Support for soft and hard note deletion
• Comprehensive test suite for notes module (85 tests, 86% coverage)
• Database schema support for soft deletes (deleted_at column)
• Slug uniqueness enforcement with random suffix generation
• Content hash calculation for integrity verification

Changed

• Updated database schema to include deleted_at column in notes table
• Added index on deleted_at for query performance

0.1.0 - 2024-11-18

Added

• Initial project structure
• Core architecture design
• Technology stack selection (Flask, SQLite, file-based storage)
• Architecture Decision Records (ADR-001 through ADR-007)
• Development documentation and standards
• Phase 1.1 design: Core utilities specification
• Python coding standards
• Documentation organization structure

Documentation

• Complete architecture overview
• Technology stack documentation
• ADR-001: Python web framework (Flask)
• ADR-002: Flask extensions (minimal approach)
• ADR-003: Frontend technology (server-side rendering)
• ADR-004: File-based note storage
• ADR-005: IndieLogin authentication
• ADR-006: Python virtual environment (uv)
• ADR-007: Slug generation algorithm
• ADR-008: Versioning strategy