feat(tags): Add database schema and tags module (v1.3.0 Phase 1)

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>
2025-12-10 11:24:23 -07:00
parent 927db4aea0
commit f10d0679da
188 changed files with 601 additions and 945 deletions
--- a/docs/design/v1.0.0/quick-reference.md
+++ b/docs/design/v1.0.0/quick-reference.md
@@ -0,0 +1,339 @@
+# StarPunk V1 Quick Reference
+
+## Implementation Order (Dependency-Based)
+
+This is the strict dependency order for implementing StarPunk V1. Each item depends on all items above it.
+
+### Layer 1: Foundation (No Dependencies)
+1. `starpunk/utils.py` - Utility functions
+2. `starpunk/models.py` - Data models
+3. `templates/` - All HTML templates (can be done in parallel)
+4. `static/css/style.css` - Styling (can be done in parallel)
+
+### Layer 2: Core Features (Depends on Layer 1)
+5. `starpunk/notes.py` - Notes CRUD operations (depends on utils, models)
+6. `starpunk/auth.py` - Authentication (depends on models)
+
+### Layer 3: Web Interface (Depends on Layers 1-2)
+7. `starpunk/routes/public.py` - Public routes (depends on notes)
+8. `starpunk/routes/admin.py` - Admin routes (depends on auth, notes)
+
+### Layer 4: Additional Features (Depends on Layers 1-2)
+9. `starpunk/feed.py` - RSS feed generation (depends on notes)
+10. `starpunk/micropub.py` - Micropub endpoint (depends on auth, notes)
+
+### Layer 5: API Routes (Depends on Layers 1-4)
+11. `starpunk/routes/api.py` - REST API (optional, depends on auth, notes)
+
+### Layer 6: Testing (Depends on All Above)
+12. Unit tests for each module
+13. Integration tests
+14. Standards validation
+15. Security testing
+
+### Layer 7: Documentation (Depends on Complete Implementation)
+16. User documentation
+17. Deployment guide
+18. API documentation
+
+---
+
+## Module Dependencies
+
+```
+database.py (already complete)
+config.py (already complete)
+    ↓
+utils.py → models.py
+    ↓         ↓
+    ↓    notes.py ← auth.py
+    ↓         ↓         ↓
+    ↓    feed.py   micropub.py
+    ↓         ↓         ↓
+    └─→ routes/public.py
+              ↓
+         routes/admin.py (also depends on auth.py)
+              ↓
+         routes/api.py (optional)
+```
+
+---
+
+## Critical Path Items
+
+These features MUST be implemented for a functional V1:
+
+### Tier 1: Absolutely Required
+- [ ] `utils.py` - Can't create notes without slug generation
+- [ ] `models.py` - Everything uses these data structures
+- [ ] `notes.py` - Core functionality
+- [ ] `auth.py` - Required for admin access
+- [ ] `routes/admin.py` - Required to create notes via web
+- [ ] `routes/public.py` - Required to view notes
+
+### Tier 2: Required for IndieWeb Compliance
+- [ ] `feed.py` - RSS is required per specs
+- [ ] `micropub.py` - Micropub is required per specs
+- [ ] Microformats in templates - Required per specs
+
+### Tier 3: Nice to Have
+- [ ] `routes/api.py` - Bonus JSON API (not required)
+- [ ] `static/js/preview.js` - Enhancement only
+- [ ] Media uploads - Can defer to V2
+
+---
+
+## File Checklist
+
+### Python Modules (9 files)
+- [x] `starpunk/__init__.py` (complete)
+- [x] `starpunk/config.py` (complete)
+- [x] `starpunk/database.py` (complete)
+- [ ] `starpunk/utils.py` (implement in Phase 1)
+- [ ] `starpunk/models.py` (implement in Phase 1)
+- [ ] `starpunk/notes.py` (implement in Phase 2)
+- [ ] `starpunk/auth.py` (implement in Phase 3)
+- [ ] `starpunk/feed.py` (implement in Phase 5)
+- [ ] `starpunk/micropub.py` (implement in Phase 6)
+
+### Route Blueprints (3 files)
+- [ ] `starpunk/routes/__init__.py` (create in Phase 4)
+- [ ] `starpunk/routes/public.py` (implement in Phase 4)
+- [ ] `starpunk/routes/admin.py` (implement in Phase 4)
+- [ ] `starpunk/routes/api.py` (optional, Phase 7)
+
+### Templates (9 files)
+- [ ] `templates/base.html`
+- [ ] `templates/index.html`
+- [ ] `templates/note.html`
+- [ ] `templates/admin/base.html`
+- [ ] `templates/admin/login.html`
+- [ ] `templates/admin/dashboard.html`
+- [ ] `templates/admin/new.html`
+- [ ] `templates/admin/edit.html`
+- [ ] `templates/feed.xml`
+
+### Static Files (2 files)
+- [ ] `static/css/style.css` (required)
+- [ ] `static/js/preview.js` (optional)
+
+### Test Files (9 files)
+- [x] `tests/__init__.py` (complete)
+- [x] `tests/conftest.py` (complete)
+- [ ] `tests/test_utils.py`
+- [ ] `tests/test_models.py`
+- [ ] `tests/test_notes.py`
+- [ ] `tests/test_auth.py`
+- [ ] `tests/test_feed.py`
+- [ ] `tests/test_micropub.py`
+- [ ] `tests/test_integration.py`
+
+### Documentation Files
+- [ ] Update `README.md` (Phase 9)
+- [ ] `docs/architecture/deployment.md` (Phase 9)
+- [ ] `docs/user-guide.md` (Phase 9)
+- [ ] `docs/api.md` (Phase 9)
+- [ ] `CONTRIBUTING.md` (Phase 9)
+
+**Total Files to Create**: ~35 files
+
+---
+
+## Test Coverage Requirements
+
+### Unit Tests (>90% coverage)
+- `test_utils.py` → `utils.py`
+- `test_models.py` → `models.py`
+- `test_notes.py` → `notes.py`
+- `test_auth.py` → `auth.py`
+- `test_feed.py` → `feed.py`
+- `test_micropub.py` → `micropub.py`
+
+### Integration Tests (major flows)
+- Login → Create Note → View Note → Edit → Delete
+- Micropub → Publish → View on Site
+- RSS Feed Updates
+
+### Standards Validation (manual/automated)
+- W3C HTML Validator
+- W3C Feed Validator
+- IndieWebify.me (Microformats)
+- Micropub.rocks (Micropub compliance)
+
+### Security Testing
+- CSRF protection
+- SQL injection prevention
+- XSS prevention
+- Path traversal prevention
+- Authentication/authorization
+
+---
+
+## Configuration Checklist
+
+### Required .env Variables
+```bash
+# CRITICAL - Must set these
+SESSION_SECRET=<generate with: python3 -c "import secrets; print(secrets.token_hex(32))">
+ADMIN_ME=https://your-website.com
+
+# Important
+SITE_URL=http://localhost:5000
+SITE_NAME=My StarPunk Site
+SITE_AUTHOR=Your Name
+
+# Optional (have defaults)
+SITE_DESCRIPTION=
+SESSION_LIFETIME=30
+INDIELOGIN_URL=https://indielogin.com
+DATA_PATH=./data
+NOTES_PATH=./data/notes
+DATABASE_PATH=./data/starpunk.db
+FLASK_ENV=development
+FLASK_DEBUG=1
+LOG_LEVEL=INFO
+```
+
+---
+
+## Common Development Commands
+
+```bash
+# Activate virtual environment
+source /home/phil/Projects/starpunk/.venv/bin/activate
+
+# Run development server
+flask --app app.py run --debug
+
+# Run tests
+pytest
+
+# Run tests with coverage
+pytest --cov=starpunk --cov-report=html
+
+# Format code
+black starpunk/ tests/
+
+# Lint code
+flake8 starpunk/ tests/
+
+# Type check
+mypy starpunk/
+
+# Install dependencies
+uv pip install -r requirements.txt
+
+# Install dev dependencies
+uv pip install -r requirements-dev.txt
+
+# Create database
+python -c "from starpunk.database import init_db; init_db()"
+
+# Run specific test file
+pytest tests/test_notes.py
+
+# Run specific test
+pytest tests/test_notes.py::test_create_note
+
+# Check test coverage
+pytest --cov=starpunk --cov-report=term-missing
+```
+
+---
+
+## Key Design Decisions Reference
+
+Quick lookup for architectural decisions:
+
+| Decision | ADR | Key Choice |
+|----------|-----|------------|
+| Web Framework | ADR-001 | Flask (minimal, no magic) |
+| Dependencies | ADR-002 | 6 packages only (Flask, markdown, feedgen, httpx, python-dotenv, pytest) |
+| Frontend | ADR-003 | Server-side rendering, minimal JS |
+| Storage | ADR-004 | Hybrid: Files for content, DB for metadata |
+| Authentication | ADR-005 | IndieLogin.com (delegated OAuth) |
+| Virtual Env | ADR-006 | uv package manager, Python 3.11+ |
+
+---
+
+## Success Criteria
+
+### V1 is complete when:
+- [ ] Can create notes via web interface
+- [ ] Can authenticate with IndieLogin.com
+- [ ] Can view published notes on public site
+- [ ] Can publish via Micropub client
+- [ ] RSS feed is valid and updates
+- [ ] All tests pass (>80% coverage)
+- [ ] All validators pass (HTML, RSS, Microformats, Micropub)
+- [ ] Documentation is complete
+- [ ] Deployable to production
+
+### Performance Targets
+- [ ] API responses < 100ms
+- [ ] Page renders < 200ms
+- [ ] RSS generation < 300ms
+- [ ] Memory usage < 100MB
+
+### Quality Targets
+- [ ] Test coverage > 80%
+- [ ] No security vulnerabilities
+- [ ] Valid HTML5
+- [ ] Valid RSS 2.0
+- [ ] Valid Microformats2
+- [ ] Micropub spec compliant
+
+---
+
+## Troubleshooting Common Issues
+
+### Database locked errors
+- Close all database connections
+- Check if another process has lock
+- Restart Flask app
+
+### IndieLogin fails
+- Check ADMIN_ME is set correctly
+- Verify internet connection to indielogin.com
+- Check state token hasn't expired (5 min limit)
+
+### File not found errors
+- Check DATA_PATH exists
+- Check file permissions (need write access)
+- Check year/month directories created
+
+### Import errors
+- Ensure virtual environment activated
+- Run `uv pip install -r requirements.txt`
+- Check PYTHONPATH if needed
+
+### Tests fail
+- Check database initialized
+- Check test fixtures in conftest.py
+- Ensure test isolation (no shared state)
+
+---
+
+## Quick Links
+
+### Documentation
+- [Full Implementation Plan](implementation-plan.md)
+- [Architecture Overview](/home/phil/Projects/starpunk/docs/architecture/overview.md)
+- [Technology Stack](/home/phil/Projects/starpunk/docs/architecture/technology-stack.md)
+
+### External Specs
+- [Micropub Spec](https://micropub.spec.indieweb.org/)
+- [IndieAuth Spec](https://www.w3.org/TR/indieauth/)
+- [Microformats2](http://microformats.org/wiki/microformats2)
+- [RSS 2.0 Spec](https://www.rssboard.org/rss-specification)
+
+### Tools
+- [W3C HTML Validator](https://validator.w3.org/)
+- [W3C Feed Validator](https://validator.w3.org/feed/)
+- [IndieWebify.me](https://indiewebify.me/)
+- [Micropub.rocks](https://micropub.rocks/)
+- [Quill (Micropub Client)](https://quill.p3k.io/)
+
+---
+
+**Last Updated**: 2025-11-18