ss-tools/specs/011-git-integration-dashboard/tasks.md

# Tasks: Git Integration Plugin

**Feature**: Git Integration for Dashboard Development
**Status**: Completed with implementation drift identified on 2026-07-01
**Total Tasks**: 43 baseline tasks, plus remediation and UX backlog below

## Phase 1: Setup
**Goal**: Initialize project structure and dependencies.

- [x] T001 Install GitPython dependency in `backend/requirements.txt`
- [x] T002 Create backend directory structure (routes, models, plugins, services)
- [x] T003 Create frontend directory structure (components, routes, services)

## Phase 2: Foundational
**Goal**: Implement core data models and service skeletons.
**Prerequisites**: Phase 1

- [x] T004 Create Git Pydantic models (Branch, Commit, DashboardChange) in `backend/src/api/routes/git_schemas.py`
- [x] T005 Create GitServerConfig and Environment SQLAlchemy models in `backend/src/models/git.py`
- [x] T006 Implement GitService class skeleton with GitPython init in `backend/src/services/git_service.py`
- [x] T007 Implement GitPlugin class skeleton inheriting PluginBase in `backend/src/plugins/git_plugin.py`

## Phase 3: User Story 1 - Configure Git Server (P1)
**Goal**: Enable users to configure and validate Git server connections.
**Prerequisites**: Phase 2

- [x] T008 [US1] Implement `GitService.test_connection` method in `backend/src/services/git_service.py`
- [x] T009 [US1] Implement GET/POST `/api/git/config` endpoints in `backend/src/api/routes/git.py`
- [x] T010 [US1] Create `frontend/src/services/gitService.js` API client
- [x] T011 [US1] Create `frontend/src/components/tools/ConnectionForm.svelte` (or similar) for Git config
- [x] T012 [US1] Implement Settings page at `frontend/src/routes/settings/git/+page.svelte`

## Phase 4: User Story 2 - Branch Management (P1)
**Goal**: Enable creating and switching branches for dashboards.
**Prerequisites**: Phase 3

- [x] T013 [US2] Implement `GitService` branch operations (list, create, checkout) in `backend/src/services/git_service.py`
- [x] T014 [US2] Implement `GitService.init_repo` (clone/init strategy) in `backend/src/services/git_service.py`
- [x] T015 [US2] Implement GET/POST `/api/git/branches` endpoints in `backend/src/api/routes/git.py`
- [x] T016 [US2] Implement POST `/api/git/checkout` endpoint in `backend/src/api/routes/git.py`
- [x] T017 [US2] Create `frontend/src/components/git/BranchSelector.svelte` component
- [x] T018 [US2] Update Dashboard page to include Git controls container

## Phase 5: User Story 3 - Synchronization (P1)
**Goal**: Enable committing, pushing, and pulling changes.
**Prerequisites**: Phase 4

- [x] T019 [US3] Implement Dashboard export/unpack logic (using SupersetClient/superset_tool) in `backend/src/plugins/git_plugin.py`
- [x] T020 [US3] Implement `GitService` status and diff generation methods in `backend/src/services/git_service.py`
- [x] T021 [US3] Implement `GitService` commit, push, and pull methods in `backend/src/services/git_service.py`
- [x] T022 [US3] Implement `/api/git/sync`, `/commit`, `/push`, `/pull` endpoints in `backend/src/api/routes/git.py`
- [x] T023 [US3] Create `frontend/src/components/git/CommitModal.svelte` with diff viewer
- [x] T024 [US3] Create `frontend/src/components/git/ConflictResolver.svelte` (Keep Mine/Theirs UI)

## Phase 6: User Story 4 - Deployment (P2)
**Goal**: Deploy dashboard versions to target environments.
**Prerequisites**: Phase 5

- [x] T025 [US4] Implement Environment CRUD endpoints in `backend/src/api/routes/git.py`
- [x] T026 [US4] Implement deployment logic (zip packing + Import API) in `backend/src/plugins/git_plugin.py`
- [x] T027 [US4] Implement POST `/api/git/deploy` endpoint in `backend/src/api/routes/git.py`
- [x] T028 [US4] Create Deployment modal/interface in `frontend/src/components/git/DeploymentModal.svelte`

