dd822a35b5
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
8fbdcb6e6f
feat: Complete Phase 2.4 - HTTP Content Negotiation
...
Implements HTTP content negotiation for feed format selection.
Phase 2.4 Deliverables:
- Content negotiation via Accept header parsing
- Quality factor support (q= parameter)
- 5 feed endpoints with format routing
- 406 Not Acceptable responses with helpful errors
- Comprehensive test coverage (63 tests)
Endpoints:
- /feed - Content negotiation based on Accept header
- /feed.rss - Explicit RSS 2.0
- /feed.atom - Explicit ATOM 1.0
- /feed.json - Explicit JSON Feed 1.1
- /feed.xml - Backward compatibility (→ RSS)
MIME Type Mapping:
- application/rss+xml → RSS 2.0
- application/atom+xml → ATOM 1.0
- application/feed+json or application/json → JSON Feed 1.1
- */* → RSS 2.0 (default)
Implementation:
- Simple quality factor parsing (StarPunk philosophy)
- Not full RFC 7231 compliance (minimal approach)
- Reuses existing feed generators
- No breaking changes
Quality Metrics:
- 132/132 tests passing (100%)
- Zero breaking changes
- Full backward compatibility
- Standards compliant negotiation
🤖 Generated with [Claude Code](https://claude.com/claude-code )
Co-Authored-By: Claude <noreply@anthropic.com >
2025-11-27 20:46:49 -07:00
59e9d402c6
feat: Implement Phase 2 Feed Formats - ATOM, JSON Feed, RSS fix (Phases 2.0-2.3)
...
This commit implements the first three phases of v1.1.2 Phase 2 Feed Formats,
adding ATOM 1.0 and JSON Feed 1.1 support alongside the existing RSS feed.
CRITICAL BUG FIX:
- Fixed RSS streaming feed ordering (was showing oldest-first instead of newest-first)
- Streaming RSS removed incorrect reversed() call at line 198
- Feedgen RSS kept correct reversed() to compensate for library behavior
NEW FEATURES:
- ATOM 1.0 feed generation (RFC 4287 compliant)
- Proper XML namespacing and RFC 3339 dates
- Streaming and non-streaming methods
- 11 comprehensive tests
- JSON Feed 1.1 generation (JSON Feed spec compliant)
- RFC 3339 dates and UTF-8 JSON output
- Custom _starpunk extension with permalink_path and word_count
- 13 comprehensive tests
REFACTORING:
- Restructured feed code into starpunk/feeds/ module
- feeds/rss.py - RSS 2.0 (moved from feed.py)
- feeds/atom.py - ATOM 1.0 (new)
- feeds/json_feed.py - JSON Feed 1.1 (new)
- Backward compatible feed.py shim for existing imports
- Business metrics integrated into all feed generators
TESTING:
- Created shared test helper tests/helpers/feed_ordering.py
- Helper validates newest-first ordering across all formats
- 48 total feed tests, all passing
- RSS: 24 tests
- ATOM: 11 tests
- JSON Feed: 13 tests
FILES CHANGED:
- Modified: starpunk/feed.py (now compatibility shim)
- New: starpunk/feeds/ module with rss.py, atom.py, json_feed.py
- New: tests/helpers/feed_ordering.py (shared test helper)
- New: tests/test_feeds_atom.py, tests/test_feeds_json.py
- Modified: CHANGELOG.md (Phase 2 entries)
- New: docs/reports/2025-11-26-v1.1.2-phase2-feed-formats-partial.md
NEXT STEPS:
Phase 2.4 (Content Negotiation) pending - will add /feed endpoint with
Accept header negotiation and explicit format endpoints.
🤖 Generated with [Claude Code](https://claude.com/claude-code )
Co-Authored-By: Claude <noreply@anthropic.com >
2025-11-26 14:54:52 -07:00
b0230b1233
feat: Complete v1.1.2 Phase 1 - Metrics Instrumentation
...
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 >
2025-11-26 14:13:44 -07:00
d565721cdb
fix: Add data transformer to resolve metrics dashboard template mismatch
...
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 >
2025-11-25 21:24:47 -07:00
f62d3c5382
docs: Add v1.1.1 developer Q&A session
...
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 >
2025-11-25 13:43:56 -07:00
e589f5bd6c
docs: Fix ADR numbering conflicts and create comprehensive documentation indices
...
This commit resolves all documentation issues identified in the comprehensive review:
CRITICAL FIXES:
- Renumbered duplicate ADRs to eliminate conflicts:
* ADR-022-migration-race-condition-fix → ADR-037
* ADR-022-syndication-formats → ADR-038
* ADR-023-microformats2-compliance → ADR-040
* ADR-027-versioning-strategy-for-authorization-removal → ADR-042
* ADR-030-CORRECTED-indieauth-endpoint-discovery → ADR-043
* ADR-031-endpoint-discovery-implementation → ADR-044
- Updated all cross-references to renumbered ADRs in:
* docs/projectplan/ROADMAP.md
* docs/reports/v1.0.0-rc.5-migration-race-condition-implementation.md
* docs/reports/2025-11-24-endpoint-discovery-analysis.md
* docs/decisions/ADR-043-CORRECTED-indieauth-endpoint-discovery.md
* docs/decisions/ADR-044-endpoint-discovery-implementation.md
- Updated README.md version from 1.0.0 to 1.1.0
- Tracked ADR-021-indieauth-provider-strategy.md in git
DOCUMENTATION IMPROVEMENTS:
- Created comprehensive INDEX.md files for all docs/ subdirectories:
* docs/architecture/INDEX.md (28 documents indexed)
* docs/decisions/INDEX.md (55 ADRs indexed with topical grouping)
* docs/design/INDEX.md (phase plans and feature designs)
* docs/standards/INDEX.md (9 standards with compliance checklist)
* docs/reports/INDEX.md (57 implementation reports)
* docs/deployment/INDEX.md (deployment guides)
* docs/examples/INDEX.md (code samples and usage patterns)
* docs/migration/INDEX.md (version migration guides)
* docs/releases/INDEX.md (release documentation)
* docs/reviews/INDEX.md (architectural reviews)
* docs/security/INDEX.md (security documentation)
- Updated CLAUDE.md with complete folder descriptions including:
* docs/migration/
* docs/releases/
* docs/security/
VERIFICATION:
- All ADR numbers now sequential and unique (50 total ADRs)
- No duplicate ADR numbers remain
- All cross-references updated and verified
- Documentation structure consistent and well-organized
These changes improve documentation discoverability, maintainability, and
ensure proper version tracking. All index files follow consistent format
with clear navigation guidance.
🤖 Generated with [Claude Code](https://claude.com/claude-code )
Co-Authored-By: Claude <noreply@anthropic.com >
2025-11-25 13:28:56 -07:00
3ed77fd45f
fix: Resolve database migration failure on existing databases
...
Fixes critical issue where migration 002 indexes already existed in SCHEMA_SQL,
causing 'index already exists' errors on databases created before v1.0.0-rc.1.
Changes:
- Removed duplicate index definitions from SCHEMA_SQL (database.py)
- Enhanced migration system to detect and handle indexes properly
- Added comprehensive documentation of the fix
Version bumped to 1.0.0-rc.2 with full changelog entry.
Refs: docs/reports/2025-11-24-migration-fix-v1.0.0-rc.2.md
2025-11-24 13:11:14 -07:00
2eaf67279d
docs: Standardize all IndieAuth spec references to W3C URL
...
- Updated 42 references from indieauth.spec.indieweb.org to www.w3.org/TR/indieauth
- Ensures consistency across all documentation
- Points to the authoritative W3C specification
- No functional changes, documentation update only
Generated with Claude Code
Co-Authored-By: Claude <noreply@anthropic.com >
2025-11-24 11:54:04 -07:00
dca9604746
docs: Address Micropub design issues and clarify V1 scope
...
- Create ADR-029 for IndieAuth/Micropub integration strategy
- Address all critical issues from developer review:
- Add missing 'me' parameter to token endpoint
- Clarify PKCE as optional extension
- Define token security migration strategy
- Add authorization_codes table schema
- Define property mapping rules
- Clarify two authentication flows
- Simplify V1 scope per user decision:
- Remove update/delete operations from V1
- Focus on create-only functionality
- Reduce timeline from 8-10 to 6-8 days
- Update project plan with post-V1 roadmap:
- Phase 11: Update/delete operations (V1.1)
- Phase 12: Media endpoint (V1.2)
- Phase 13: Advanced IndieWeb features (V2.0)
- Phase 14: Enhanced features (V2.0+)
- Create token security migration documentation
- Update ADR-028 for consistency with simplified scope
BREAKING CHANGE: Token migration will invalidate all existing tokens for security
2025-11-24 11:39:13 -07:00
5bbecad01d
docs: Design Micropub endpoint architecture for V1 release
...
- Add comprehensive Micropub endpoint design document
- Define token management approach for IndieAuth
- Specify minimal V1 feature set (create posts, queries)
- Defer media endpoint and advanced features to post-V1
- Add ADR-028 documenting implementation strategy
- 8-10 day implementation timeline to unblock V1
The Micropub endpoint is the final blocker for V1.0.0 release.
2025-11-24 11:19:59 -07:00
066cde8c46
docs: Extract and organize CLAUDE.MD content, restructure documentation
...
This commit performs comprehensive documentation reorganization:
1. Extracted testing checklist from CLAUDE.MD to docs/standards/testing-checklist.md
- Consolidated manual testing checklist
- Added validation tools and resources
- Created pre-release validation workflow
2. Streamlined CLAUDE.md to lightweight operational instructions
- Python environment setup (uv)
- Agent-developer protocol
- Key documentation references
- Removed redundant content (already in other docs)
3. Removed CLAUDE.MD (uppercase) - content was redundant
- All content already exists in architecture/overview.md and projectplan docs
- Only unique content (testing checklist) was extracted
4. Moved root documentation files to appropriate locations:
- CONTAINER_IMPLEMENTATION_SUMMARY.md -> docs/reports/2025-11-19-container-implementation-summary.md
- QUICKFIX-AUTH-LOOP.md -> docs/reports/2025-11-18-quickfix-auth-loop.md
- TECHNOLOGY-STACK-SUMMARY.md -> docs/architecture/technology-stack-legacy.md
- TODO_TEST_UPDATES.md -> docs/reports/2025-11-19-todo-test-updates.md
5. Consolidated design folders:
- Moved all docs/designs/ content into docs/design/
- Renamed PHASE-5-EXECUTIVE-SUMMARY.md to phase-5-executive-summary.md (consistent naming)
- Removed empty docs/designs/ directory
6. Added ADR-021: IndieAuth Provider Strategy
- Documents decision to build own IndieAuth provider
- Explains rationale and trade-offs
Repository root now contains only: README.md, CLAUDE.md, CHANGELOG.md
🤖 Generated with [Claude Code](https://claude.com/claude-code )
Co-Authored-By: Claude <noreply@anthropic.com >
2025-11-24 10:17:50 -07:00
0cca8169ce
feat: Implement Phase 4 Web Interface with bugfixes (v0.5.2)
...
## Phase 4: Web Interface Implementation
Implemented complete web interface with public and admin routes,
templates, CSS, and development authentication.
### Core Features
**Public Routes**:
- Homepage with recent published notes
- Note permalinks with microformats2
- Server-side rendering (Jinja2)
**Admin Routes**:
- Login via IndieLogin
- Dashboard with note management
- Create, edit, delete notes
- Protected with @require_auth decorator
**Development Authentication**:
- Dev login bypass for local testing (DEV_MODE only)
- Security safeguards per ADR-011
- Returns 404 when disabled
**Templates & Frontend**:
- Base layouts (public + admin)
- 8 HTML templates with microformats2
- Custom responsive CSS (114 lines)
- Error pages (404, 500)
### Bugfixes (v0.5.1 → v0.5.2)
1. **Cookie collision fix (v0.5.1)**:
- Renamed auth cookie from "session" to "starpunk_session"
- Fixed redirect loop between dev login and admin dashboard
- Flask's session cookie no longer conflicts with auth
2. **HTTP 404 error handling (v0.5.1)**:
- Update route now returns 404 for nonexistent notes
- Delete route now returns 404 for nonexistent notes
- Follows ADR-012 HTTP Error Handling Policy
- Pattern consistency across all admin routes
3. **Note model enhancement (v0.5.2)**:
- Exposed deleted_at field from database schema
- Enables soft deletion verification in tests
- Follows ADR-013 transparency principle
### Architecture
**New ADRs**:
- ADR-011: Development Authentication Mechanism
- ADR-012: HTTP Error Handling Policy
- ADR-013: Expose deleted_at Field in Note Model
**Standards Compliance**:
- Uses uv for Python environment
- Black formatted, Flake8 clean
- Follows git branching strategy
- Version incremented per versioning strategy
### Test Results
- 405/406 tests passing (99.75%)
- 87% code coverage
- All security tests passing
- Manual testing confirmed working
### Documentation
- Complete implementation reports in docs/reports/
- Architecture reviews in docs/reviews/
- Design documents in docs/design/
- CHANGELOG updated for v0.5.2
### Files Changed
**New Modules**:
- starpunk/dev_auth.py
- starpunk/routes/ (public, admin, auth, dev_auth)
**Templates**: 10 files (base, pages, admin, errors)
**Static**: CSS and optional JavaScript
**Tests**: 4 test files for routes and templates
**Docs**: 20+ architectural and implementation documents
🤖 Generated with [Claude Code](https://claude.com/claude-code )
Co-Authored-By: Claude <noreply@anthropic.com >
2025-11-18 23:01:53 -07:00
d4f1bfb198
feat: Implement Phase 3 authentication module with IndieLogin support
...
Implement complete authentication system following ADR-010 and Phase 3 design specs.
This is a MINOR version increment (0.3.0 -> 0.4.0) as it adds new functionality.
Authentication Features:
- IndieLogin authentication flow via indielogin.com
- Secure session management with SHA-256 token hashing
- CSRF protection with single-use state tokens
- Session lifecycle (create, verify, destroy)
- require_auth decorator for protected routes
- Automatic cleanup of expired sessions
- IP address and user agent tracking
Security Measures:
- Cryptographically secure token generation (secrets module)
- Token hashing for storage (never plaintext)
- SQL injection prevention (prepared statements)
- Single-use CSRF state tokens
- 30-day session expiry with activity refresh
- Comprehensive security logging
Implementation Details:
- starpunk/auth.py: 406 lines, 6 core functions, 4 helpers, 4 exceptions
- tests/test_auth.py: 648 lines, 37 tests, 96% coverage
- Database schema updates for sessions and auth_state tables
- URL validation utility added to utils.py
Test Coverage:
- 37 authentication tests
- 96% code coverage (exceeds 90% target)
- All security features tested
- Edge cases and error paths covered
Documentation:
- Implementation report in docs/reports/
- Updated CHANGELOG.md with detailed changes
- Version incremented to 0.4.0
- ADR-010 and Phase 3 design docs included
Follows project standards:
- Black code formatting (88 char lines)
- Flake8 linting (no errors)
- Python coding standards
- Type hints on all functions
- Comprehensive docstrings
🤖 Generated with [Claude Code](https://claude.com/claude-code )
Co-Authored-By: Claude <noreply@anthropic.com >
2025-11-18 20:35:36 -07:00
a68fd570c7
that initial commit
2025-11-18 19:21:31 -07:00
