feature: Tokens syncing with Github

[akshay-gupta7]

Is your feature request related to a problem? Please describe.

The ability to store design tokens on a GH repository and sync.

Definition of Done

Penpot Design Tokens ↔ GitHub Sync

---

1. Authentication & Authorization

• User can connect a GitHub account or organization via Personal Access Token (PAT).
• Required scopes are minimal and documented.
• Access token is securely stored and never logged.
• Connection status is clearly visible (connected repo, org/user, permissions).

---

2. Repository & Target Configuration

User must be able to configure:

• Repository Owner / Organization
• Repository Name
• Target Branch
• Base Directory Path
• File Naming Strategy(single file name or tokens' folder)

Validation Requirements:

• Repository exists
• Branch exists
• Path is writable
• Duplicate providers are prevented

---

3. Pull (GitHub → Penpot)

• Fetches token JSON files from configured directory.
• JSON is schema-validated before import.
• Clear handling of:
  • Created tokens
  • Updated tokens
  • Deleted tokens (behavior explicitly defined)

Error handling includes:

• Invalid JSON
• Schema mismatch
• Permission errors (403)
• Rate limiting (429)
• Missing files

---

4. Push (Penpot → GitHub)

• Produces deterministic output:
  • Consistent formatting
• No unintended files (e.g., .gitkeep unless explicitly required).
• Commit strategy defined:
  • Direct commit to branch OR
  • Create branch + Pull Request

Push Requirements:

• Meaningful commit message from the user

---

6. UX & Observability

UI must display:

• Last sync timestamp
• Last commit SHA or PR link
• Summary of changes (created / updated / deleted counts)

Operational requirements:

• Visible progress state
• Clear error messaging
• Retry capability
• Structured logging without exposing secrets

---

7. Security

• No access tokens stored in logs or analytics.
• All communication via HTTPS.
• Rate limit handling with backoff.
• Follows GitHub API best practices (conditional requests where applicable).

---

8. Testing Requirements

Unit Tests

• JSON parsing & schema validation
• File path mapping
• Reference resolution
• Conflict detection logic

Integration Tests

• Repository content listing (with pagination)
• Create/update file operations
• Permission failure handling

End-to-End Test

• Connect repository
• Pull sample tokens
• Modify token
• Push changes
• Verify commit or PR reflects expected output

---

9. Documentation

User Documentation must include:

• Setup instructions
• Required permissions
• Expected repository structure
• Troubleshooting guide

Developer Documentation must include:

• Sync architecture overview
• Pull algorithm
• Push algorithm
• Known limitations
• Performance considerations

---

Final Acceptance Criteria

The feature is considered Done when:

• Authentication works reliably.
• Pull and Push operations succeed without data corruption.
• Conflicts are handled gracefully.
• No security leaks occur.
• All required tests pass.
• Documentation is complete and up to date.