StarPunk/docs/projectplan/v1.1/priority-work.md

StarPunk v1.1.0: Priority Work Items

Overview

This document tracked HIGH PRIORITY work items for the v1.1.0 release. All critical items have been successfully completed.

Target Release: v1.1.0 Status: COMPLETED ✅ Created: 2025-11-24 Released: 2025-11-25

Critical Priority Items

All critical items were successfully completed for v1.1.0 release.

---

1. Database Migration System Redesign - Phase 2 ✅

Priority: CRITICAL ADR: ADR-033 Actual Effort: ~2 hours Status: COMPLETE Implementation: Renamed SCHEMA_SQL to INITIAL_SCHEMA_SQL for clarity

Problem

The current database initialization system fails when upgrading existing production databases because SCHEMA_SQL represents the current schema rather than the initial v0.1.0 baseline. This causes indexes to be created on columns that don't exist yet.

Solution

Implement INITIAL_SCHEMA_SQL as designed in ADR-032 to represent the v0.1.0 baseline schema. All schema evolution will happen through migrations.

Implementation Tasks

1. Create INITIAL_SCHEMA_SQL constant (database.py)

   INITIAL_SCHEMA_SQL = """
   -- V0.1.0 baseline schema from commit a68fd57
   -- [Full SQL as documented in ADR-032]
   """
   

2. Modify init_db() function (database.py)

   • Add database existence check
   • Use INITIAL_SCHEMA_SQL for fresh databases
   • Run migrations for all databases
   • See ADR-032 for complete logic

3. Add helper functions (database.py)

   • database_exists_with_tables(): Check if database has existing tables
   • Update imports and error handling

4. Update existing SCHEMA_SQL (database.py)

   • Rename to CURRENT_SCHEMA_SQL
   • Mark as documentation-only (not used for initialization)
   • Add clear comments explaining purpose

Testing Requirements

• Test fresh database initialization (should create v0.1.0 schema then migrate)
• Test upgrade from existing v1.0.0-rc.2 database
• Test upgrade from v0.x.x databases if available
• Verify all indexes created correctly
• Verify no duplicate table/index errors
• Test migration tracking (schema_migrations table)
• Performance test for fresh install (all migrations)

Documentation Updates

• Update database.py docstrings
• Add inline comments explaining dual schema constants
• Update deployment documentation
• Add production upgrade guide
• Update CHANGELOG.md

Success Criteria

• Existing databases upgrade without errors
• Fresh databases initialize correctly
• All migrations run in proper order
• No index creation errors
• Clear upgrade path from any version

---

2. IndieAuth Provider Strategy Implementation

Priority: HIGH ADR: ADR-021 (if exists) Estimated Effort: 8-10 hours Dependencies: Database migration system working correctly Risk: Medium (external service dependencies)

Problem

Current IndieAuth implementation may need updates based on production usage patterns and compliance requirements.

Implementation Notes

• Review existing ADR-021-indieauth-provider-strategy.md
• Implement any pending IndieAuth improvements
• Ensure full spec compliance

---

Medium Priority Items

These items SHOULD be completed for v1.1.0 if time permits.

3. Full-Text Search Implementation ✅

Priority: MEDIUM (Elevated to HIGH - implemented) ADR: ADR-034 Actual Effort: ~7 hours (including complete UI) Status: COMPLETE Implementation: SQLite FTS5 with full UI and API

Implementation Approach

• Use SQLite FTS5 extension
• Create shadow FTS table for note content
• Update on note create/update/delete
• Add search_notes() function to notes.py

---

4. Migration System Testing Suite

Priority: MEDIUM Estimated Effort: 4-5 hours Dependencies: Item #1 (Migration redesign) Risk: Low

Test Coverage Needed

• Migration ordering tests
• Rollback simulation tests
• Schema evolution tests
• Performance benchmarks
• CI/CD integration

---

Implementation Order

1. First: Complete Database Migration System Redesign (Critical)
2. Second: Add comprehensive migration tests
3. Third: IndieAuth improvements (if needed)
4. Fourth: Full-text search (if time permits)

Release Checklist

Before releasing v1.1.0:

• All CRITICAL items complete
• All tests passing
• Documentation updated
• CHANGELOG.md updated with all changes
• Version bumped to 1.1.0
• Migration guide written for production systems
• Release notes prepared
• Docker image tested with migrations

Risk Mitigation

Migration System Risks

• Risk: Breaking existing databases
• Mitigation: Comprehensive testing, backward compatibility, clear rollback procedures

Performance Risks

• Risk: Slow fresh installations (running all migrations)
• Mitigation: Migration performance testing, potential migration squashing in future

Deployment Risks

• Risk: Production upgrade failures
• Mitigation: Detailed upgrade guide, test on staging first, backup procedures

Notes for Implementation

For the Developer Implementing Item #1

1. Start with ADR-032 for complete design details
2. Check git history for original schema (commit a68fd57)
3. Test thoroughly - this is critical infrastructure
4. Consider edge cases:
   • Empty database
   • Partially migrated database
   • Corrupted migration tracking
   • Missing migration files

Key Files to Modify

1. /home/phil/Projects/starpunk/starpunk/database.py

   • Add INITIAL_SCHEMA_SQL constant
   • Modify init_db() function
   • Add helper functions

2. /home/phil/Projects/starpunk/tests/test_migrations.py

   • Add new test cases for initial schema
   • Test upgrade paths

3. /home/phil/Projects/starpunk/docs/architecture/database.md

   • Document schema evolution strategy
   • Explain dual schema constants

Success Metrics

• Zero database upgrade failures in production
• Fresh installation time < 1 second
• All tests passing
• Clear documentation for future maintainers
• Positive user feedback on stability

References

• ADR-031: Database Migration System Redesign
• ADR-032: Initial Schema SQL Implementation
• v1.1 Potential Features
• Migration Implementation Reports

---

Last Updated: 2025-11-24 Version: 1.0.0-rc.2 → 1.1.0 (planned)