OpenNoodl/dev-docs/tasks/phase-3-editor-ux-overhaul/TASK-002-github-integration/GIT-OVERVIEW.md

GIT Series: Git & GitHub Integration

Overview

The GIT series transforms Noodl's version control experience from a manual, expert-only feature into a seamless, integrated part of the development workflow. By adding GitHub OAuth, surfacing git status in the dashboard, and encouraging good version control habits, we make collaboration accessible to all Noodl users.

Target Environment

• Editor: React 19 version only
• Runtime: Not affected (git is editor-only)
• Backwards Compatibility: Existing git projects continue to work

Task Dependency Graph

GIT-001 (GitHub OAuth)
    │
    ├──────────────────────────┐
    │                          │
    ▼                          ▼
GIT-002 (Dashboard Status)  GIT-003 (Repository Cloning)
    │
    ├──────────────────────────┐
    │                          │
    ▼                          ▼
GIT-004 (Auto-Init)        GIT-005 (Enhanced Push/Pull)

Task Summary

Task ID	Name	Est. Hours	Priority
GIT-001	GitHub OAuth Integration	14-20	Critical
GIT-002	Git Status Dashboard Visibility	11-16	High
GIT-003	Repository Cloning	13-18	High
GIT-004	Auto-Initialization & Commit Encouragement	13-19	Medium
GIT-005	Enhanced Push/Pull UI	17-23	Medium

Total Estimated: 68-96 hours

Implementation Order

Week 1-2: Authentication & Status

1. GIT-001 - GitHub OAuth (foundation for GitHub API access)
2. GIT-002 - Dashboard status (leverages DASH-002 project list)

Week 3: Cloning & Basic Flow

3. GIT-003 - Repository cloning (depends on OAuth for private repos)

Week 4: Polish & Encouragement

4. GIT-004 - Auto-initialization (depends on status detection)
5. GIT-005 - Enhanced push/pull (depends on status infrastructure)

Existing Infrastructure

The codebase already has solid git foundations to build on:

noodl-git Package

packages/noodl-git/src/
├── git.ts              # Main Git class
├── core/
│   ├── clone.ts        # Clone operations
│   ├── push.ts         # Push operations
│   ├── pull.ts         # Pull operations
│   └── ...
├── actions/            # Higher-level actions
└── constants.ts

Key existing methods:

• git.initNewRepo() - Initialize new repository
• git.clone() - Clone with progress
• git.push() - Push with progress
• git.pull() - Pull with rebase
• git.status() - Working directory status
• git.getBranches() - List branches
• git.getCommitsCurrentBranch() - Commit history

Version Control Panel

packages/noodl-editor/src/editor/src/views/panels/VersionControlPanel/
├── VersionControlPanel.tsx
├── components/
│   ├── GitStatusButton.tsx     # Push/pull status
│   ├── GitProviderPopout/      # Credentials management
│   ├── LocalChanges.tsx        # Uncommitted files
│   ├── History.tsx             # Commit history
│   └── BranchMerge.tsx         # Branch operations
└── context/
    └── fetch.context.ts        # Git state management

Credentials Storage

• GitStore - Stores credentials per-project encrypted
• trampoline-askpass-handler - Handles git credential prompts
• Currently uses PAT (Personal Access Token) for GitHub

Key Technical Decisions

OAuth vs PAT

Current: Personal Access Token per project

• User creates PAT on GitHub
• Copies to Noodl per project
• Stored encrypted in GitStore

New (GIT-001): OAuth + PAT fallback

• One-click GitHub OAuth
• Token stored globally
• PAT remains for non-GitHub remotes

Status Checking Strategy

Approach: Batch + Cache

• Check multiple projects in parallel
• Cache results with TTL
• Background refresh

Why: Git status requires opening each repo, which is slow. Caching makes dashboard responsive while keeping data fresh.

Auto-Initialization

Approach: Opt-out

• Git initialized by default
• Initial commit created automatically
• Can disable in settings

Why: Most users benefit from version control. Making it default reduces "I lost my work" issues.

Services to Create

Service	Location	Purpose
GitHubOAuthService	noodl-editor/services	OAuth flow, token management
GitHubApiClient	noodl-editor/services	GitHub REST API calls
ProjectGitStatusService	noodl-editor/services	Batch status checking, caching
CloneService	noodl-editor/services	Clone wrapper with progress
CommitReminderService	noodl-editor/services	Periodic commit reminders
ConflictResolutionService	noodl-editor/services	Conflict detection, resolution

Components to Create

Component	Package	Purpose
GitHubConnectButton	noodl-core-ui	OAuth trigger button
GitHubAccountCard	noodl-core-ui	Connected account display
GitStatusBadge	noodl-core-ui	Status indicator in list
CloneModal	noodl-core-ui	Clone flow modal
RepoBrowser	noodl-core-ui	Repository list/search
QuickCommitPopup	noodl-core-ui	Fast commit dialog
SyncStatusHeader	noodl-core-ui	Editor header sync status
BranchSelector	noodl-core-ui	Branch dropdown
PullPreviewModal	noodl-core-ui	Preview before pull

Dependencies

On DASH Series

• GIT-002 → DASH-002 (project list for status display)
• GIT-001 → DASH-001 (launcher context for account display)

External Packages

May need:

{
  "@octokit/rest": "^20.0.0"  // GitHub API client (optional)
}

Security Considerations

1. OAuth Tokens: Store with electron's safeStorage API
2. PKCE Flow: Use PKCE for OAuth (no client secret in app)
3. Token Scope: Request minimum necessary (repo, read:org, read:user)
4. Credential Cache: Clear on logout/disconnect
5. PAT Fallback: Encrypted per-project storage continues

Testing Strategy

Unit Tests

• OAuth token exchange
• Status calculation logic
• Conflict detection
• Default commit message generation

Integration Tests

• Clone from public repo
• Clone from private repo with auth
• Push/pull with mock remote
• Branch operations

Manual Testing

• Full OAuth flow
• Dashboard status refresh
• Clone flow end-to-end
• Commit reminder timing
• Conflict resolution

Cline Usage Notes

Before Starting Each Task

1. Read the task document completely
2. Review existing git infrastructure:
   • packages/noodl-git/src/git.ts
   • packages/noodl-editor/src/editor/src/views/panels/VersionControlPanel/
3. Check GitStore and credential handling

Key Gotchas

1. Git operations are async: Always use try/catch, git can fail
2. Repository paths: Use _retainedProjectDirectory from ProjectModel
3. Merge strategy: Noodl has custom merge for project.json (mergeProject)
4. Auth caching: Credentials cached by trampoline, may need clearing
5. Electron context: Some git ops need main process (deep links)

Testing Git Operations

# In tests directory, run git tests
npm run test:editor -- --grep="Git"

Success Criteria (Series Complete)

1. ✅ Users can authenticate with GitHub via OAuth
2. ✅ Git status visible in project dashboard
3. ✅ Users can clone repositories from UI
4. ✅ New projects have git by default
5. ✅ Users are reminded to commit regularly
6. ✅ Pull/push is intuitive with previews
7. ✅ Branch management is accessible

Future Work (Post-GIT)

The GIT series enables:

• COMP series: Shared component repositories
• DEPLOY series: Auto-push to frontend repo on deploy
• Community features: Public component sharing

Files in This Series

• GIT-001-github-oauth.md
• GIT-002-dashboard-git-status.md
• GIT-003-repository-cloning.md
• GIT-004-auto-init-commit-encouragement.md
• GIT-005-enhanced-push-pull.md
• GIT-OVERVIEW.md (this file)