## Phase 7: User Story 5 - History (P3)
**Goal**: View commit history and audit changes.
**Prerequisites**: Phase 5

- [x] T029 [US5] Implement `GitService.get_history` method in `backend/src/services/git_service.py`
- [x] T030 [US5] Implement GET `/api/git/history` endpoint in `backend/src/api/routes/git.py`
- [x] T031 [US5] Create `frontend/src/components/git/CommitHistory.svelte` component
- [x] T032 [US5] Integrate History viewer into Dashboard page

## Phase 8: Polish & Cross-Cutting
**Goal**: Finalize error handling, UI feedback, and performance.

- [x] T033 Add comprehensive error handling for Git operations (timeouts, auth failures)
- [x] T034 Add loading states and progress indicators to all Git UI components
- [x] T035 Verify offline mode behavior and graceful degradation

## Dependencies

- US1 -> US2 -> US3 -> US4
- US3 -> US5
- US1 is the critical path.

## Implementation Strategy
- MVP: Complete US1, US2, and US3 (Configure, Branch, Sync). This allows local-only versioning if remote is optional, or full sync if remote is configured.
- Incremental: Add Deployment (US4) and History (US5) after core sync workflow is stable.

## Phase 9: Operational Debug (2026-03-08)
**Goal**: Validate mismatch between configured Git server URL and repository origin URL during push flow.

- [x] D001 Diagnose source-of-truth mismatch for server URL in push flow
- [x] D002 Validate diagnosis with backend push diagnostics logs
- [x] D003 Apply behavioral fix only after diagnosis confirmation

## Phase 10: Operational Debug (2026-03-08)
**Goal**: Diagnose unexpected 409 on pull caused by unfinished merge detection.

- [x] D004 Add pull diagnostics logs for merge marker, repo path, branch, and binding metadata
- [x] D005 Confirm root cause hypothesis from new diagnostics before applying any behavior fix
- [x] D006 Implement richer 409 API response for unfinished merge (repo path, branch, explicit manual steps)

## Phase 11: Operational Debug (2026-03-08)
**Goal**: Add GitManager remediation dialog for unfinished merge 409 with actionable guidance.

- [x] D007 Implement unresolved-merge resolution dialog in `frontend/src/components/git/GitManager.svelte`
- [x] D008 Add frontend contract test for unfinished-merge dialog behavior in `frontend/src/components/git/__tests__/git_manager.unfinished_merge.integration.test.js`

## Phase 12: Branch Naming Convention Update (2026-05-27)
**Goal**: Переименование ветки `main` → `prod` для соответствия environment stages.
**Status**: Target completed in spec, implementation drift found on 2026-07-01

### Audit Finding (2026-07-01)
Live UI and source inspection show remaining `main` usage in backend defaults and frontend release flow. Treat the checked items below as intended migration scope, not as verified current behavior.

### Backend Changes
- [x] B001 Update `_ensure_gitflow_branches` to create `prod`, `dev`, `preprod` instead of `main`, `dev`, `preprod`
- [x] B002 Update `create_branch` default parameter from `main` to `prod`
- [x] B003 Update remote providers (GitHub, GitLab, Gitea) to use `prod` as default_branch

### Frontend Changes
- [x] F001 Update `BranchSelector.svelte` default currentBranch from `main` to `prod`
- [x] F002 Update `GitManager.svelte` initial state from `main` to `prod`
- [x] F003 Update `GitReleasePanel.svelte` UI label from `PROD (main)` to `PROD (prod)`
- [x] F004 Update `git-utils.js` promote defaults: `preprod → prod` instead of `preprod → main`

### Tests
- [x] T001 Update all test fixtures from `main` to `prod` in `gitService.test.js`

## Phase 12A: Branch Naming Remediation (Required)
**Goal**: Bring implementation back in line with the `dev -> preprod -> prod` branch model.
**Status**: Implemented 2026-07-01
**Priority**: P0
**Prerequisites**: Current baseline Git workflow must remain operational.

