Release Branch Consolidation Implementation Plan

Problem Statement

The Terraphim AI project has multiple release-related branches and tags that need to be consolidated into a single, perfect release. The current state shows:

v1.0.0 tag: Initial release with TUI and Server working, but Desktop app had dependency issues
v1.0.1 tag: Added Desktop app fixes with system tray synchronization
v1.0.2 tag: Points to a dependabot commit on main branch
release/v1.0.0 branch: Contains release commits but not fully merged to main
fix/github-actions-release-workflows branch: Current branch with GitHub Actions fixes
main branch: Has some commits not in release branches

The priority is to ensure TUI and REPL are fully functional first, then terraphim-server, and finally the desktop application.

Current State Analysis

Branch/Tag Relationships

Branches containing v1.0.0:

fix/github-actions-release-workflows (current)
release/v1.0.0
remotes/origin/fix/github-actions-release-workflows
remotes/origin/release/v1.0.0

Branches containing v1.0.1:

fix/github-actions-release-workflows (current)
release/v1.0.0
remotes/origin/fix/github-actions-release-workflows

v1.0.2 points to main branch (dependabot commit)

Component Status

1. TUI and REPL (Priority 1) ⚠️ NEEDS FIXES

Location: crates/terraphim_tui/

Current Issues:

Tests fail to compile with REPL features enabled
Test files reference registry.add_command() method that doesn't exist
Only register_command() and add_command_directory() methods exist in CommandRegistry

Test Compilation Errors:

error[E0599]: no method named `add_command` found for struct `CommandRegistry`
  --> crates/terraphim_tui/src/commands/tests.rs:207:18
  --> crates/terraphim_tui/src/commands/tests.rs:235:18
  --> crates/terraphim_tui/src/commands/tests.rs:238:18
  (and more...)

Files Affected:

crates/terraphim_tui/src/commands/tests.rs (8 occurrences of add_command())
crates/terraphim_tui/src/commands/registry.rs (implementation file)

Cargo.toml Configuration: crates/terraphim_tui/Cargo.toml

Version: 1.0.0
Features: repl, repl-full, repl-chat, repl-mcp, repl-file, repl-custom
Binary: terraphim-tui

2. Terraphim Server (Priority 2) ✅ COMPILES

Location: terraphim_server/

Status:

Tests compile successfully
Version in Cargo.toml: 0.2.3 (needs update to 1.0.0)
162 unit tests reported passing in v1.0.0 release notes

Test Output:

Finished `test` profile [unoptimized + debuginfo] target(s) in 49.91s
19 test executables created

Known Issues:

Version mismatch: Cargo.toml shows 0.2.3 but release is 1.0.0

3. Desktop Application (Priority 3) ⚠️ BUILD FAILS

Location: desktop/

Current Issues:

Frontend build fails due to svelte-jsoneditor HTML validation error
Version: 1.0.0 (correct)

Build Error:

[vite-plugin-svelte] node_modules/svelte-jsoneditor/components/modals/TransformWizard.svelte:94:2
`<tr>` cannot be a child of `<table>`. `<table>` only allows these children:
<caption>, <colgroup>, <tbody>, <thead>, <tfoot>, <style>, <script>, <template>

Dependency Information:

svelte-jsoneditor: ^0.21.6 (in package.json)
Svelte version: ^5.2.8
Issue is in dependency's code, not our code

Files Involved:

desktop/package.json
desktop/vite.config.ts
desktop/node_modules/svelte-jsoneditor/components/modals/TransformWizard.svelte

Release Documentation

Existing Documentation:

releases/v1.0.0/RELEASE_NOTES.md: Initial release notes
releases/v1.0.0/TAURI_DESKTOP_RELEASE.md: Desktop app release info
docs/artifacts/FINAL_COMPREHENSIVE_STATUS.md: Status showing 85% completion with blocking issues
docs/artifacts/FINAL_VALIDATION_STATUS.md: Test validation results

Key Findings from Reports:

162/162 tests passing for core components
TUI implementation synced from private repo
Desktop app reported as "FULLY FUNCTIONAL" in v1.0.1
svelte-jsoneditor issue was known and documented

Disabled Tests

Files Found:

./crates/terraphim_service/tests/openrouter_proxy_test.rs.disabled
./crates/terraphim_middleware/tests/atomic_haystack.rs.disabled
./crates/terraphim_middleware/tests/dual_haystack_validation_test.rs.disabled
./crates/terraphim_middleware/tests/atomic_roles_e2e_test.rs.disabled
./crates/terraphim_middleware/tests/atomic_document_import_test.rs.disabled
./crates/terraphim_middleware/tests/atomic_haystack_config_integration.rs.disabled
./crates/terraphim_multi_agent/src/llm_client.rs.disabled
./crates/terraphim_multi_agent/src/simple_llm_client.rs.disabled
./desktop/src-tauri/tests/extract_feature_tests.rs.disabled
./desktop/src-tauri/tests/comprehensive_cmd_tests.rs.disabled
./.github/workflows/ci-native.yml.disabled

Changes Since v1.0.1

Current branch (fix/github-actions-release-workflows) has:

GitHub Actions workflow fixes (4 workflow files modified)
Cross.toml configuration added (20 lines)
desktop/vite.config.ts modifications (7 lines added)
docker/Dockerfile.multiarch updates
New documentation: docs/github-actions-release-fix-plan.md
New test script: scripts/test-workflows.sh

Total: 9 files changed, 244 insertions(+), 14 deletions(-)

Proposed Solution

Phase 1: Fix TUI and REPL (Priority 1)

Objective: Make TUI fully functional with all REPL features working and tests passing.

Tasks:

Fix CommandRegistry Test Methods (30 min)
- Update test files to use correct method names
- Replace registry.add_command(parsed) with registry.register_command(parsed)
- Files to modify:
  - crates/terraphim_tui/src/commands/tests.rs (8 locations)
Run TUI Tests (15 min)

cargo test -p terraphim_tui --features repl-full

Verify all tests pass
Fix any remaining compilation errors

Build and Test TUI Binary (15 min)

cargo build -p terraphim_tui --bin terraphim-tui --features repl-full --release
./target/release/terraphim-tui --help
./target/release/terraphim-tui repl

Verify binary builds
Test REPL interactive mode
Test all REPL commands

Verify TUI Features (20 min)
- Test basic search functionality
- Test configuration commands
- Test role management
- Test MCP tools integration (if feature enabled)
- Test chat functionality (if feature enabled)

Success Criteria:

All TUI tests pass with repl-full features
Binary builds without errors
REPL starts and responds to commands
All documented commands work as expected

Phase 2: Verify and Update Server (Priority 2)

Objective: Ensure terraphim_server is fully functional and version numbers are correct.

Tasks:

Update Server Version (5 min)
- Modify terraphim_server/Cargo.toml
- Change version from 0.2.3 to 1.0.0
- Update any related version references
Run Server Tests (10 min)

cargo test -p terraphim_server

Verify all tests pass
Expected: 162+ tests passing

Build Server Binary (10 min)

cargo build -p terraphim_server --release

Verify binary size (~15MB expected)

Test Server Functionality (20 min)

./target/release/terraphim_server --role Default

Verify server starts on port 8000
Test health endpoint
Test search API
Test knowledge graph endpoints
Verify with TUI client connection

Success Criteria:

Version updated to 1.0.0
All tests pass
Server binary builds and runs
API endpoints respond correctly
TUI can connect to server

Phase 3: Fix Desktop Application (Priority 3)

Objective: Resolve svelte-jsoneditor build issue and get Desktop app building.

Tasks:

Fix svelte-jsoneditor Issue (30 min)

Option A: Disable Strict HTML Validation (RECOMMENDED)
- Modify desktop/vite.config.ts
- Add compiler option to disable strict validation:

export default defineConfig({
  plugins: [
    svelte({
      compilerOptions: {
        disallowInvalidTags: false,
      },
    }),
  ],
});

Option B: Downgrade svelte-jsoneditor

cd desktop
yarn add [email protected]

Option C: Remove svelte-jsoneditor (if not critical)

Search codebase for usage
If minimal usage, remove dependency and related code

Build Desktop Frontend (10 min)

cd desktop
yarn build

Verify build succeeds
Check dist/ directory created

Build Tauri Desktop App (20 min)

cd desktop
yarn tauri build

Verify .dmg created (macOS)
Check app bundle size

