Implement automatic generation of multiple image sizes for responsive
delivery and enhanced feed optimization.
Changes:
- Add migration 009 for media_variants table with CASCADE delete
- Define variant specs: thumb (150x150 crop), small (320px), medium (640px), large (1280px)
- Implement generate_variant() with center crop for thumbnails and aspect-preserving resize
- Implement generate_all_variants() with try/except cleanup, pass year/month/optimized_bytes explicitly
- Update save_media() to generate all variants after saving original
- Update get_note_media() to include variants dict (backwards compatible - only when variants exist)
- Record original as 'original' variant type
Technical details:
- Variants use explicit year/month parameters to avoid fragile path traversal
- Pass optimized_bytes to avoid redundant file I/O
- File cleanup on variant generation failure
- Skip generating variants larger than source image
- variants key only added to response when variants exist (pre-v1.4.0 compatibility)
All existing tests pass. Phase 2 complete.
Per design document: /home/phil/Projects/starpunk/docs/design/v1.4.0/media-implementation-design.md
Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Implement tiered resize strategy for large images per v1.4.0 design:
Changes:
- Increase MAX_FILE_SIZE from 10MB to 50MB
- Add MAX_OUTPUT_SIZE constant (10MB target after optimization)
- Add MIN_QUALITY and MIN_DIMENSION constants
- Add get_optimization_params() for tiered strategy:
- <=10MB: 2048px max, 95% quality
- 10-25MB: 1600px max, 90% quality
- 25-50MB: 1280px max, 85% quality
- Update optimize_image() signature to return 4-tuple (img, w, h, bytes)
- Implement iterative quality reduction if output >10MB
- Add animated GIF detection and size check in validate_image()
- Update save_media() to use new optimize_image() return value
- Fix GIF format preservation during optimization
- Update tests to match new optimize_image() signature
All existing tests pass. Ready for Phase 2 (Image Variants).
Following design in:
/home/phil/Projects/starpunk/docs/design/v1.4.0/media-implementation-design.md
Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
The Note model has a `tags` property that uses `_cached_tags` internally.
Setting `tags` directly via object.__setattr__ conflicts with the property.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Implements tag/category rendering in RSS 2.0, Atom 1.0, and JSON Feed 1.1
syndication feeds. Tags added in v1.3.0 are now visible to feed readers.
Changes:
- Load tags in feed generation (_get_cached_notes)
- Add <category> elements to RSS 2.0 feeds
- Add <category term/label> to Atom 1.0 feeds
- Add "tags" array to JSON Feed 1.1 items
- Omit empty tags field in JSON Feed (minimal approach)
Standards compliance:
- RSS 2.0: category element with display name
- Atom 1.0: RFC 4287 category with term and label attributes
- JSON Feed 1.1: tags array of strings
Per design: docs/design/v1.3.1/feed-tags-design.md
Implementation: docs/design/v1.3.1/2025-12-10-feed-tags-implementation.md
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Promoting v1.3.0-rc.1 to stable release.
Changes:
- Updated version in starpunk/__init__.py to 1.3.0
- Updated CHANGELOG.md header to v1.3.0
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Release candidate v1.3.0-rc.1 with tags/categories and enhanced Microformats2 support.
Major features:
- Complete tag/category system with Micropub support
- Strict Microformats2 compliance (p-category, h-feed properties)
- Tag archive pages at /tags/{tag}
- Enhanced h-entry markup with dt-updated
- Proper h-feed structure on collection pages
Generated with Claude Code
Co-Authored-By: Claude <noreply@anthropic.com>
v1.3.1 "Syndicate Tags":
- RSS/Atom/JSON Feed category/tag support
v1.4.0 "Media":
- Micropub media endpoint (W3C compliant)
- Large image support (>10MB auto-resize)
- Enhanced feed media (image variants, full Media RSS)
Also adds tag-filtered feeds to backlog at medium priority.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Release candidate for v1.3.0 with tags/categories and enhanced Microformats2 support.
Features:
- Tag/category system with Micropub support
- Strict Microformats2 compliance (p-category, h-feed)
- Tag archive pages
- Enhanced h-entry markup
Generated with Claude Code
Co-Authored-By: Claude <noreply@anthropic.com>
Implement Phase 3 of v1.3.0 tags feature per microformats-tags-design.md:
Routes (starpunk/routes/public.py):
- Add /tag/<tag> archive route with normalization and 404 handling
- Pre-load tags in index route for all notes
- Pre-load tags in note route for individual notes
Admin (starpunk/routes/admin.py):
- Parse comma-separated tag input in create route
- Parse tag input in update route
- Pre-load tags when displaying edit form
- Empty tag field removes all tags
Templates:
- Add tag input field to templates/admin/edit.html
- Add tag input field to templates/admin/new.html
- Use Jinja2 map filter to display existing tags
Implementation details:
- Tag URL parameter normalized to lowercase before lookup
- Tags pre-loaded using object.__setattr__ pattern (like media)
- parse_tag_input() handles trim, dedupe, normalization
- All existing tests pass (micropub categories, admin routes)
Per architect design:
- No pagination on tag archives (acceptable for v1.3.0)
- No autocomplete in admin (out of scope)
- Follows existing media loading patterns
Generated with Claude Code
Co-Authored-By: Claude <noreply@anthropic.com>
Implement Phase 2 of v1.3.0 per microformats-tags-design.md
Template Updates:
- templates/index.html: Add h-feed properties (u-url, enhanced p-author with u-photo/p-note, feed-level u-photo)
- templates/index.html: Add p-category markup with rel="tag" to note previews
- templates/note.html: Add p-category markup with rel="tag" for tags
- templates/note.html: Enhance author h-card with u-photo and p-note (hidden for parsers)
- templates/note.html: Document u-photo placement outside e-content per draft spec
- templates/tag.html: Create new tag archive template with h-feed structure
Key Decisions Applied:
- Tags ordered alphabetically by display_name (ready for backend)
- rel="tag" on all p-category links per microformats2 spec
- Author bio (p-note) hidden with display: none for semantic parsing
- Dual u-photo elements intentional for parser compatibility
- Graceful fallback when author photo/bio not available
Templates are backward compatible and ready for backend integration.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Implements tag/category system backend following microformats2 p-category specification.
Database changes:
- Migration 008: Add tags and note_tags tables
- Normalized tag storage (case-insensitive lookup, display name preserved)
- Indexes for performance
New module:
- starpunk/tags.py: Tag management functions
- normalize_tag: Normalize tag strings
- get_or_create_tag: Get or create tag records
- add_tags_to_note: Associate tags with notes (replaces existing)
- get_note_tags: Retrieve note tags (alphabetically ordered)
- get_tag_by_name: Lookup tag by normalized name
- get_notes_by_tag: Get all notes with specific tag
- parse_tag_input: Parse comma-separated tag input
Model updates:
- Note.tags property (lazy-loaded, prefer pre-loading in routes)
- Note.to_dict() add include_tags parameter
CRUD updates:
- create_note() accepts tags parameter
- update_note() accepts tags parameter (None = no change, [] = remove all)
Micropub integration:
- Pass tags to create_note() (tags already extracted by extract_tags())
- Return tags in q=source response
Per design doc: docs/design/v1.3.0/microformats-tags-design.md
Generated with Claude Code
Co-Authored-By: Claude <noreply@anthropic.com>
Promote v1.2.0-rc.2 to stable v1.2.0 release
- Merged rc.1 and rc.2 changelog entries
- Updated version in starpunk/__init__.py
- All features tested in production
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
## Added
- Feed Media Enhancement with Media RSS namespace support
- RSS enclosure, media:content, media:thumbnail elements
- JSON Feed image field for first image
- ADR-059: Full feed media standardization roadmap
## Fixed
- Media display on homepage (was only showing on note pages)
- Responsive image sizing with CSS constraints
- Caption display (now alt text only, not visible)
- Logging correlation ID crash in non-request contexts
## Documentation
- Feed media design documents and implementation reports
- Media display fixes design and validation reports
- Updated ROADMAP with v1.3.0/v1.4.0 media plans
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Fixes logging errors during app initialization and in background threads.
The correlation_id filter must be applied to handlers (not just loggers)
to ensure all log records have the correlation_id attribute before
formatting occurs.
Issue: Gunicorn workers were crashing due to missing correlation_id
in logs from memory monitor and other non-request contexts.
Promoting release candidate to stable production release.
v1.1.2 "Syndicate" - Enhanced Content Distribution
This release delivers comprehensive metrics instrumentation and multi-format
feed support (RSS, ATOM, JSON Feed) with content negotiation, caching, and
statistics dashboard.
No changes from v1.1.2-rc.2 - both production issues verified fixed.
Version: 1.1.2 (stable)
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Implements the metrics instrumentation that was missing from v1.1.1.
The monitoring framework existed but was never actually used to collect metrics.
Phase 1 Deliverables:
- Database operation monitoring with query timing
- HTTP request/response metrics with request IDs
- Memory monitoring daemon thread
- Business metrics framework
- Configuration management
Quality Metrics:
- 28/28 tests passing (100%)
- Zero architectural deviations
- <1% performance overhead achieved
- Production-ready implementation
Architect Review: APPROVED with excellent marks
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Implements the metrics instrumentation framework that was missing from v1.1.1.
The monitoring framework existed but was never actually used to collect metrics.
Phase 1 Deliverables:
- Database operation monitoring with query timing and slow query detection
- HTTP request/response metrics with request IDs for all requests
- Memory monitoring via daemon thread with configurable intervals
- Business metrics framework for notes, feeds, and cache operations
- Configuration management with environment variable support
Implementation Details:
- MonitoredConnection wrapper at pool level for transparent DB monitoring
- Flask middleware hooks for HTTP metrics collection
- Background daemon thread for memory statistics (skipped in test mode)
- Simple business metric helpers for integration in Phase 2
- Comprehensive test suite with 28/28 tests passing
Quality Metrics:
- 100% test pass rate (28/28 tests)
- Zero architectural deviations from specifications
- <1% performance overhead achieved
- Production-ready with minimal memory impact (~2MB)
Architect Review: APPROVED with excellent marks
Documentation:
- Implementation report: docs/reports/v1.1.2-phase1-metrics-implementation.md
- Architect review: docs/reviews/2025-11-26-v1.1.2-phase1-review.md
- Updated CHANGELOG.md with Phase 1 additions
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Critical production hotfix resolving template/data structure mismatch
that caused 500 error on /admin/dashboard endpoint.
Root Cause:
Template expects flat structure (metrics.database.count) but monitoring
module provides nested structure (metrics.by_type.database.count) with
different field names.
Solution:
Route Adapter Pattern - transformer function maps nested monitoring data
to flat template structure at presentation layer.
Changes:
- Add transform_metrics_for_template() function
- Update metrics_dashboard() route to use transformer
- Provide safe defaults for missing metrics data
- Handle edge cases (empty dict, missing by_type)
Testing:
- All 32 admin route tests passing
- Transformer validated with full test coverage
- No breaking changes
Documentation:
- Consolidated hotfix design in docs/design/
- Architectural review completed (approved)
- Implementation report updated
- Misclassified ADRs removed (ADR-022, ADR-060)
Technical Debt:
Adapter layer should be replaced with proper data contracts in v1.2.0
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Root cause: Template expects flat structure (metrics.database.count) but
monitoring module provides nested structure (metrics.by_type.database.count)
with different field names (avg_duration_ms vs avg).
Solution: Route Adapter Pattern - transformer function maps data structure
at presentation layer.
Changes:
- Add transform_metrics_for_template() function to admin.py
- Update metrics_dashboard() route to use transformer
- Provide safe defaults for missing/empty metrics data
- Handle all operation types: database, http, render
Testing: All 32 admin route tests passing
Documentation:
- Updated implementation report with actual fix details
- Created consolidated hotfix design documentation
- Architectural review by architect (approved with minor concerns)
Technical debt: Adapter layer should be replaced with proper data
contracts in v1.2.0
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
CRITICAL production hotfix for v1.1.1-rc.2 addressing route conflict
that caused 500 errors on /admin/dashboard.
Changes:
- Renamed metrics dashboard route from /admin/dashboard to /admin/metrics-dashboard
- Added defensive imports for missing monitoring module with graceful fallback
- Updated version to 1.1.1-rc.2
- Updated CHANGELOG with hotfix details
- Created implementation report in docs/reports/
Testing:
- All 32 admin route tests pass (100%)
- 593/600 total tests pass (7 pre-existing failures unrelated to hotfix)
- Verified backward compatibility maintained
Design:
- Follows ADR-022 architecture decision
- Implements design from docs/design/hotfix-v1.1.1-rc2-route-conflict.md
- No breaking changes - all existing url_for() calls work correctly
Production Impact:
- Resolves 500 error at /admin/dashboard
- Notes dashboard remains at /admin/ (unchanged)
- Metrics dashboard now at /admin/metrics-dashboard
- Graceful degradation when monitoring module unavailable
Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Phase 1 of v1.1.1 "Polish" release focusing on production readiness.
Implements logging, connection pooling, validation, and error handling.
Following specs in docs/design/v1.1.1/developer-qa.md and ADRs 052-055.
**Structured Logging** (Q3, ADR-054)
- RotatingFileHandler (10MB files, keep 10)
- Correlation IDs for request tracing
- All print statements replaced with logging
- Context-aware correlation IDs (init/request)
- Logs written to data/logs/starpunk.log
**Database Connection Pooling** (Q2, ADR-053)
- Connection pool with configurable size (default: 5)
- Request-scoped connections via Flask g object
- Pool statistics for monitoring
- WAL mode enabled for concurrency
- Backward compatible get_db() signature
**Configuration Validation** (Q14, ADR-052)
- Validates presence and type of all config values
- Fail-fast startup with clear error messages
- LOG_LEVEL enum validation
- Type checking for strings, integers, paths
- Non-zero exit status on errors
**Centralized Error Handling** (Q4, ADR-055)
- Moved handlers to starpunk/errors.py
- Micropub spec-compliant JSON errors
- HTML templates for browser requests
- All errors logged with correlation IDs
- MicropubError exception class
**Database Module Reorganization**
- Moved database.py to database/ package
- Separated init.py, pool.py, schema.py
- Maintains backward compatibility
- Cleaner separation of concerns
**Testing**
- 580 tests passing
- 1 pre-existing flaky test noted
- No breaking changes to public API
**Documentation**
- CHANGELOG.md updated with v1.1.1 entry
- Version bumped to 1.1.1
- Implementation report in docs/reports/
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Create developer-qa.md with architect's answers to all 20
implementation questions from the developer's design review.
This is the proper format for Q&A between developer and architect
during design review, not an ADR (which is for architectural
decisions with lasting impact).
Content includes:
- 6 critical questions with answers (config, db pool, logging, etc.)
- 8 important questions (session migration, Unicode, health checks)
- 6 nice-to-have clarifications (testing, monitoring, dashboard)
- Implementation phases (3 weeks)
- Integration guidance
Developer now has clear guidance to proceed with v1.1.1 implementation.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Comprehensive project plan updates to reflect v1.1.0 release:
New Documents:
- INDEX.md: Navigation index for all planning docs
- ROADMAP.md: Future version planning (v1.1.1 → v2.0.0)
- v1.1/RELEASE-STATUS.md: Complete v1.1.0 tracking
Updated Documents:
- v1/implementation-plan.md: Updated to v1.1.0, marked V1 100% complete
- v1.1/priority-work.md: Marked all items complete with actual effort
Changes:
- Fixed outdated status (was showing v0.9.5)
- Marked Micropub as complete (v1.0.0)
- Tracked all v1.1.0 features (search, slugs, migrations)
- Added clear roadmap for future versions
- Linked all ADRs and implementation reports
Project plan now fully synchronized with v1.1.0 "SearchLight" release.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Fix custom slug extraction bug where mp-slug was being filtered
out by normalize_properties() before it could be used.
Changes:
- Extract mp-slug from raw request data before normalization
- Add tests for both form-encoded and JSON formats
- All 13 Micropub tests passing
Fixes issue where Quill-specified custom slugs were ignored.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Update CHANGELOG.md with fix details in Unreleased section.
Create comprehensive implementation report documenting:
- Root cause analysis
- Code changes made
- Test results (all 13 Micropub tests pass)
- Deployment notes
Generated with Claude Code
Co-Authored-By: Claude <noreply@anthropic.com>
Fix bug where custom slugs (mp-slug) were being ignored because they
were extracted from normalized properties after being filtered out.
The root cause: normalize_properties() filters out all mp-* parameters
(line 139) because they're Micropub server extensions, not properties.
The old code tried to extract mp-slug from the normalized properties
dict, but it had already been removed.
The fix: Extract mp-slug directly from raw request data BEFORE calling
normalize_properties(). This preserves the custom slug through to
create_note().
Changes:
- Move mp-slug extraction to before property normalization (line 290-299)
- Handle both form-encoded (list) and JSON (string or list) formats
- Add comprehensive tests for custom slug with both request formats
- All 13 Micropub tests pass
Fixes the issue reported in production where Quill-specified slugs
were being replaced with auto-generated ones.
References:
- docs/reports/custom-slug-bug-diagnosis.md (architect's analysis)
- Micropub spec: mp-slug is a server extension parameter
Generated with Claude Code
Co-Authored-By: Claude <noreply@anthropic.com>
Implements full search functionality for StarPunk v1.1.0.
Search API Endpoint (/api/search):
- GET endpoint with query parameter (q) validation
- Pagination via limit (default 20, max 100) and offset parameters
- JSON response with results count and formatted search results
- Authentication-aware: anonymous users see published notes only
- Graceful handling of FTS5 unavailability (503 error)
- Proper error responses for missing/empty queries
Search Web Interface (/search):
- HTML search results page with Bootstrap-inspired styling
- Search form with HTML5 validation (minlength=2, maxlength=100)
- Results display with title, excerpt, date, and links
- Empty state for no results
- Error state for FTS5 unavailability
- Simple pagination (Next/Previous navigation)
Navigation Integration:
- Added search box to site navigation in base.html
- Preserves query parameter on results page
- Responsive design with emoji search icon
- Accessible with proper ARIA labels
FTS Index Population:
- Added startup check in __init__.py for empty FTS index
- Automatic rebuild from existing notes on first run
- Graceful degradation if population fails
- Logging for troubleshooting
Security Features:
- XSS prevention: HTML in search results properly escaped
- Safe highlighting: FTS5 <mark> tags preserved, user content escaped
- Query validation: empty queries rejected, length limits enforced
- SQL injection prevention via FTS5 query parser
- Authentication filtering: unpublished notes hidden from anonymous users
Testing:
- Added 41 comprehensive tests across 3 test files
- test_search_api.py: 12 tests for API endpoint validation
- test_search_integration.py: 17 tests for UI rendering and integration
- test_search_security.py: 12 tests for XSS, SQL injection, auth filtering
- All tests passing with no regressions
Implementation follows architect specifications from:
- docs/architecture/v1.1.0-validation-report.md
- docs/architecture/v1.1.0-feature-architecture.md
- docs/decisions/ADR-034-full-text-search.md
Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Release v1.1.0 "Searchlight" with search, custom slugs, and RSS fix.
Changes:
- Updated version to 1.1.0 in starpunk/__init__.py
- Updated CHANGELOG.md with v1.1.0 release notes
- Created implementation report in docs/reports/
Release highlights:
- Full-text search with FTS5 (core functionality complete)
- Custom slugs via Micropub mp-slug property
- RSS feed ordering fix (newest first)
- Migration system redesign (INITIAL_SCHEMA_SQL)
All features implemented and tested. Search UI to be completed
in immediate follow-up work.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