### Backend Remediation
- [x] R001 Change `GitServerConfig.default_branch` fallback from `main` to `prod`
- [x] R002 Change `GitServerConfigBase.default_branch` schema fallback from `main` to `prod`
- [x] R003 Update `_ensure_gitflow_branches` to create/use `prod`, `dev`, `preprod`, with `prod` replacing `main` as production branch
- [x] R004 Update generic feature branch creation default source from `main` to `dev`
- [x] R005 Update GitHub repository creation default branch from `main` to `prod`
- [x] R006 Update GitLab repository creation default branch from `main` to `prod`
- [x] R007 Update Gitea repository creation default branch from `main` to `prod`
- [x] R008 Preserve legacy `main/master` compatibility for existing repositories without promoting those names as defaults
- [x] R009 Add/update backend regression tests for provider default branch payloads and API model defaults

### Frontend Remediation
- [x] R010 Update `GitManagerModel` initial `currentBranch` from `main` to `prod`
- [x] R011 Update `BranchModel` and `BranchSelector` default branch from `main` to `prod`
- [x] R012 Update `applyGitflowStageDefaults`: `PREPROD` promotes `preprod -> prod`
- [x] R013 Update `GitReleasePanel` pipeline label to `PROD (prod)`
- [x] R014 Prevent `main -> main` release action; show "No next promotion from PROD" or deploy/rollback options
- [x] R015 Add/update frontend regression tests for branch/release payload defaults
- [x] R016 Browser-validate `/git` branch selector and release flow after fixes

### Documentation Remediation
- [x] R017 Update API contract examples from `main` to `prod`
- [x] R018 Update quickstart to describe BI-friendly `DEV -> PREPROD -> PROD` workflow
- [x] R019 Re-run this spec audit and mark Phase 12 as verified after tests/browser checks pass

## Phase 13: Feature & Hotfix Branch Support (Completed)
**Goal**: Расширить модель веток для поддержки параллельной разработки нескольких фич и срочных исправлений.
**Status**: Completed 2026-07-01
**Priority**: P2
**Estimated Effort**: 25-30 hours

### Backend Implementation
- [x] B010 Implement `merge_branch` method in `GitService` for merging source_branch into target_branch
- [x] B011 Add conflict detection and handling in `merge_branch` (abort on conflicts, return status)
- [x] B012 Implement `delete_branch` method with protection for environment branches (dev/preprod/prod)
- [x] B013 Extend `list_branches` to group branches by type (Environment / Feature / Hotfix)
- [x] B014 Add branch name validation (regex: `^[a-zA-Z0-9][a-zA-Z0-9._\/\-]*$`, no `..`, no leading `/`)
- [x] B015 Implement branch protection rules (optional: require MR for prod)
- [x] B016 Add POST `/api/git/merge` endpoint for branch merging
- [x] B017 Add DELETE `/api/git/branches/{name}` endpoint for branch deletion
- [x] B018 Add unit tests for merge_branch with conflict scenarios (38 tests, all pass)
- [x] B019 Add integration tests for feature branch workflow (create → commit → merge → delete)

### Frontend Implementation
- [x] F010 Redesign `BranchSelector.svelte` with grouped dropdown (Environment / Feature / Hotfix)
- [x] F011 Create `CreateBranchDialog.svelte` with type selection (feature/hotfix/bugfix), name validation, source branch selection
- [x] F012 Add merge button to `GitManager.svelte` for feature branches (visible when currentBranch starts with `feature/`)
- [x] F013 Create `MergeDialog.svelte` with diff preview, conflict handling, auto-delete option
- [x] F014 Extend `GitReleasePanel.svelte` to support merge from feature branches to dev
- [x] F015 Add branch type badges (Environment / Feature / Hotfix) with color coding
- [x] F016 Implement branch deletion UI with confirmation dialog
- [x] F017 Add i18n keys for new branch management features (en/ru)
- [x] F018 Add UX tests for branch creation and merge workflows
- [x] F019 Add integration tests for feature branch lifecycle

### Documentation
- [x] D010 Update user guide with feature branch workflow
- [x] D011 Add branch naming conventions to documentation
- [x] D012 Create troubleshooting guide for merge conflicts

### Dependencies
- B010 → B011 → B016 (merge implementation chain)
- B012 → B017 (delete implementation)
- B013 → F010 (grouped list → UI)
- F011 → F013 (create dialog → merge dialog)
- All backend tasks should be completed before frontend tasks