Test Desktop Application (30 min)
- Launch Terraphim Desktop.app
- Test system tray functionality
- Test search interface
- Test configuration wizard
- Test role selector
- Test knowledge graph visualization
- Test global shortcuts (Ctrl+Shift+T)

Success Criteria:

Frontend builds without errors
Tauri app builds successfully
All major features work in desktop app
System tray integration works
Auto-updater configured correctly

Phase 4: Branch Consolidation

Objective: Merge all release work into a clean, consolidated release branch.

Tasks:

Create Consolidated Release Branch (10 min)

git checkout -b release/v1.0.3-consolidated

Cherry-pick Critical Fixes (30 min)
- Review commits on fix/github-actions-release-workflows
- Cherry-pick GitHub Actions fixes
- Cherry-pick TUI fixes (from Phase 1)
- Cherry-pick server version updates (from Phase 2)
- Cherry-pick desktop fixes (from Phase 3)
Update All Version Numbers (15 min)
- Ensure all Cargo.toml files show 1.0.3 (or appropriate version)
- Update desktop/package.json
- Update desktop/src-tauri/tauri.conf.json
Run Full Test Suite (20 min)

cargo test --workspace
cd desktop && yarn test

Build All Artifacts (30 min)

# TUI
cargo build -p terraphim_tui --features repl-full --release

# Server
cargo build -p terraphim_server --release

# Desktop
cd desktop && yarn tauri build

Create Release Documentation (30 min)
- Update CHANGELOG.md
- Create release/v1.0.3/RELEASE_NOTES.md
- Document all fixes applied
- List all tested features
- Note any known issues

Success Criteria:

Clean branch with consolidated fixes
All version numbers consistent
All tests passing
All binaries build successfully
Complete release documentation

Phase 5: Merge to Main and Tag

Objective: Merge consolidated release to main and create final release tag.

Tasks:

Merge to Main (10 min)

git checkout main
git merge --no-ff release/v1.0.3-consolidated

Create Release Tag (10 min)

git tag -a v1.0.3 -m "Release v1.0.3 - Fully functional TUI, Server, and Desktop

- TUI with complete REPL functionality
- Server with correct version numbers
- Desktop app with fixed build issues
- All critical tests passing
- Comprehensive release documentation"

Push to Remote (5 min)

git push origin main
git push origin v1.0.3
git push origin release/v1.0.3-consolidated

Create GitHub Release (30 min)
- Go to GitHub Releases
- Create new release from v1.0.3 tag
- Upload release artifacts:
  - terraphim-tui binary
  - terraphim_server binary
  - TerraphimDesktop_v1.0.3_aarch64.dmg
  - App bundles (.app directories as .tar.gz)
- Copy release notes from documentation
- Publish release
Clean Up Old Branches (10 min)

git branch -D release/v1.0.0
git branch -D fix/github-actions-release-workflows
git push origin --delete release/v1.0.0
git push origin --delete fix/github-actions-release-workflows

Success Criteria:

Main branch has all fixes
Release tag created and pushed
GitHub release published with artifacts
Old branches cleaned up
Release is fully documented

Risk Mitigation

Known Risks

TUI Test Fixes May Reveal Deeper Issues
- Mitigation: Fix tests incrementally, run after each change
- Fallback: Review private repo sync to ensure all code present
svelte-jsoneditor Fix May Break Other Components
- Mitigation: Test all UI components after applying fix
- Fallback: Try alternative solutions (downgrade or remove)
Version Number Inconsistencies
- Mitigation: Use script to update all versions consistently
- Verification: Grep for version strings before committing
Disabled Tests May Indicate Missing Features
- Mitigation: Review each disabled test, determine if needed
- Decision: Re-enable if critical, document if optional

Rollback Plan

If critical issues are discovered:

Before Merge to Main:
- Simply abandon release branch
- Fix issues on feature branch
- Restart consolidation process
After Merge to Main:
- Revert merge commit: git revert -m 1 <merge-commit>
- Create hotfix branch
- Apply fixes and re-merge

Timeline Estimate

Phase 1 (TUI/REPL): 1.5 hours
Phase 2 (Server): 1 hour
Phase 3 (Desktop): 1.5 hours
Phase 4 (Consolidation): 2 hours
Phase 5 (Merge & Release): 1 hour

Total Estimated Time: 7 hours

Success Metrics

Technical Metrics

