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/projectplan/v1.X.X-indieweb-options.md
+++ b/docs/projectplan/v1.X.X-indieweb-options.md
@@ -0,0 +1,222 @@
+# StarPunk v1.X.X IndieWeb-Focused Release Options
+
+*Created: 2025-11-28*
+*Status: Options for architect review*
+
+Based on analysis of current implementation gaps and IndieWeb specifications, here are three genuinely different paths forward for full IndieWeb protocol support.
+
+---
+
+## Option A: v1.2.0 "Conversation" - Webmention & Reply Context
+
+**Focus:** Enable two-way conversations between IndieWeb sites
+
+**What's Missing Now:**
+- Zero Webmention support (no sending, no receiving)
+- No reply context display (when replying to others)
+- No backlinks/responses display
+- No notification system for mentions
+
+**What You'll Get:**
+- **Webmention Sending** (W3C Webmention spec)
+  - Automatic endpoint discovery via HTTP headers/HTML links
+  - Send notifications when mentioning/replying to other sites
+  - Queue system for reliable delivery with retries
+- **Webmention Receiving** (W3C Webmention spec)
+  - Advertise endpoint in HTML and HTTP headers
+  - Verify source mentions target
+  - Store and display incoming mentions (likes, replies, reposts)
+- **Reply Context** (IndieWeb reply-context spec)
+  - Fetch and display content you're replying to
+  - Parse microformats2 from source
+  - Cache reply contexts locally
+- **Response Display** (facepile pattern)
+  - Show likes/reposts as compact avatars
+  - Display full replies with author info
+  - Separate responses by type
+
+**IndieWeb Specs:**
+- W3C Webmention: https://www.w3.org/TR/webmention/
+- Reply-context: https://indieweb.org/reply-context
+- Response display: https://indieweb.org/responses
+- Facepile: https://indieweb.org/facepile
+
+**Completion Criteria:**
+- Pass webmention.rocks test suite (21 tests)
+- Successfully send/receive with 3+ IndieWeb sites
+- Display reply contexts with proper h-cite markup
+- Show incoming responses grouped by type
+
+**User Value:**
+Transform StarPunk from broadcast-only to conversational. Users can reply to other IndieWeb posts and see who's engaging with their content. Creates a decentralized comment system.
+
+**Scope:** 8-10 weeks
+
+---
+
+## Option B: v1.3.0 "Studio" - Complete Micropub Media & Post Types
+
+**Focus:** Full Micropub spec compliance with rich media and diverse post types
+
+**What's Missing Now:**
+- No media endpoint (can't upload images/audio/video)
+- No update/delete via Micropub (create-only)
+- No syndication targets
+- Only supports notes (no articles, photos, bookmarks, etc.)
+- No query support beyond basic config
+
+**What You'll Get:**
+- **Micropub Media Endpoint** (W3C Micropub spec section 3.7)
+  - Accept multipart uploads for images/audio/video
+  - Generate URLs for uploaded media
+  - Return media URL to client for embedding
+  - Basic image resizing/optimization
+- **Micropub Updates/Deletes** (W3C Micropub spec sections 3.3-3.4)
+  - Replace/add/delete specific properties
+  - Full post deletion support
+  - JSON syntax for complex updates
+- **Post Type Discovery** (IndieWeb post-type-discovery)
+  - Articles (with titles)
+  - Photos (image-centric posts)
+  - Bookmarks (link saving)
+  - Likes (marking favorites)
+  - Reposts (sharing others' content)
+  - Audio/Video posts
+- **Syndication Targets** (Micropub syndicate-to)
+  - Configure external targets (Mastodon, Twitter bridges)
+  - POSSE implementation
+  - Return syndication URLs
+
+**IndieWeb Specs:**
+- W3C Micropub (complete): https://www.w3.org/TR/micropub/
+- Post Type Discovery: https://indieweb.org/post-type-discovery
+- POSSE: https://indieweb.org/POSSE
+
+**Completion Criteria:**
+- Pass micropub.rocks full test suite (not just create)
+- Support all major post types with proper templates
+- Successfully syndicate to 2+ external services
+- Handle media uploads from mobile apps
+
+**User Value:**
+Use any Micropub client (Indigenous, Quill, etc.) with full features. Post photos from your phone, save bookmarks, like posts, all through standard clients. Syndicate to social media automatically.
+
+**Scope:** 10-12 weeks
+
+---
+
+## Option C: v1.4.0 "Identity" - Complete Microformats2 & IndieAuth Provider
+
+**Focus:** Become a full IndieWeb identity provider and improve content markup
+
+**What's Missing Now:**
+- Minimal h-entry markup (missing author, location, syndication)
+- No h-card on pages (no author identity)
+- No h-feed markup enhancements
+- No rel=me verification
+- Using external IndieAuth (not self-hosted)
+- No authorization endpoint
+- No token endpoint
+
+**What You'll Get:**
+- **Complete h-entry Microformats2** (microformats2 spec)
+  - Author h-card embedded in each post
+  - Location (p-location with h-geo/h-adr)
+  - Syndication links (u-syndication)
+  - In-reply-to markup (u-in-reply-to)
+  - Categories/tags (p-category)
+- **Author h-card** (microformats2 h-card)
+  - Full profile page with h-card
+  - Representative h-card on homepage
+  - Contact info, bio, social links
+  - rel=me links for verification
+- **Enhanced h-feed** (microformats2 h-feed)
+  - Feed name and author
+  - Pagination with rel=prev/next
+  - Feed photo/summary
+- **IndieAuth Provider** (IndieAuth spec)
+  - Authorization endpoint (login to other sites with your domain)
+  - Token endpoint (issue access tokens)
+  - Client registration support
+  - Scope management
+  - Token revocation interface
+
+**IndieWeb Specs:**
+- Microformats2: http://microformats.org/wiki/microformats2
+- h-card: http://microformats.org/wiki/h-card
+- h-entry: http://microformats.org/wiki/h-entry
+- IndieAuth: https://indieauth.spec.indieweb.org/
+- rel=me: https://indieweb.org/rel-me
+
+**Completion Criteria:**
+- Pass IndieWebify.me full validation
+- Successfully authenticate to 5+ IndieWeb services
+- Parse correctly in all major microformats2 parsers
+- Provide IndieAuth to other sites (eat your own dogfood)
+
+**User Value:**
+Your site becomes your identity across the web. Log into any IndieWeb service with your domain. Rich markup makes your content parse perfectly everywhere. No dependency on external auth services.
+
+**Scope:** 6-8 weeks
+
+---
+
+## Recommendation Rationale
+
+Each option represents a fundamentally different IndieWeb capability:
+
+- **Option A (Conversation)**: Makes StarPunk social and interactive
+- **Option B (Studio)**: Makes StarPunk a complete publishing platform
+- **Option C (Identity)**: Makes StarPunk an identity provider
+
+All three are essential for "full IndieWeb support" but focus on different protocols:
+
+- A focuses on **Webmention** (W3C Recommendation)
+- B focuses on **Micropub** completion (W3C Recommendation)
+- C focuses on **Microformats2** & **IndieAuth** (IndieWeb specs)
+
+## Current Implementation Gaps Summary
+
+Based on code analysis:
+
+### Micropub (`starpunk/micropub.py`)
+✅ Create notes (basic)
+✅ Query config
+✅ Query source
+❌ Media endpoint
+❌ Updates (replace/add/delete)
+❌ Deletes
+❌ Syndication targets
+❌ Query for syndicate-to
+
+### Microformats (templates)
+✅ Basic h-entry (content, published date, URL)
+✅ Basic h-feed wrapper
+❌ Author h-card
+❌ Complete h-entry properties
+❌ rel=me links
+❌ h-feed metadata
+
+### Webmention
+❌ No implementation at all
+
+### IndieAuth
+✅ Client (using indielogin.com)
+❌ No provider capability
+
+### Post Types
+✅ Notes
+❌ Articles, photos, bookmarks, likes, reposts, etc.
+
+---
+
+## Decision Factors
+
+Consider these when choosing:
+
+1. **User Demand**: What are users asking for most?
+2. **Ecosystem Value**: Which adds most value to IndieWeb network?
+3. **Technical Dependencies**: Option C (Identity) might benefit A & B
+4. **Market Differentiation**: Which makes StarPunk unique?
+
+All three options are genuinely different approaches to "full IndieWeb support" - the choice depends on priorities.
--- a/docs/projectplan/v1.X.X-options.md
+++ b/docs/projectplan/v1.X.X-options.md
@@ -0,0 +1,155 @@
+# StarPunk Next Release Options
+
+After v1.1.2 "Syndicate" (Metrics + Multi-Format Feeds + Statistics Dashboard)
+
+## Option A: v1.2.0 "Discover" - Discoverability & SEO Enhancement
+
+**Focus:** Make your content findable by search engines and discoverable by IndieWeb tools, improving organic reach and community integration.
+
+**User Benefit:** Your notes become easier to find through Google, properly parsed by IndieWeb tools, and better integrated with the broader web ecosystem. Solves the "I'm publishing but nobody can find me" problem.
+
+**Key Features:**
+- **Microformats2 Enhancement** - Full h-entry, h-card, h-feed validation and enrichment with author info, categories, and reply contexts
+- **Structured Data Implementation** - Schema.org JSON-LD for articles, breadcrumbs, and person markup for rich snippets
+- **XML Sitemap Generation** - Dynamic sitemap.xml with lastmod dates, priority scores, and change frequencies
+- **OpenGraph & Twitter Cards** - Social media preview optimization with proper meta tags and image handling
+- **Webmention Discovery** - Add webmention endpoint discovery links (preparation for future receiving)
+- **Archive Pages** - Year/month archive pages with proper pagination and navigation
+- **Category/Tag System** - Simple tagging with category pages and tag clouds (backward compatible with existing notes)
+
+**Technical Highlights:**
+- Microformats2 spec compliance validation with indiewebify.me
+- JSON-LD structured data for Google Rich Results
+- Sitemap protocol compliance with optional ping to search engines
+- Minimal implementation - tags stored in note metadata, no new tables
+- Progressive enhancement - existing notes work unchanged
+
+**Scope:** Medium
+
+**Dependencies:**
+- Existing RSS/ATOM/JSON Feed infrastructure for sitemap generation
+- Current URL routing for archive pages
+- Metrics instrumentation helps track search traffic
+
+**Strategic Value:** Essential for growth - if people can't find your content, the best CMS is worthless. This positions StarPunk as SEO-friendly out of the box, competing with static site generators while maintaining IndieWeb principles.
+
+---
+
+## Option B: v1.2.0 "Control" - Publishing Workflow & Content Management
+
+**Focus:** Professional publishing workflows with scheduling, drafts management, and bulk operations - treating your notes as a serious publishing platform.
+
+**User Benefit:** Write when inspired, publish when strategic. Queue up content for consistent publishing, manage drafts effectively, and perform bulk operations efficiently. Solves the "I want to write now but publish later" problem.
+
+**Key Features:**
+- **Scheduled Publishing** - Set future publish dates/times with automatic publishing via background worker
+- **Draft Versioning** - Save multiple draft versions with comparison view and restore capability
+- **Bulk Operations** - Select multiple notes for publish/unpublish/delete with confirmation
+- **Publishing Calendar** - Visual calendar showing scheduled posts, published posts, and gaps
+- **Auto-Save Drafts** - JavaScript-based auto-save every 30 seconds while editing
+- **Note Templates** - Create reusable templates for common post types (weekly update, link post, etc.)
+- **Quick Notes** - Minimal UI for rapid note creation (just a text box, like Twitter)
+- **Markdown Shortcuts** - Toolbar with common formatting buttons and keyboard shortcuts
+
+**Technical Highlights:**
+- Background task runner (simple Python threading, no Celery needed)
+- Draft versions stored as JSON in a single column (no complex versioning tables)
+- Calendar view using existing metrics dashboard infrastructure
+- LocalStorage for auto-save (works offline)
+- Template system uses simple markdown files in data/templates/
+
+**Scope:** Large
+
+**Dependencies:**
+- Existing admin interface for UI components
+- Current note creation flow for templates
+- Metrics system helps track publishing patterns
+
+**Strategic Value:** Transforms StarPunk from a simple notes publisher to a professional content management system. Appeals to serious bloggers and content creators who need workflow features but want IndieWeb simplicity.
+
+---
+
+## Option C: v1.1.3 "Shield" - Security Hardening & Privacy Controls
+
+**Focus:** Enterprise-grade security hardening and privacy features, making StarPunk suitable for security-conscious users and sensitive content.
+
+**User Benefit:** Peace of mind knowing your content is protected with multiple layers of security, comprehensive audit trails, and privacy controls. Solves the "I need to know my site is secure" problem.
+
+**Key Features:**
+- **Two-Factor Authentication (2FA)** - TOTP support via authenticator apps with backup codes
+- **Comprehensive Audit Logging** - Track all actions: login attempts, note changes, settings modifications with who/what/when/where
+- **Rate Limiting** - Application-level rate limiting for auth endpoints, API calls, and feed access
+- **Content Security Policy (CSP) Level 2** - Strict CSP with nonces, report-uri, and upgrade-insecure-requests
+- **Session Security Hardening** - Fingerprinting, concurrent session limits, geographic anomaly detection
+- **Private Notes** - Password-protected notes with separate authentication (not in feeds)
+- **Automated Security Headers** - HSTS preload, X-Frame-Options, X-Content-Type-Options, Referrer-Policy
+- **Failed Login Tracking** - Lock accounts after N failed attempts with email notification
+
+**Technical Highlights:**
+- PyOTP library for TOTP implementation (minimal dependency)
+- Audit logs in separate SQLite database for performance isolation
+- Rate limiting using in-memory token bucket algorithm
+- CSP nonce generation per request for inline scripts
+- GeoIP lite for geographic anomaly detection
+- bcrypt for private note passwords
+
+**Scope:** Medium
+
+**Dependencies:**
+- Existing auth system for 2FA integration
+- Current session management for hardening
+- Metrics buffer pattern reused for rate limiting
+
+**Strategic Value:** Positions StarPunk as the security-first IndieWeb CMS. Critical differentiator for users who prioritize security and privacy. Many IndieWeb tools lack proper security features - this would make StarPunk stand out.
+
+---
+
+## Decision Matrix
+
+| Aspect | Option A: "Discover" | Option B: "Control" | Option C: "Shield" |
+|--------|---------------------|--------------------|--------------------|
+| **User Appeal** | Bloggers wanting traffic | Power users, professionals | Security-conscious users |
+| **Complexity** | Medium - mostly templates | High - new UI patterns | Medium - mostly backend |
+| **Dependencies** | Few - builds on feeds | Some - needs background tasks | Minimal - largely independent |
+| **IndieWeb Value** | High - improves ecosystem | Medium - individual benefit | Low - not IndieWeb specific |
+| **Market Differentiation** | Medium - expected feature | High - rare in minimal CMSs | Very High - unique position |
+| **Implementation Risk** | Low - well understood | Medium - UI complexity | Low - standard patterns |
+| **Performance Impact** | Minimal | Medium (background tasks) | Minimal |
+| **Maintenance Burden** | Low | High (more features) | Medium (security updates) |
+
+## Architectural Recommendations
+
+### If Choosing Option A: "Discover"
+- Implement microformats2 validation as a separate module
+- Use template inheritance to minimize code duplication
+- Cache generated sitemaps using existing feed cache pattern
+- Consider making categories a simple JSON field initially
+
+### If Choosing Option B: "Control"
+- Start with simple cron-like scheduler, not full job queue
+- Use existing MetricsBuffer pattern for background task tracking
+- Implement templates as markdown files with frontmatter
+- Consider feature flags to ship incrementally
+
+### If Choosing Option C: "Shield"
+- Audit log must be in separate database for performance
+- Rate limiting should use existing metrics infrastructure
+- 2FA should be optional and backward compatible
+- Consider security.txt file for disclosure
+
+## Recommendation
+
+**Architect's Choice: Option A "Discover"**
+
+Rationale:
+1. **Natural progression** - After feeds (syndication), discovery is the logical next step
+2. **Broad appeal** - Every user benefits from better SEO and discoverability
+3. **Standards-focused** - Aligns with StarPunk's commitment to web standards
+4. **Low risk** - Well-understood requirements with clear success metrics
+5. **Foundation for growth** - Enables future features like webmentions, reply contexts
+
+Option B is compelling but introduces significant complexity that conflicts with StarPunk's minimalist philosophy. Option C, while valuable, serves a narrower audience and doesn't advance core IndieWeb goals.
+
+---
+
+*Generated: 2025-11-28*