### Risks & Mitigations
- **Risk**: Merge conflicts in YAML files may be complex
  - **Mitigation**: Use existing ConflictResolver component, provide clear error messages
- **Risk**: Branch protection may slow down workflow for small teams
  - **Mitigation**: Make protection rules optional via GitServerConfig settings
- **Risk**: Auto-delete may cause work loss if misconfigured
  - **Mitigation**: Require explicit confirmation, add "undo" option for 5 minutes

### Success Criteria
- Users can create feature branches from dev with proper naming validation
- Users can merge feature branches back to dev with conflict resolution
- Users can delete feature branches after successful merge
- Branch list is grouped by type for easy navigation
- Merge conflicts are handled gracefully with clear user guidance

## Phase 14: BI Developer UX Improvements (Planned)
**Goal**: Make Git management understandable and safe for BI developers and Superset analysts.
**Status**: Planned
**Priority**: P1 after Phase 12A
**Estimated Effort**: 20-30 hours

### UX Foundation
- [x] U001 Add Git modal pipeline header: `DEV (dev) -> PREPROD (preprod) -> PROD (prod)`
- [x] U002 Show current branch, lifecycle stage, changed file count, and recommended next action
- [x] U003 Rename primary UI actions to BI workflow terms while keeping Git terms as secondary labels
- [x] U004 Move raw Git diagnostics into advanced sections. Raw diff and repository status payload are now behind expandable advanced sections.

### Branch UX
- [x] U010 Redesign branch selector groups: Environment, Feature, Hotfix, Legacy/Advanced
- [x] U011 Hide or de-emphasize `origin/*` remote refs in the primary selector
- [x] U012 Mark `main/master` as legacy when present
- [x] U013 Add branch type badges and explanatory tooltips. Branch selector now shows ENV/FEATURE/HOTFIX/LEGACY badges with titles.

### Repository Setup UX
- [x] U020 Split setup into "Create new repository" and "Connect existing repository". Init panel now has a segmented create/connect flow.
- [x] U021 Show pre-action summary: default branch `prod` and branches to create
- [x] U022 After initialization, guide the user to sync the current Superset dashboard. Init copy and workspace empty state point users to Sync after repository binding.
- [x] U023 Add empty/error states for no configured Git servers and invalid remote URL. Init panel now has explicit no-server and URL validation states.

### Change Review UX
- [x] U030 Add semantic change summary above YAML diff
- [x] U031 Categorize changes into charts, datasets, dashboard metadata, databases, filters, and other files
- [x] U032 Rename `LLM` button to "Generate description"
- [x] U033 Add commit message templates for common BI changes
- [x] U034 Keep raw YAML diff expandable and searchable

### Release and Deploy Guardrails
- [x] U040 Add PROD action confirmation summary: dashboard name, source branch, target environment, last commit, author, changed files. Implemented in the Git manager deploy confirmation with backend `last_commit_*` status metadata.
- [x] U041 Require reason for direct merge and show audit warning. Direct mode now shows audit warning, requires reason, and disables promote until provided.
- [x] U042 Replace invalid PROD promotion states with deploy/rollback options
- [x] U043 Add rollback entry points from history and PROD state. Commit history now exposes rollback-by-revert, and PROD operations link users to history rollback.

### Error Recovery UX
- [x] U050 Move checkout blocking errors from global sticky toasts into modal-scoped banners
- [x] U051 Provide recovery actions: save version, inspect files, open conflict resolver, retry, dismiss. Merge recovery dialog exposes continue/save, command inspection, conflict resolver, refresh/retry, abort, and dismiss actions.
- [x] U052 Keep detailed backend diagnostics available in expandable sections. Workspace advanced diagnostics exposes the raw repository status payload.
- [x] U053 Add browser tests for checkout conflict, unfinished merge, push rejected, and no-repo setup states. Added Playwright browser-state coverage in `frontend/e2e/tests/git.e2e.js`.

### Success Criteria
- A BI developer can identify the next safe action within 10 seconds of opening Git management.
- New repo setup clearly communicates branch model before making changes.
- PROD-affecting actions always show target and source context before execution.
- Legacy `main/master` refs do not confuse the primary `prod` workflow.