StarPunk/docs/projectplan/BACKLOG.md

StarPunk Backlog

Last Updated: 2025-12-17

Recently Completed

v1.5.0 - Quality of Life Improvements (Complete)

• Timestamp-based default slug generation (ADR-062)
• Debug file management with automatic cleanup
• Filename sanitization in debug paths
• N+1 query fix for feed generation (batch media loading)
• Atomic variant generation (temp file pattern)
• MPO format test coverage
• Test suite cleanup (removed 5 broken tests, fixed brittle assertions)

v1.4.2 - HEIC/MPO Support and Dimension Limit Increase (Complete)

• HEIC/HEIF format detection and conversion to JPEG
• MPO (Multi-Picture Object) format support for iPhone depth photos
• MAX_DIMENSION increased from 4096 to 12000 pixels
• Enhanced debug logging for failed uploads

v1.4.0/v1.4.1 - Media Variants (Complete)

• Image variant generation (thumb, small, medium, large)
• Micropub media endpoint
• Enhanced feed media support with Media RSS

v1.3.0 - Microformats2 Compliance and Tags (Complete)

• Tag/Category system with database schema
• p-category microformats2 markup
• h-feed required properties (name, author, url)
• Author h-card with photo and bio
• u-photo placement outside e-content
• mf2py validation test suite

Priority Levels

• Critical - Items that break existing functionality
• High - Important features or fixes
• Medium - Planned features
• Low - Nice-to-have, deferred indefinitely

---

Critical

No critical items

---

High

POSSE

• Native syndication to social networks
• Supported networks:
  • First iteration:
    • Mastodon (and compatible services)
    • Bluesky
  • Second iteration
    • TBD
• Solution should include a configuration UI for setup

---

Medium

PKCE Support for IndieAuth

• Description: Implement PKCE (Proof Key for Code Exchange) per RFC 7636 for IndieAuth authentication. Some IndieAuth providers (like indielogin.com) require PKCE. While not required by the W3C IndieAuth spec, it's a security best practice.
• Source: Hotfix 2025-12-17 scoping decision
• Approach:
  • Add code_verifier column to auth_state table
  • Add PKCE helper functions (_generate_pkce_verifier(), _generate_pkce_challenge())
  • Include code_challenge and code_challenge_method=S256 in authorization request
  • Include code_verifier in token exchange request
• Reference: Commit 5e50330 had working PKCE implementation that was removed in a3bac86
• Priority: Medium (adds security, enables compatibility with providers that require PKCE)

N+1 Query Patterns - Deferred Locations

• Description: N+1 query patterns exist in multiple locations beyond _get_cached_notes(). These are lower priority due to lower traffic or single-note contexts.
• Deferred Locations:
  1. Admin Edit Page (starpunk/routes/admin.py line 186): Single note context, low impact
  2. Tag Archive Pages (starpunk/routes/public.py lines 243-248, 332): Lower traffic than main feed
  3. Individual Note View (starpunk/routes/public.py lines 282-289): Single note, negligible
  4. Note Model Property (starpunk/models.py lines 380-381): On-demand loading, acceptable
  5. Tag Module (starpunk/tags.py line 197): Internal helper, low volume
• Source: Architect Review, v1.5.0 scoping decision
• Approach: Future optimization if performance issues arise. Consider batch loading patterns established in v1.5.0.
• Priority: Deferred to post-v1.5.0

Rate Limiting on Upload Endpoints

• Description: No rate limiting exists on media upload endpoints, making them vulnerable to abuse.
• Location: /admin/new (admin.py), /media (micropub.py)
• Source: Architect Review (Security Assessment)
• Approach: Implement Flask-Limiter or similar rate limiting middleware for upload routes.

Tag Enhancements (v1.3.0 Follow-up)

• Tag pagination on archive pages (when note count exceeds threshold)
• Tag autocomplete in admin interface
• Tag-filtered feeds (e.g., /feed.rss?tag=python, /tags/python/feed.rss)
• Fix: Empty tag field in admin should remove all tags (currently may leave unchanged)

Tag-Filtered Feeds

• Filter feeds by tag (e.g., /feed.rss?tag=python)
• Dedicated tag feed URLs (e.g., /tags/python/feed.rss)
• Support all three formats (RSS, Atom, JSON Feed)
• Cache management for filtered feeds

Webmentions

• Receive endpoint
• Send on publish
• Display received mentions
• Moderation interface

Reply Contexts

• In-reply-to support
• Like/repost posts
• Bookmark posts

Media Uploads Enhancements

• File management interface
• Thumbnail generation
• CDN integration (optional)

Photo Posts

• Instagram-like photo notes
• Gallery views
• EXIF data preservation

Audio/Podcast Support

• Podcast RSS with iTunes namespace
• Audio duration extraction
• Episode metadata support
• Apple/Google podcast compatibility
• See: ADR-059

Video Support

• Video upload handling
• Poster image generation
• Video in Media RSS feeds
• HTML5 video embedding

---

Low

HEIC/MPO Conversion Quality Not Configurable

• Description: HEIC and MPO to JPEG conversion uses hardcoded quality=95. Users with different quality/size tradeoff preferences cannot adjust this.
• Location: starpunk/media.py line 157
• Source: Developer Review (M3)
• Approach: Add HEIC_CONVERSION_QUALITY config variable with 95 as default.

MAX_DIMENSION Not Configurable

• Description: MAX_DIMENSION = 12000 is a hardcoded constant. Cannot adjust limit without code change.
• Location: starpunk/media.py line 41
• Source: Developer Review (M4)
• Approach: Make configurable via config variable, keeping 12000 as default.

Animated WebP Not Detected

• Description: Animated GIF detection exists but animated WebP is not handled, potentially bypassing animated image size checks.
• Location: starpunk/media.py (validate_image function)
• Source: Architect Review (Issue 2.2.2)
• Approach: Add animated WebP detection similar to existing GIF handling.

Caption Not Escaped in RSS HTML

• Description: In RSS generation, caption is used directly in alt attribute without HTML escaping. Could break markup if caption contains " or other special characters.
• Location: starpunk/feeds/rss.py line 136
• Source: Architect Review (Issue 2.2.10)
• Approach: Use html.escape() for caption when generating HTML content.

Incomplete MPO Documentation

• Description: Code comment says "extract primary image" but doesn't explain the multi-frame nature of MPO files (contain multiple images for 3D or depth maps).
• Location: starpunk/media.py lines 163-165
• Source: Developer Review (M5)
• Approach: Enhance inline comment to document that MPO files contain multiple frames and only the primary frame is extracted.

Module Docstring Stale

• Description: Module docstring still states "4096x4096 max dimensions" but MAX_DIMENSION was updated to 12000 in v1.4.2.
• Location: starpunk/media.py lines 1-12
• Source: Architect Review (Issue 1.2.1)
• Approach: Update docstring to reflect current 12000px limit.

Flaky Migration Race Condition Tests

• Improve test_migration_race_condition.py::TestGraduatedLogging::test_debug_level_for_early_retries
• Test expects DEBUG retry messages but passes when migration succeeds without retries
• May need to mock or force retry conditions for reliable testing

Deferred Indefinitely

• Static Site Generation - Conflicts with dynamic Micropub
• Multi-language UI - Low priority for single-user system
• Advanced Analytics - Privacy concerns, use external tools
• Comments System - Use Webmentions instead
• WYSIWYG Editor - Markdown is sufficient
• Mobile App - Web interface is mobile-friendly