feat: v1.2.0-rc.1 - IndieWeb Features Release Candidate

Complete implementation of v1.2.0 "IndieWeb Features" release. ## Phase 1: Custom Slugs - Optional custom slug field in note creation form - Auto-sanitization (lowercase, hyphens only) - Uniqueness validation with auto-numbering - Read-only after creation to preserve permalinks - Matches Micropub mp-slug behavior ## Phase 2: Author Discovery + Microformats2 - Automatic h-card discovery from IndieAuth identity URL - 24-hour caching with graceful fallback - Never blocks login (per ADR-061) - Complete h-entry, h-card, h-feed markup - All required Microformats2 properties - rel-me links for identity verification - Passes IndieWeb validation ## Phase 3: Media Upload - Upload up to 4 images per note (JPEG, PNG, GIF, WebP) - Automatic optimization with Pillow - Auto-resize to 2048px - EXIF orientation correction - 95% quality compression - Social media-style layout (media top, text below) - Optional captions for accessibility - Integration with all feed formats (RSS, ATOM, JSON Feed) - Date-organized storage with UUID filenames - Immutable caching (1 year) ## Database Changes - migrations/006_add_author_profile.sql - Author discovery cache - migrations/007_add_media_support.sql - Media storage ## New Modules - starpunk/author_discovery.py - h-card discovery and caching - starpunk/media.py - Image upload, validation, optimization ## Documentation - 4 new ADRs (056, 057, 058, 061) - Complete design specifications - Developer Q&A with 40+ questions answered - 3 implementation reports - 3 architect reviews (all approved) ## Testing - 56 new tests for v1.2.0 features - 842 total tests in suite - All v1.2.0 feature tests passing ## Dependencies - Added: mf2py (Microformats2 parser) - Added: Pillow (image processing) Version: 1.2.0-rc.1 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
2025-11-28 15:02:20 -07:00
parent 83739ec2c6
commit dd822a35b5
40 changed files with 6929 additions and 15 deletions
--- a/docs/decisions/ADR-056-no-selfhosted-indieauth.md
+++ b/docs/decisions/ADR-056-no-selfhosted-indieauth.md
@@ -0,0 +1,110 @@
+# ADR-056: Use External IndieAuth Provider (Never Self-Host)
+
+## Status
+**ACCEPTED** - This is a permanent, non-negotiable decision.
+
+## Context
+StarPunk is a minimal IndieWeb CMS focused on **content creation and syndication**, not identity infrastructure. The project philosophy demands that every line of code must justify its existence.
+
+The question of whether to implement self-hosted IndieAuth has been raised multiple times. This ADR documents the final, permanent decision on this matter.
+
+## Decision
+**StarPunk will NEVER implement self-hosted IndieAuth.**
+
+We will always rely on external IndieAuth providers such as:
+- indielogin.com (primary recommendation)
+- Other established IndieAuth providers
+
+This decision is **permanent and non-negotiable**.
+
+## Rationale
+
+### 1. Project Focus
+StarPunk's mission is to be a minimal CMS for publishing IndieWeb content. Our core competencies are:
+- Publishing notes with proper microformats
+- Generating RSS/Atom/JSON feeds
+- Implementing Micropub for content creation
+- Media management for content
+
+Identity infrastructure is explicitly **NOT** our focus.
+
+### 2. Complexity vs Value
+Implementing IndieAuth would require:
+- OAuth 2.0 implementation
+- Token management
+- Security considerations
+- Key storage and rotation
+- User profile management
+- Authorization code flows
+
+This represents hundreds or thousands of lines of code that don't serve our core mission of content publishing.
+
+### 3. Existing Solutions Work
+External IndieAuth providers like indielogin.com:
+- Are battle-tested
+- Handle security updates
+- Support multiple authentication methods
+- Are free to use
+- Align with IndieWeb principles of building on existing infrastructure
+
+### 4. Philosophy Alignment
+Our core philosophy states: "Every line of code must justify its existence. When in doubt, leave it out."
+
+Self-hosted IndieAuth cannot justify its existence in a minimal content-focused CMS.
+
+## Consequences
+
+### Positive
+- Dramatically reduced codebase complexity
+- No security burden for identity management
+- Faster development of content features
+- Clear project boundaries
+- User authentication "just works" via proven providers
+
+### Negative
+- Dependency on external service (indielogin.com)
+- Cannot function without internet connection to auth provider
+- No control over authentication user experience
+
+### Mitigations
+- Document clear setup instructions for using indielogin.com
+- Support multiple external providers for redundancy
+- Cache authentication tokens appropriately
+
+## Alternatives Considered
+
+### 1. Self-Hosted IndieAuth (REJECTED)
+**Why considered:** Full control over authentication
+**Why rejected:** Massive scope creep, violates project philosophy
+
+### 2. No Authentication (REJECTED)
+**Why considered:** Ultimate simplicity
+**Why rejected:** Single-user system still needs access control
+
+### 3. Basic Auth or Simple Password (REJECTED)
+**Why considered:** Very simple to implement
+**Why rejected:** Not IndieWeb compliant, poor user experience
+
+### 4. Hybrid Approach (REJECTED)
+**Why considered:** Optional self-hosted with external fallback
+**Why rejected:** Maintains complexity we're trying to avoid
+
+## Implementation Notes
+
+All authentication code should:
+1. Assume an external IndieAuth provider
+2. Never include hooks or abstractions for self-hosting
+3. Document indielogin.com as the recommended provider
+4. Include clear error messages when auth provider is unavailable
+
+## References
+- Project Philosophy: "Every line of code must justify its existence"
+- IndieAuth Specification: https://indieauth.spec.indieweb.org/
+- indielogin.com: https://indielogin.com/
+
+## Final Note
+This decision has been made after extensive consideration and multiple discussions. It is final.
+
+**Do not propose self-hosted IndieAuth in future architectural discussions.**
+
+The goal of StarPunk is **content**, not **identity**.
--- a/docs/decisions/ADR-057-media-attachment-model.md
+++ b/docs/decisions/ADR-057-media-attachment-model.md
@@ -0,0 +1,110 @@
+# ADR-057: Media Attachment Model
+
+## Status
+Accepted
+
+## Context
+The v1.2.0 media upload feature needed a clear model for how media relates to notes. Initial design assumed inline markdown image insertion (like a blog editor), but user feedback clarified that notes are more like social media posts (tweets, Mastodon toots) where media is attached rather than inline.
+
+Key insights from user:
+- "Notes are more like tweets, thread posts, mastodon posts etc. where the media is inserted is kind of irrelevant"
+- Media should appear at the TOP of notes when displayed
+- Text content should appear BELOW media
+- Multiple images per note should be supported
+
+## Decision
+We will implement a social media-style attachment model for media:
+
+1. **Database Design**: Use a junction table (`note_media`) to associate media files with notes, allowing:
+   - Multiple media per note (max 4)
+   - Explicit ordering via `display_order` column
+   - Per-attachment metadata (captions)
+   - Future reuse of media across notes
+
+2. **Display Model**: Media attachments appear at the TOP of notes:
+   - 1 image: Full width display
+   - 2 images: Side-by-side layout
+   - 3-4 images: Grid layout
+   - Text content always appears below media
+
+3. **Syndication Strategy**:
+   - RSS: Embed media as HTML in description (universal support)
+   - ATOM: Use both `<link rel="enclosure">` and HTML content
+   - JSON Feed: Use native `attachments` array (cleanest)
+
+4. **Microformats2**: Multiple `u-photo` properties for multi-photo posts
+
+## Rationale
+**Why attachment model over inline markdown?**
+- Matches user mental model (social media posts)
+- Simplifies UI/UX (no cursor tracking needed)
+- Better syndication support (especially JSON Feed)
+- Cleaner Microformats2 markup
+- Consistent display across all contexts
+
+**Why junction table over array column?**
+- Better query performance for feeds
+- Supports future media reuse
+- Per-attachment metadata
+- Explicit ordering control
+- Standard relational design
+
+**Why limit to 4 images?**
+- Twitter limit is 4 images
+- Mastodon limit is 4 images
+- Prevents performance issues
+- Maintains clean grid layouts
+- Sufficient for microblogging use case
+
+## Consequences
+
+### Positive
+- Clean separation of media and text content
+- Familiar social media UX pattern
+- Excellent syndication feed support
+- Future-proof for media galleries
+- Supports accessibility via captions
+- Efficient database queries
+
+### Negative
+- No inline images in markdown content
+- All media must appear at top
+- Cannot mix text and images
+- More complex database schema
+- Additional JOIN queries needed
+
+### Neutral
+- Different from traditional blog CMSs
+- Requires grid layout CSS
+- Media upload is separate from text editing
+
+## Alternatives Considered
+
+### Alternative 1: Inline Markdown Images
+Store media URLs in markdown content as `![alt](url)`.
+- **Pros**: Traditional blog approach, flexible positioning
+- **Cons**: Poor syndication, complex editing UX, inconsistent display
+
+### Alternative 2: JSON Array in Notes Table
+Store media IDs as JSON array column in notes table.
+- **Pros**: Simpler schema, fewer tables
+- **Cons**: Poor query performance, no per-media metadata, violates 1NF
+
+### Alternative 3: Single Media Per Note
+Restrict to one image per note.
+- **Pros**: Simplest implementation
+- **Cons**: Too limiting, doesn't match social media patterns
+
+## Implementation Notes
+
+1. Migration will create both `media` and `note_media` tables
+2. Feed generators must query media via JOIN
+3. Template must render media before content
+4. Upload UI shows thumbnails, not markdown insertion
+5. Consider lazy loading for performance
+
+## References
+- [IndieWeb multi-photo posts](https://indieweb.org/multi-photo)
+- [Microformats2 u-photo property](https://microformats.org/wiki/h-entry#u-photo)
+- [JSON Feed attachments](https://jsonfeed.org/version/1.1#attachments)
+- [Twitter photo upload limits](https://help.twitter.com/en/using-twitter/tweeting-gifs-and-pictures)
--- a/docs/decisions/ADR-058-image-optimization-strategy.md
+++ b/docs/decisions/ADR-058-image-optimization-strategy.md
@@ -0,0 +1,183 @@
+# ADR-058: Image Optimization Strategy
+
+## Status
+Accepted
+
+## Context
+The v1.2.0 media upload feature requires decisions about image size limits, optimization, and validation. Based on user requirements:
+- 4 images maximum per note (confirmed)
+- No drag-and-drop reordering needed (display order is upload order)
+- Image optimization desired
+- Optional caption field for each image (accessibility)
+
+Research was conducted on:
+- Web image best practices (2024)
+- IndieWeb implementation patterns
+- Python image processing libraries
+- Storage implications for single-user CMS
+
+## Decision
+
+### Image Limits
+We will enforce the following limits:
+
+1. **Count**: Maximum 4 images per note
+2. **File Size**: Maximum 10MB per image
+3. **Dimensions**: Maximum 4096x4096 pixels
+4. **Formats**: JPEG, PNG, GIF, WebP only
+
+### Optimization Strategy
+We will implement **automatic resizing on upload**:
+
+1. **Resize Policy**:
+   - Images larger than 2048 pixels (longest edge) will be resized
+   - Aspect ratio will be preserved
+   - Original quality will be maintained (no aggressive compression)
+   - EXIF orientation will be corrected
+
+2. **Rejection Policy**:
+   - Files over 10MB will be rejected (before optimization)
+   - Dimensions over 4096x4096 will be rejected
+   - Invalid formats will be rejected
+   - Corrupted files will be rejected
+
+3. **Processing Library**: Use **Pillow** for image processing
+
+### Database Schema Updates
+Add caption field to `note_media` table:
+```sql
+CREATE TABLE note_media (
+    id INTEGER PRIMARY KEY,
+    note_id INTEGER NOT NULL,
+    media_id INTEGER NOT NULL,
+    display_order INTEGER NOT NULL DEFAULT 0,
+    caption TEXT,  -- Optional caption for accessibility
+    created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    FOREIGN KEY (note_id) REFERENCES notes(id) ON DELETE CASCADE,
+    FOREIGN KEY (media_id) REFERENCES media(id) ON DELETE CASCADE,
+    UNIQUE(note_id, media_id)
+);
+```
+
+## Rationale
+
+### Why 10MB file size limit?
+- Generous for high-quality photos from modern phones
+- Prevents storage abuse on single-user instance
+- Reasonable upload time even on slower connections
+- Matches or exceeds most social platforms
+
+### Why 4096x4096 max dimensions?
+- Covers 16-megapixel images (4000x4000)
+- Sufficient for 4K displays (3840x2160)
+- Prevents memory issues during processing
+- Larger than needed for web display
+
+### Why resize to 2048px?
+- Optimal balance between quality and performance
+- Retina-ready (2x scaling on 1024px display)
+- Significant file size reduction
+- Matches common social media limits
+- Preserves quality for most use cases
+
+### Why Pillow over alternatives?
+- De-facto standard for Python image processing
+- Fastest for basic resize operations
+- Minimal dependencies
+- Well-documented and stable
+- Sufficient for our needs (resize, format conversion, EXIF)
+
+### Why automatic optimization?
+- Better user experience (no manual intervention)
+- Consistent output quality
+- Storage efficiency
+- Faster page loads
+- Users still get good quality
+
+### Why no thumbnail generation?
+- Adds complexity for minimal benefit
+- Modern browsers handle image scaling well
+- Single-user CMS doesn't need CDN optimization
+- Can be added later if needed
+
+## Consequences
+
+### Positive
+- Automatic optimization improves performance
+- Generous limits support high-quality photography
+- Captions improve accessibility
+- Storage usage remains reasonable
+- Fast processing with Pillow
+
+### Negative
+- Users cannot upload raw/unprocessed images
+- Some quality loss for images over 2048px
+- No manual control over optimization
+- Additional processing time on upload
+
+### Neutral
+- Requires Pillow dependency
+- Images stored at single resolution
+- No progressive enhancement (thumbnails)
+
+## Alternatives Considered
+
+### Alternative 1: No Optimization
+Accept images as-is, no processing.
+- **Pros**: Simpler, preserves originals
+- **Cons**: Storage bloat, slow page loads, memory issues
+
+### Alternative 2: Strict Limits (1MB, 1920x1080)
+Match typical web recommendations.
+- **Pros**: Optimal performance, minimal storage
+- **Cons**: Too restrictive for photography, poor UX
+
+### Alternative 3: Generate Multiple Sizes
+Create thumbnail, medium, and full sizes.
+- **Pros**: Optimal delivery, responsive images
+- **Cons**: Complex implementation, 3x storage, overkill for single-user
+
+### Alternative 4: Client-side Resizing
+Resize in browser before upload.
+- **Pros**: Reduces server load
+- **Cons**: Inconsistent quality, browser limitations, poor UX
+
+## Implementation Notes
+
+1. **Validation Order**:
+   - Check file size (reject if >10MB)
+   - Check MIME type (accept only allowed formats)
+   - Load with Pillow (validates file integrity)
+   - Check dimensions (reject if >4096px)
+   - Resize if needed (>2048px)
+   - Save optimized version
+
+2. **Error Messages**:
+   - "File too large. Maximum size is 10MB"
+   - "Invalid image format. Accepted: JPEG, PNG, GIF, WebP"
+   - "Image dimensions too large. Maximum is 4096x4096"
+   - "Image appears to be corrupted"
+
+3. **Pillow Configuration**:
+   ```python
+   # Preserve quality during resize
+   image.thumbnail((2048, 2048), Image.Resampling.LANCZOS)
+
+   # Correct EXIF orientation
+   ImageOps.exif_transpose(image)
+
+   # Save with original quality
+   image.save(output, quality=95, optimize=True)
+   ```
+
+4. **Caption Implementation**:
+   - Add caption field to upload form
+   - Store in `note_media.caption`
+   - Use as alt text in HTML
+   - Include in Microformats markup
+
+## References
+- [MDN Web Performance: Images](https://developer.mozilla.org/en-US/docs/Web/Performance/images)
+- [Pillow Documentation](https://pillow.readthedocs.io/)
+- [Web.dev Image Optimization](https://web.dev/fast/#optimize-your-images)
+- [Twitter Image Specifications](https://developer.twitter.com/en/docs/twitter-api/v1/media/upload-media/uploading-media/media-best-practices)
--- a/docs/decisions/ADR-061-author-discovery.md
+++ b/docs/decisions/ADR-061-author-discovery.md
@@ -0,0 +1,111 @@
+# ADR-061: Author Profile Discovery from IndieAuth
+
+## Status
+Accepted
+
+## Context
+StarPunk v1.2.0 requires Microformats2 compliance, including proper h-card author information in h-entries. The original design assumed author information would be configured via environment variables (AUTHOR_NAME, AUTHOR_PHOTO, etc.).
+
+However, since StarPunk uses IndieAuth for authentication, and users authenticate with their domain/profile URL, we have an opportunity to discover author information directly from their IndieWeb profile rather than requiring manual configuration.
+
+The user explicitly stated: "These should be retrieved from the logged in profile domain (rel me etc.)" when asked about author configuration.
+
+## Decision
+Implement automatic author profile discovery from the IndieAuth 'me' URL:
+
+1. When a user logs in via IndieAuth, fetch their profile page
+2. Parse h-card microformats and rel-me links from the profile
+3. Cache this information in a new `author_profile` database table
+4. Use discovered information in templates for Microformats2 markup
+5. Provide fallback behavior when discovery fails
+
+## Rationale
+1. **IndieWeb Native**: Discovery from profile URLs is a core IndieWeb pattern
+2. **DRY Principle**: Author already maintains their profile; no need to duplicate
+3. **Dynamic Updates**: Profile changes are reflected on next login
+4. **Standards-Based**: Uses existing h-card and rel-me specifications
+5. **User Experience**: Zero configuration for author information
+6. **Consistency**: Author info always matches their IndieWeb identity
+
+## Consequences
+
+### Positive
+- No manual configuration of author information required
+- Automatically stays in sync with user's profile
+- Supports full IndieWeb identity model
+- Works with any IndieAuth provider
+- Discoverable rel-me links for identity verification
+
+### Negative
+- Requires network request during login (mitigated by caching)
+- Depends on proper markup on user's profile page
+- Additional database table required
+- More complex than static configuration
+- Parsing complexity for microformats
+
+### Implementation Details
+
+#### Database Schema
+```sql
+CREATE TABLE author_profile (
+    id INTEGER PRIMARY KEY,
+    me_url TEXT NOT NULL UNIQUE,
+    name TEXT,
+    photo TEXT,
+    bio TEXT,
+    rel_me_links TEXT,  -- JSON array
+    discovered_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP
+);
+```
+
+#### Discovery Flow
+1. User authenticates with IndieAuth
+2. On successful login, trigger discovery
+3. Fetch user's profile page (with timeout)
+4. Parse h-card for: name, photo, bio
+5. Parse rel-me links
+6. Store in database with timestamp
+7. Use cache for 7 days, refresh on login
+
+#### Fallback Strategy
+- If discovery fails during login, use cached data if available
+- If no cache exists, use minimal defaults (domain as name)
+- Never block login due to discovery failure
+- Log failures for monitoring
+
+## Alternatives Considered
+
+### 1. Environment Variables (Original Design)
+Static configuration via .env file
+- ✅ Simple, no network requests
+- ❌ Requires manual configuration
+- ❌ Duplicates information already on profile
+- ❌ Can become out of sync
+
+### 2. Hybrid Approach
+Environment variables with optional discovery
+- ✅ Flexibility for both approaches
+- ❌ More complex configuration
+- ❌ Unclear which takes precedence
+
+### 3. Discovery Only, No Cache
+Fetch profile on every request
+- ✅ Always up to date
+- ❌ Performance impact
+- ❌ Reliability issues
+
+### 4. Static Import Tool
+CLI command to import profile once
+- ✅ No runtime discovery needed
+- ❌ Manual process
+- ❌ Can become stale
+
+## Implementation Priority
+High - Required for v1.2.0 Microformats2 compliance
+
+## References
+- https://microformats.org/wiki/h-card
+- https://indieweb.org/rel-me
+- https://indieweb.org/discovery
+- W3C IndieAuth specification