✅ All TUI tests pass with repl-full features
✅ All server tests pass (162+)
✅ Desktop app builds without errors
✅ All binaries under expected size limits
✅ Zero compilation warnings (or documented exceptions)

Functional Metrics

✅ TUI REPL responds to all documented commands
✅ Server API endpoints return correct responses
✅ Desktop app launches and all features accessible
✅ System tray integration works
✅ Search functionality works in all interfaces

Process Metrics

✅ Single consolidated release branch
✅ All version numbers consistent
✅ Comprehensive release documentation
✅ GitHub release published with all artifacts
✅ Old branches cleaned up

Post-Release Actions

Update Documentation
- Update README.md with v1.0.3 information
- Update installation instructions
- Update feature list
Monitor for Issues
- Watch GitHub issues for bug reports
- Monitor CI/CD pipelines
- Check download statistics
Plan Next Release
- Review disabled tests
- Evaluate features for v1.1.0
- Address any known limitations
Update Project Files
- Update memories.md with consolidation process
- Update lessons-learned.md with insights
- Clear scratchpad.md for next tasks

Notes

This plan prioritizes functionality over perfection
TUI and REPL are critical path items
Desktop app is important but lowest priority
All changes should be committed incrementally
Each phase should be tested before moving to next
Documentation should be updated continuously
Do not skip verification steps

Document Version: 1.0 Created: 2025-11-06 Status: Ready for Approval Next Step: Get user approval before proceeding with Phase 1

UPDATED FINDINGS (2025-11-06 22:22)

Branch Analysis with Release Tags

Branches containing v1.0.0:

fix/github-actions-release-workflows (current)
release/v1.0.0
remotes/origin/fix/github-actions-release-workflows
remotes/origin/release/v1.0.0

Branches containing v1.0.1:

fix/github-actions-release-workflows (current)
release/v1.0.0 (local)
remotes/origin/fix/github-actions-release-workflows

Branches containing v1.0.2:

fix/github-actions-release-workflows (current)
release/v1.0.0 (local)
remotes/origin/fix/github-actions-release-workflows
remotes/origin/release/v1.0.0

Key Observation: The remotes/origin/release/v1.0.0 does NOT contain v1.0.1, but local release/v1.0.0 does!

Commit Timeline

Between v1.0.0 and v1.0.1 (4 commits):

b54ba044 (tag: v1.0.1, release/v1.0.0) Fix system tray synchronization and add comprehensive test report for v1.0.1
5ab3d07d (origin/release/v1.0.0) Fix Desktop app: Add missing role selector UI to ThemeSwitcher component and correct Tauri binary configuration
9f44b215 chore: add compressed app bundles and GitHub release notes
bf2791f4 release: v1.0.0 - Complete release with Tauri desktop app

Between v1.0.1 and v1.0.2: No commits (they point to same base)

Between v1.0.1 and current HEAD (1 commit):

d9478102 (HEAD -> fix/github-actions-release-workflows) Fix GitHub Actions release workflows for all platforms

Open Issues Relevant to Release

Critical:

#289: GitHub Actions release workflows failing across all platforms (bug, 11 hours ago)
#286: Release: terraphim-ai v1.0.0 [META] (2 days ago)

TUI/REPL Related:

#273: Phase 3: Complete REPL Implementation (Week 3)
#261: Fix TUI/REPL offline mode to use TuiService instead of mock data (bug, enhancement, 10 days ago)
#248: Fix remaining 14 failing TUI tests - MAJOR PROGRESS: 70% improvement (12 days ago)

Total Open Issues: 58

Revised Understanding

v1.0.2 tag is NOT on main - it's a lightweight tag on the same commit as v1.0.1
Local release/v1.0.0 branch is ahead of remote origin/release/v1.0.0 by at least one commit (v1.0.1)
Current branch (fix/github-actions-release-workflows) has all tags and is 1 commit ahead of v1.0.1
GitHub Actions workflows are actively failing (issue #289)

Updated Recommendation

Given this analysis, I recommend:

Do NOT create v1.0.3 - instead consolidate into v1.1.0 to signify the fixes and improvements
Push local release/v1.0.0 to origin to sync the v1.0.1 tag
Focus on fixing the three priorities as outlined, but be aware of GitHub Actions issues
Consider issue #248 - there are known TUI test issues that may be related to what we found