feat: implement universal icon system with Phosphor Icons
- Install @phosphor-icons/react package - Create centralized Icon component with size/weight/color variants - Create icon registry with 34 icons across 5 categories - Replace all raw Unicode symbols with proper icon components - Add icons to navigation, buttons, status indicators, git operations - Add icon CSS with consistent sizing and spacing - Fix type definitions for Phosphor icon compatibility Quality gates: typecheck ✓, lint ✓, build ✓ (375KB bundle)
This commit is contained in:
Fusion
@@ -0,0 +1,2 @@
|
||||
schema: spec-driven
|
||||
created: 2026-05-19
|
||||
@@ -0,0 +1,154 @@
|
||||
# Documentation Overhaul - Design
|
||||
|
||||
## Documentation Structure
|
||||
|
||||
```
|
||||
docs/
|
||||
├── README.md # Documentation index
|
||||
├── architecture/
|
||||
│ ├── backend.md # Backend architecture
|
||||
│ ├── frontend.md # Frontend architecture
|
||||
│ ├── database.md # Database schema
|
||||
│ └── deployment.md # Deployment architecture
|
||||
├── features/
|
||||
│ ├── projects.md # Project management
|
||||
│ ├── repositories.md # Git repositories
|
||||
│ ├── workspace.md # Repository workspace
|
||||
│ ├── git-history.md # Git history visualization
|
||||
│ ├── auth.md # Authentication
|
||||
│ ├── tool-types.md # Tool type management
|
||||
│ └── settings.md # User settings
|
||||
├── api/
|
||||
│ ├── README.md # API overview
|
||||
│ ├── auth.md # Auth endpoints
|
||||
│ ├── projects.md # Project endpoints
|
||||
│ ├── repositories.md # Repository endpoints
|
||||
│ └── users.md # User endpoints
|
||||
├── deployment/
|
||||
│ ├── docker.md # Docker setup
|
||||
│ ├── traefik.md # Traefik configuration
|
||||
│ ├── authentik.md # Authentik setup
|
||||
│ └── environment.md # Environment variables
|
||||
├── development/
|
||||
│ ├── setup.md # Development setup
|
||||
│ ├── testing.md # Testing strategy (moved from README)
|
||||
│ ├── contributing.md # How to contribute
|
||||
│ └── quality-gates.md # Code quality
|
||||
└── templates/
|
||||
├── feature-doc.md # Template for new features
|
||||
├── api-endpoint.md # Template for API docs
|
||||
└── architecture.md # Template for architecture docs
|
||||
```
|
||||
|
||||
## README.md Structure
|
||||
|
||||
```markdown
|
||||
# Headquarter
|
||||
|
||||
## Overview
|
||||
Short description of what the project is and does.
|
||||
|
||||
## Features
|
||||
- Feature 1 (with link to docs)
|
||||
- Feature 2 (with link to docs)
|
||||
|
||||
## Quick Start
|
||||
1. Clone repo
|
||||
2. Copy .env.example to .env
|
||||
3. docker compose up
|
||||
4. Open http://localhost:5173
|
||||
|
||||
## Architecture
|
||||
Link to architecture docs.
|
||||
|
||||
## Documentation
|
||||
- [User Guide](docs/features/)
|
||||
- [API Docs](docs/api/)
|
||||
- [Deployment](docs/deployment/)
|
||||
- [Development](docs/development/)
|
||||
|
||||
## Tech Stack
|
||||
- Backend: FastAPI + SQLAlchemy + PostgreSQL
|
||||
- Frontend: React + TypeScript + Vite
|
||||
- Auth: Authentik (OAuth2)
|
||||
- Deployment: Docker + Traefik
|
||||
```
|
||||
|
||||
## Documentation Templates
|
||||
|
||||
### Feature Documentation Template
|
||||
```markdown
|
||||
# Feature Name
|
||||
|
||||
## Overview
|
||||
What does this feature do?
|
||||
|
||||
## How to Use
|
||||
Step-by-step user guide.
|
||||
|
||||
## Screenshots/Diagrams
|
||||
Visual aids.
|
||||
|
||||
## API Endpoints
|
||||
Related API endpoints.
|
||||
|
||||
## Configuration
|
||||
Relevant config options.
|
||||
|
||||
## Related Features
|
||||
Links to related docs.
|
||||
```
|
||||
|
||||
### API Endpoint Template
|
||||
```markdown
|
||||
## GET /api/endpoint
|
||||
|
||||
**Description:** What this endpoint does.
|
||||
|
||||
**Authentication:** Required/Optional
|
||||
|
||||
**Request:**
|
||||
- Query params
|
||||
- Body schema
|
||||
|
||||
**Response:**
|
||||
- Success schema
|
||||
- Error codes
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
curl /api/endpoint
|
||||
```
|
||||
```
|
||||
|
||||
## Auto-Documentation Process
|
||||
|
||||
For new features, documentation should be created:
|
||||
|
||||
1. **During implementation** (not after):
|
||||
- When creating a new feature, create its doc file
|
||||
- Use the template from docs/templates/
|
||||
- Update README features list
|
||||
|
||||
2. **In the same commit**:
|
||||
- Code changes + doc changes in same PR
|
||||
- Review docs alongside code
|
||||
|
||||
3. **Checklist**:
|
||||
- [ ] Feature doc created in docs/features/
|
||||
- [ ] API endpoints documented in docs/api/
|
||||
- [ ] README updated with feature link
|
||||
- [ ] Architecture doc updated if needed
|
||||
|
||||
## Maintenance
|
||||
|
||||
- **Monthly review**: Check for outdated docs
|
||||
- **Version tracking**: Tag docs with app version
|
||||
- **OpenSpec integration**: Link to OpenSpec changes for context
|
||||
|
||||
## Tools
|
||||
|
||||
- **Markdown**: All docs in Markdown
|
||||
- **Mermaid**: Diagrams in Mermaid syntax
|
||||
- **FastAPI docs**: Auto-generated from code
|
||||
- **GitHub Pages**: Optional static site generation
|
||||
@@ -0,0 +1,56 @@
|
||||
# Documentation Overhaul
|
||||
|
||||
## Problem
|
||||
|
||||
The project has grown significantly but documentation hasn't kept up:
|
||||
|
||||
- **README is minimal**: Only contains testing strategy, no project overview
|
||||
- **No feature documentation**: Users can't discover what the app does
|
||||
- **No API docs**: Developers have to read source code
|
||||
- **No deployment guide**: Docker/Traefik setup is tribal knowledge
|
||||
- **No architecture docs**: New contributors can't understand the codebase
|
||||
- **No user guide**: Features like repo workspace, git history aren't explained
|
||||
- **OpenSpec changes aren't linked**: Completed changes exist but aren't referenced
|
||||
|
||||
## Solution
|
||||
|
||||
Create a comprehensive documentation system:
|
||||
|
||||
1. **Rewrite README**: Project overview, features, quick start, architecture
|
||||
2. **Create docs/ directory**: Structured documentation
|
||||
3. **Document all features**: What exists and how to use it
|
||||
4. **Create API documentation**: Auto-generated + manual docs
|
||||
5. **Create deployment guide**: Docker, Traefik, Authentik setup
|
||||
6. **Create architecture docs**: Backend, frontend, data flow
|
||||
7. **Create documentation templates**: For future features
|
||||
8. **Create CONTRIBUTING.md**: How to add docs for new features
|
||||
|
||||
## Benefits
|
||||
|
||||
- **Onboarding**: New developers understand the project in minutes
|
||||
- **Discovery**: Users discover features they didn't know existed
|
||||
- **Maintenance**: Architecture docs help refactoring decisions
|
||||
- **Deployment**: Clear setup instructions reduce support burden
|
||||
- **Future-proof**: Templates ensure new features get documented
|
||||
|
||||
## Scope
|
||||
|
||||
### What gets documented:
|
||||
- All existing features (projects, repos, git history, workspace, auth, etc.)
|
||||
- Architecture (backend, frontend, database, deployment)
|
||||
- API endpoints
|
||||
- Configuration options
|
||||
- Development setup
|
||||
|
||||
### What gets created:
|
||||
- README.md (rewritten)
|
||||
- docs/ directory with structured docs
|
||||
- docs/templates/ for new features
|
||||
- docs/api/ for API documentation
|
||||
- docs/architecture/ for system design
|
||||
- docs/deployment/ for setup guides
|
||||
- docs/features/ for user guides
|
||||
|
||||
### What stays:
|
||||
- Testing strategy (moved to docs/testing.md)
|
||||
- OpenSpec changes (archived as-is)
|
||||
@@ -0,0 +1,178 @@
|
||||
# Documentation Overhaul Specification
|
||||
|
||||
## Requirements
|
||||
|
||||
### Functional Requirements
|
||||
|
||||
1. **README Rewrite**: Comprehensive project overview with features, quick start, and links
|
||||
2. **Feature Documentation**: Every feature has a user guide in docs/features/
|
||||
3. **API Documentation**: All endpoints documented with examples
|
||||
4. **Architecture Docs**: Backend, frontend, and deployment architecture explained
|
||||
5. **Deployment Guide**: Step-by-step Docker/Traefik/Authentik setup
|
||||
6. **Development Guide**: Setup, testing, contributing guidelines
|
||||
7. **Templates**: Reusable templates for future documentation
|
||||
8. **Auto-Documentation**: Process ensuring new features get documented
|
||||
|
||||
### Non-Functional Requirements
|
||||
|
||||
1. **Discoverability**: Users can find docs easily from README
|
||||
2. **Completeness**: All current features documented
|
||||
3. **Accuracy**: Docs match current implementation
|
||||
4. **Maintainability**: Templates and processes keep docs up-to-date
|
||||
5. **Accessibility**: Markdown format, clear structure
|
||||
|
||||
## Documentation Inventory
|
||||
|
||||
### Current Features to Document
|
||||
|
||||
1. **Project Management**
|
||||
- Create/edit/delete projects
|
||||
- Project list view
|
||||
- Project workspace (default view)
|
||||
|
||||
2. **Git Repositories**
|
||||
- Create repositories (bare init, mirror clone)
|
||||
- Smart URL parsing
|
||||
- Repository list
|
||||
- Repository deletion
|
||||
|
||||
3. **Repository Workspace**
|
||||
- File browser (tree view)
|
||||
- File viewer (syntax highlighting)
|
||||
- Branch switching
|
||||
- Repository switching
|
||||
- Quick file editing
|
||||
|
||||
4. **Git History**
|
||||
- Commit history visualization
|
||||
- Branch graph
|
||||
- Commit details (diff, stats)
|
||||
- Branch filtering
|
||||
|
||||
5. **Authentication**
|
||||
- Authentik OAuth2 flow
|
||||
- Session-based auth
|
||||
- User profile
|
||||
- Logout
|
||||
|
||||
6. **User Settings**
|
||||
- Theme selection
|
||||
- Git identity
|
||||
- Default editor
|
||||
|
||||
7. **Tool Types**
|
||||
- Built-in types (code-server, jupyter)
|
||||
- Custom type creation
|
||||
- Compose template validation
|
||||
|
||||
8. **SSH Keys**
|
||||
- Generate key pairs
|
||||
- List/delete keys
|
||||
- Copy public key
|
||||
|
||||
## API Endpoints to Document
|
||||
|
||||
### Auth
|
||||
- GET /auth/login
|
||||
- GET /auth/callback
|
||||
- GET /auth/me
|
||||
- POST /auth/logout
|
||||
|
||||
### Projects
|
||||
- GET /projects
|
||||
- POST /projects
|
||||
- GET /projects/{id}
|
||||
- PUT /projects/{id}
|
||||
- DELETE /projects/{id}
|
||||
|
||||
### Repositories
|
||||
- GET /projects/{id}/repositories
|
||||
- POST /projects/{id}/repositories
|
||||
- DELETE /projects/{id}/repositories/{id}
|
||||
- GET /projects/{id}/repositories/{id}/files
|
||||
- GET /projects/{id}/repositories/{id}/files/content
|
||||
- POST /projects/{id}/repositories/{id}/files/content
|
||||
- GET /projects/{id}/repositories/{id}/branches
|
||||
- GET /projects/{id}/repositories/{id}/history
|
||||
- GET /projects/{id}/repositories/{id}/commits/{hash}
|
||||
|
||||
### Users
|
||||
- GET /users/me
|
||||
- PUT /users/me
|
||||
- POST /users/me/avatar
|
||||
- GET /users/me/config
|
||||
- PATCH /users/me/config
|
||||
|
||||
### Tool Types
|
||||
- GET /tool-types
|
||||
- POST /tool-types
|
||||
- GET /tool-types/{id}
|
||||
- PUT /tool-types/{id}
|
||||
- DELETE /tool-types/{id}
|
||||
|
||||
### SSH Keys
|
||||
- GET /ssh-keys
|
||||
- POST /ssh-keys
|
||||
- DELETE /ssh-keys/{id}
|
||||
|
||||
## Documentation Templates
|
||||
|
||||
### Feature Doc Template
|
||||
```markdown
|
||||
# [Feature Name]
|
||||
|
||||
## Overview
|
||||
[1-2 sentence description]
|
||||
|
||||
## How to Use
|
||||
[Step-by-step guide]
|
||||
|
||||
## Screenshots
|
||||
[If applicable]
|
||||
|
||||
## API Reference
|
||||
[Links to API docs]
|
||||
|
||||
## Configuration
|
||||
[Relevant env vars/settings]
|
||||
|
||||
## Related
|
||||
[Links to related features]
|
||||
```
|
||||
|
||||
### API Doc Template
|
||||
```markdown
|
||||
## [METHOD] [PATH]
|
||||
|
||||
**Auth:** [Required/Optional]
|
||||
|
||||
**Description:** [What it does]
|
||||
|
||||
### Request
|
||||
[Params/body schema]
|
||||
|
||||
### Response
|
||||
[Success/error schemas]
|
||||
|
||||
### Example
|
||||
[Code example]
|
||||
```
|
||||
|
||||
## Implementation Checklist
|
||||
|
||||
For every new feature:
|
||||
- [ ] Create feature doc in docs/features/
|
||||
- [ ] Document API endpoints in docs/api/
|
||||
- [ ] Update README.md features list
|
||||
- [ ] Update architecture docs if needed
|
||||
- [ ] Add to CHANGELOG.md
|
||||
|
||||
## Success Criteria
|
||||
|
||||
1. README provides clear project overview
|
||||
2. All 8 feature areas have user guides
|
||||
3. All API endpoints have documentation
|
||||
4. New developer can set up project in < 15 minutes
|
||||
5. Deployment guide enables setup without asking questions
|
||||
6. Templates exist for future documentation
|
||||
7. CONTRIBUTING.md explains documentation requirements
|
||||
@@ -0,0 +1,202 @@
|
||||
# Documentation Overhaul - Tasks
|
||||
|
||||
## Phase 1: README Rewrite
|
||||
|
||||
- [ ] **Task 1.1**: Rewrite README.md
|
||||
- Add project overview and description
|
||||
- List all features with brief descriptions
|
||||
- Add quick start section
|
||||
- Add tech stack section
|
||||
- Add links to docs/ directory
|
||||
- Keep testing strategy (or move to docs/testing.md)
|
||||
|
||||
- [ ] **Task 1.2**: Create docs/README.md
|
||||
- Documentation index
|
||||
- Link to all doc sections
|
||||
- Quick navigation
|
||||
|
||||
## Phase 2: Create Documentation Structure
|
||||
|
||||
- [ ] **Task 2.1**: Create docs/ directory structure
|
||||
- mkdir docs/architecture
|
||||
- mkdir docs/features
|
||||
- mkdir docs/api
|
||||
- mkdir docs/deployment
|
||||
- mkdir docs/development
|
||||
- mkdir docs/templates
|
||||
|
||||
- [ ] **Task 2.2**: Create documentation templates
|
||||
- docs/templates/feature-doc.md
|
||||
- docs/templates/api-endpoint.md
|
||||
- docs/templates/architecture.md
|
||||
|
||||
## Phase 3: Feature Documentation
|
||||
|
||||
- [ ] **Task 3.1**: Document Project Management
|
||||
- docs/features/projects.md
|
||||
- Creating/editing/deleting projects
|
||||
- Project list view
|
||||
- Project workspace
|
||||
|
||||
- [ ] **Task 3.2**: Document Git Repositories
|
||||
- docs/features/repositories.md
|
||||
- Creating repos (bare init, mirror clone)
|
||||
- Smart URL parsing
|
||||
- Repository management
|
||||
|
||||
- [ ] **Task 3.3**: Document Repository Workspace
|
||||
- docs/features/workspace.md
|
||||
- File browser
|
||||
- File viewer
|
||||
- Branch switching
|
||||
- Quick editing
|
||||
|
||||
- [ ] **Task 3.4**: Document Git History
|
||||
- docs/features/git-history.md
|
||||
- Commit history view
|
||||
- Branch graph
|
||||
- Commit details
|
||||
|
||||
- [ ] **Task 3.5**: Document Authentication
|
||||
- docs/features/auth.md
|
||||
- Authentik OAuth2 flow
|
||||
- Session management
|
||||
- User profile
|
||||
|
||||
- [ ] **Task 3.6**: Document User Settings
|
||||
- docs/features/settings.md
|
||||
- Theme selection
|
||||
- Git identity
|
||||
- Preferences
|
||||
|
||||
- [ ] **Task 3.7**: Document Tool Types
|
||||
- docs/features/tool-types.md
|
||||
- Built-in types
|
||||
- Custom type creation
|
||||
- Compose templates
|
||||
|
||||
- [ ] **Task 3.8**: Document SSH Keys
|
||||
- docs/features/ssh-keys.md
|
||||
- Key generation
|
||||
- Management
|
||||
|
||||
## Phase 4: API Documentation
|
||||
|
||||
- [ ] **Task 4.1**: Document Auth API
|
||||
- docs/api/auth.md
|
||||
- All auth endpoints
|
||||
|
||||
- [ ] **Task 4.2**: Document Projects API
|
||||
- docs/api/projects.md
|
||||
- All project endpoints
|
||||
|
||||
- [ ] **Task 4.3**: Document Repositories API
|
||||
- docs/api/repositories.md
|
||||
- All repository endpoints
|
||||
- File operations
|
||||
- History endpoints
|
||||
|
||||
- [ ] **Task 4.4**: Document Users API
|
||||
- docs/api/users.md
|
||||
- User profile endpoints
|
||||
- Config endpoints
|
||||
|
||||
- [ ] **Task 4.5**: Document Tool Types API
|
||||
- docs/api/tool-types.md
|
||||
- CRUD endpoints
|
||||
|
||||
- [ ] **Task 4.6**: Document SSH Keys API
|
||||
- docs/api/ssh-keys.md
|
||||
- Key management endpoints
|
||||
|
||||
## Phase 5: Architecture Documentation
|
||||
|
||||
- [ ] **Task 5.1**: Create backend architecture doc
|
||||
- docs/architecture/backend.md
|
||||
- Tech stack
|
||||
- Directory structure
|
||||
- Data flow
|
||||
- Auth flow
|
||||
|
||||
- [ ] **Task 5.2**: Create frontend architecture doc
|
||||
- docs/architecture/frontend.md
|
||||
- Tech stack
|
||||
- Directory structure
|
||||
- State management
|
||||
- Routing
|
||||
|
||||
- [ ] **Task 5.3**: Create database schema doc
|
||||
- docs/architecture/database.md
|
||||
- Entity relationship diagram
|
||||
- Table descriptions
|
||||
- Migration strategy
|
||||
|
||||
- [ ] **Task 5.4**: Create deployment architecture doc
|
||||
- docs/architecture/deployment.md
|
||||
- Docker architecture
|
||||
- Traefik routing
|
||||
- Service diagram
|
||||
|
||||
## Phase 6: Deployment Guide
|
||||
|
||||
- [ ] **Task 6.1**: Create Docker setup guide
|
||||
- docs/deployment/docker.md
|
||||
- Local development setup
|
||||
- Docker compose configuration
|
||||
|
||||
- [ ] **Task 6.2**: Create Traefik guide
|
||||
- docs/deployment/traefik.md
|
||||
- Traefik configuration
|
||||
- Routing rules
|
||||
- TLS setup
|
||||
|
||||
- [ ] **Task 6.3**: Create Authentik guide
|
||||
- docs/deployment/authentik.md
|
||||
- Provider setup
|
||||
- Application configuration
|
||||
- OAuth2 settings
|
||||
|
||||
- [ ] **Task 6.4**: Create environment variables guide
|
||||
- docs/deployment/environment.md
|
||||
- All env vars explained
|
||||
- Required vs optional
|
||||
- Default values
|
||||
|
||||
## Phase 7: Development Guide
|
||||
|
||||
- [ ] **Task 7.1**: Create setup guide
|
||||
- docs/development/setup.md
|
||||
- Prerequisites
|
||||
- Installation steps
|
||||
- Running locally
|
||||
|
||||
- [ ] **Task 7.2**: Move testing strategy
|
||||
- Move from README.md to docs/development/testing.md
|
||||
- Update references
|
||||
|
||||
- [ ] **Task 7.3**: Create contributing guide
|
||||
- docs/development/contributing.md
|
||||
- Code style
|
||||
- PR process
|
||||
- Documentation requirements
|
||||
|
||||
- [ ] **Task 7.4**: Create quality gates doc
|
||||
- docs/development/quality-gates.md
|
||||
- Linting rules
|
||||
- Type checking
|
||||
- Testing requirements
|
||||
|
||||
## Phase 8: Finalization
|
||||
|
||||
- [ ] **Task 8.1**: Review all docs
|
||||
- Check for completeness
|
||||
- Check for accuracy
|
||||
- Fix broken links
|
||||
|
||||
- [ ] **Task 8.2**: Create CHANGELOG.md
|
||||
- List all features implemented
|
||||
- Link to OpenSpec changes
|
||||
|
||||
- [ ] **Task 8.3**: Commit all documentation
|
||||
- Single commit for docs
|
||||
- Conventional commit message
|
||||
@@ -0,0 +1,2 @@
|
||||
schema: spec-driven
|
||||
created: 2026-05-19
|
||||
@@ -0,0 +1,154 @@
|
||||
# Smart Git URL Parsing - Design
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
User pastes URL → Frontend validates → Backend validates → Clone repo
|
||||
↓ ↓
|
||||
Show suggestions Parse & suggest
|
||||
```
|
||||
|
||||
## URL Detection Logic
|
||||
|
||||
### Patterns to Detect
|
||||
|
||||
1. **GitHub/GitLab/Bitbucket browser URLs**
|
||||
- `https://github.com/owner/repo/tree/branch-name`
|
||||
- `https://github.com/owner/repo/blob/branch/path/to/file`
|
||||
- `https://github.com/owner/repo/pull/123`
|
||||
- `https://gitlab.com/owner/repo/-/tree/branch`
|
||||
- `https://bitbucket.org/owner/repo/src/branch/`
|
||||
|
||||
2. **URLs with query parameters**
|
||||
- `https://github.com/owner/repo?tab=readme-ov-file`
|
||||
- `https://github.com/owner/repo.git?branch=develop`
|
||||
|
||||
3. **Valid clone URLs (should pass through)**
|
||||
- `https://github.com/owner/repo.git`
|
||||
- `git@github.com:owner/repo.git`
|
||||
- `https://github.com/owner/repo` (without .git)
|
||||
|
||||
### URL Parsing Rules
|
||||
|
||||
```python
|
||||
def extract_base_repo_url(url: str) -> str | None:
|
||||
"""Extract base repository URL from a browser/git URL.
|
||||
|
||||
Examples:
|
||||
https://github.com/user/repo/tree/main → https://github.com/user/repo.git
|
||||
https://github.com/user/repo.git → https://github.com/user/repo.git
|
||||
git@github.com:user/repo.git → git@github.com:user/repo.git
|
||||
https://gitlab.com/user/repo/-/blob/main/README.md → https://gitlab.com/user/repo.git
|
||||
|
||||
Returns None if URL doesn't match known patterns.
|
||||
"""
|
||||
...
|
||||
```
|
||||
|
||||
**Algorithm:**
|
||||
1. Remove query parameters
|
||||
2. Detect host (github.com, gitlab.com, bitbucket.org, etc.)
|
||||
3. For GitHub: Remove `/tree/*`, `/blob/*`, `/pull/*`, `/issues/*` paths
|
||||
4. For GitLab: Remove `/-/tree/*`, `/-/blob/*` paths
|
||||
5. For Bitbucket: Remove `/src/*` paths
|
||||
6. Ensure `.git` suffix
|
||||
7. Return cleaned URL or None
|
||||
|
||||
## API Changes
|
||||
|
||||
### POST /repositories (enhanced)
|
||||
|
||||
**Request Body:**
|
||||
```json
|
||||
{
|
||||
"project_id": "uuid",
|
||||
"name": "my-repo",
|
||||
"remote_url": "https://github.com/user/repo/tree/main",
|
||||
"is_mirror": false
|
||||
}
|
||||
```
|
||||
|
||||
**New Response for Non-Repo URLs (422):**
|
||||
```json
|
||||
{
|
||||
"detail": "URL appears to be a browser URL, not a git clone URL",
|
||||
"suggested_url": "https://github.com/user/repo.git",
|
||||
"original_url": "https://github.com/user/repo/tree/main",
|
||||
"needs_confirmation": true
|
||||
}
|
||||
```
|
||||
|
||||
### New Endpoint: POST /repositories/parse-url
|
||||
|
||||
**Request:**
|
||||
```json
|
||||
{
|
||||
"url": "https://github.com/user/repo/tree/main"
|
||||
}
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"original_url": "https://github.com/user/repo/tree/main",
|
||||
"base_url": "https://github.com/user/repo.git",
|
||||
"is_valid_repo_url": false,
|
||||
"needs_parsing": true,
|
||||
"message": "This looks like a browser URL. Did you mean to clone https://github.com/user/repo.git?"
|
||||
}
|
||||
```
|
||||
|
||||
## Frontend Flow
|
||||
|
||||
### Repository Creation Dialog (Enhanced)
|
||||
|
||||
1. **User pastes URL**
|
||||
2. **Frontend calls `/repositories/parse-url`** (debounced)
|
||||
3. **If URL needs parsing:**
|
||||
- Show yellow warning indicator
|
||||
- Display: "This looks like a browser URL"
|
||||
- Show suggested URL with "Use this instead" button
|
||||
- Allow user to proceed with original URL anyway
|
||||
4. **If URL is valid:**
|
||||
- Show green checkmark
|
||||
- Proceed normally
|
||||
5. **User clicks "Create"**
|
||||
6. **If backend returns 422 with suggestion:**
|
||||
- Show confirmation dialog with suggested URL
|
||||
- Options: "Use suggested URL", "Use original", "Cancel"
|
||||
|
||||
### UI Components
|
||||
|
||||
**URLInput Component:**
|
||||
- Input field with validation status icon
|
||||
- Shows inline suggestions when URL is detected as browser URL
|
||||
- Green/yellow/red border based on validation
|
||||
|
||||
**URLCorrectionDialog Component:**
|
||||
- Modal dialog for confirming URL correction
|
||||
- Shows before/after comparison
|
||||
- Clear action buttons
|
||||
|
||||
## Implementation Order
|
||||
|
||||
1. **Backend utilities** - URL parsing functions with tests
|
||||
2. **Backend endpoint** - `/repositories/parse-url`
|
||||
3. **Backend validation** - Enhanced POST /repositories with suggestion response
|
||||
4. **Frontend URL input** - Enhanced input with validation feedback
|
||||
5. **Frontend dialog** - Confirmation dialog for URL corrections
|
||||
6. **Integration** - Wire up parse-url endpoint to frontend
|
||||
7. **Tests** - Unit tests for URL parsing, integration tests for flow
|
||||
|
||||
## Error Handling
|
||||
|
||||
### Invalid URLs
|
||||
- Completely malformed URLs: Return 400 with clear message
|
||||
- Unsupported hosts: Return 400 with "Unsupported git host"
|
||||
- Private repos (auth needed): Return 401/403 with auth instructions
|
||||
- Non-existent repos: Return 404 (from git clone failure)
|
||||
|
||||
### Clone Failures
|
||||
- Network issues: Retry with exponential backoff
|
||||
- Auth required: Prompt for credentials
|
||||
- Large repos: Show progress indicator
|
||||
- Timeout: Increase timeout for large repos
|
||||
@@ -0,0 +1,43 @@
|
||||
# Smart Git URL Parsing for Repository Creation
|
||||
|
||||
## Problem
|
||||
|
||||
When users add a new repository, they often paste a full browser URL that includes branch names, file paths, or query parameters instead of a clean repository URL. This causes the clone operation to fail with unclear error messages.
|
||||
|
||||
**Examples of problematic URLs:**
|
||||
- `https://github.com/user/repo/tree/main` (includes branch path)
|
||||
- `https://github.com/user/repo/blob/main/README.md` (includes file path)
|
||||
- `https://github.com/user/repo?tab=readme-ov-file` (includes query params)
|
||||
- `https://github.com/user/repo/pull/123` (includes PR path)
|
||||
|
||||
**Current behavior:** The backend attempts to clone the exact URL, which fails with "fatal: repository not found" or similar errors.
|
||||
|
||||
**User confusion:** Users don't understand why the clone failed since the URL works in their browser.
|
||||
|
||||
## Solution
|
||||
|
||||
Implement smart URL parsing that:
|
||||
|
||||
1. **Detects non-repo URLs**: Recognizes when a URL contains paths like `/tree/`, `/blob/`, `/pull/`, or query parameters
|
||||
2. **Extracts base repo URL**: Strips away branch names, file paths, query parameters to get `https://host/owner/repo.git`
|
||||
3. **Suggests correction**: Shows the user the extracted base URL and asks for confirmation
|
||||
4. **Improves clone handling**: Handles edge cases and provides clear error messages
|
||||
|
||||
## Benefits
|
||||
|
||||
- **Better UX**: Users get helpful suggestions instead of cryptic errors
|
||||
- **Fewer support issues**: Self-service correction reduces confusion
|
||||
- **More robust**: Handles common copy-paste mistakes automatically
|
||||
- **Educational**: Teaches users what a proper git URL looks like
|
||||
|
||||
## Scope
|
||||
|
||||
### Backend
|
||||
- URL parsing utilities to detect and extract base repo URLs
|
||||
- Enhanced validation in repository creation endpoint
|
||||
- Clear error messages for unsupported URLs
|
||||
|
||||
### Frontend
|
||||
- UI dialog to show URL correction suggestions
|
||||
- Option to accept or edit the suggested URL
|
||||
- Visual indicator for URL validation status
|
||||
@@ -0,0 +1,206 @@
|
||||
# Smart Git URL Parsing Specification
|
||||
|
||||
## Requirements
|
||||
|
||||
### Functional Requirements
|
||||
|
||||
1. **URL Detection**: Detect when a provided URL is a browser URL rather than a git clone URL
|
||||
2. **URL Extraction**: Extract the base repository URL from browser URLs
|
||||
3. **User Confirmation**: Show extracted URL to user and ask for confirmation
|
||||
4. **Flexible Input**: Allow users to proceed with original URL if they prefer
|
||||
5. **Multiple Hosts**: Support GitHub, GitLab, Bitbucket, and generic git hosts
|
||||
|
||||
### Non-Functional Requirements
|
||||
|
||||
1. **Performance**: URL parsing should be instant (< 100ms)
|
||||
2. **Accuracy**: Should correctly identify 95%+ of browser URLs
|
||||
3. **User Experience**: Clear, helpful messages without technical jargon
|
||||
4. **Backward Compatibility**: Existing valid git URLs should continue to work
|
||||
|
||||
## API Specification
|
||||
|
||||
### POST /git-repositories/parse-url
|
||||
Parse a URL and determine if it's a valid clone URL or needs correction.
|
||||
|
||||
**Request Body:**
|
||||
```json
|
||||
{
|
||||
"url": "https://github.com/user/repo/tree/main"
|
||||
}
|
||||
```
|
||||
|
||||
**Response 200:**
|
||||
```json
|
||||
{
|
||||
"original_url": "https://github.com/user/repo/tree/main",
|
||||
"base_url": "https://github.com/user/repo.git",
|
||||
"is_valid_clone_url": false,
|
||||
"needs_parsing": true,
|
||||
"host": "github.com",
|
||||
"message": "This URL contains a branch path. The repository URL is: https://github.com/user/repo.git"
|
||||
}
|
||||
```
|
||||
|
||||
**Response 200 (already valid):**
|
||||
```json
|
||||
{
|
||||
"original_url": "https://github.com/user/repo.git",
|
||||
"base_url": "https://github.com/user/repo.git",
|
||||
"is_valid_clone_url": true,
|
||||
"needs_parsing": false,
|
||||
"host": "github.com",
|
||||
"message": "Valid git repository URL"
|
||||
}
|
||||
```
|
||||
|
||||
### Enhanced POST /projects/{project_id}/repositories
|
||||
Enhanced to return suggestions when URL needs parsing.
|
||||
|
||||
**New 422 Response:**
|
||||
```json
|
||||
{
|
||||
"detail": "The provided URL appears to be a browser URL, not a git clone URL",
|
||||
"suggested_url": "https://github.com/user/repo.git",
|
||||
"original_url": "https://github.com/user/repo/tree/main",
|
||||
"error_code": "URL_NEEDS_PARSING"
|
||||
}
|
||||
```
|
||||
|
||||
**Request Body (with force flag):**
|
||||
```json
|
||||
{
|
||||
"name": "my-repo",
|
||||
"remote_url": "https://github.com/user/repo/tree/main",
|
||||
"is_mirror": false,
|
||||
"force_original_url": true
|
||||
}
|
||||
```
|
||||
|
||||
## Data Model
|
||||
|
||||
### URLParseResult
|
||||
```python
|
||||
class URLParseResult:
|
||||
original_url: str
|
||||
base_url: str | None
|
||||
is_valid_clone_url: bool
|
||||
needs_parsing: bool
|
||||
host: str | None
|
||||
message: str
|
||||
error_code: str | None
|
||||
```
|
||||
|
||||
## URL Parsing Rules
|
||||
|
||||
### Supported Hosts
|
||||
- github.com
|
||||
- gitlab.com
|
||||
- bitbucket.org
|
||||
- Any custom domain with git hosting
|
||||
|
||||
### GitHub URL Patterns
|
||||
```
|
||||
https://github.com/{owner}/{repo} → valid
|
||||
https://github.com/{owner}/{repo}.git → valid
|
||||
https://github.com/{owner}/{repo}/tree/{branch} → extract base
|
||||
https://github.com/{owner}/{repo}/blob/{branch}/{path} → extract base
|
||||
https://github.com/{owner}/{repo}/pull/{number} → extract base
|
||||
https://github.com/{owner}/{repo}/issues/{number} → extract base
|
||||
https://github.com/{owner}/{repo}/actions → extract base
|
||||
```
|
||||
|
||||
### GitLab URL Patterns
|
||||
```
|
||||
https://gitlab.com/{owner}/{repo} → valid
|
||||
https://gitlab.com/{owner}/{repo}.git → valid
|
||||
https://gitlab.com/{owner}/{repo}/-/tree/{branch} → extract base
|
||||
https://gitlab.com/{owner}/{repo}/-/blob/{branch}/{path} → extract base
|
||||
https://gitlab.com/{owner}/{repo}/-/merge_requests/{number} → extract base
|
||||
```
|
||||
|
||||
### Bitbucket URL Patterns
|
||||
```
|
||||
https://bitbucket.org/{owner}/{repo} → valid
|
||||
https://bitbucket.org/{owner}/{repo}.git → valid
|
||||
https://bitbucket.org/{owner}/{repo}/src/{branch} → extract base
|
||||
```
|
||||
|
||||
### Extraction Algorithm
|
||||
1. Parse URL components (scheme, netloc, path, query)
|
||||
2. Remove query parameters entirely
|
||||
3. Split path by `/`
|
||||
4. Remove trailing segments that indicate non-repo paths:
|
||||
- `tree/*`, `blob/*`, `pull/*`, `issues/*`, `actions`
|
||||
- `-/tree/*`, `-/blob/*`, `-/merge_requests/*`
|
||||
- `src/*`
|
||||
5. Reconstruct URL with remaining path
|
||||
6. Add `.git` suffix if missing (for HTTPS URLs)
|
||||
7. Return extracted URL
|
||||
|
||||
## Frontend Specification
|
||||
|
||||
### URL Input Component
|
||||
- Input field for repository URL
|
||||
- Real-time validation (debounced 300ms)
|
||||
- Visual indicators:
|
||||
- 🟢 Green border: Valid git URL
|
||||
- 🟡 Yellow border: Browser URL detected, suggestion shown
|
||||
- 🔴 Red border: Invalid/malformed URL
|
||||
- Inline suggestion banner below input:
|
||||
```
|
||||
⚠️ This looks like a browser URL
|
||||
Suggested: https://github.com/user/repo.git
|
||||
[Use Suggested] [Keep Original]
|
||||
```
|
||||
|
||||
### Confirmation Dialog
|
||||
Shown when backend returns 422 with suggestion:
|
||||
```
|
||||
┌─────────────────────────────────────┐
|
||||
│ URL Correction Suggestion │
|
||||
├─────────────────────────────────────┤
|
||||
│ │
|
||||
│ The URL you entered appears to be │
|
||||
│ a browser URL, not a git clone URL. │
|
||||
│ │
|
||||
│ Original: │
|
||||
│ https://github.com/user/repo/tree/main│
|
||||
│ │
|
||||
│ Suggested repository URL: │
|
||||
│ https://github.com/user/repo.git │
|
||||
│ │
|
||||
│ [Use Suggested URL] [Use Original] │
|
||||
│ [Cancel] │
|
||||
└─────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Error Codes
|
||||
|
||||
| Error Code | Description | User Message |
|
||||
|------------|-------------|--------------|
|
||||
| URL_NEEDS_PARSING | Browser URL detected | "This looks like a browser URL. Did you mean: {suggested_url}?" |
|
||||
| INVALID_URL | Malformed URL | "Please enter a valid URL" |
|
||||
| UNSUPPORTED_HOST | Unknown git host | "This git host is not supported" |
|
||||
| CLONE_FAILED | Git clone failed | "Failed to clone repository: {error}" |
|
||||
| AUTH_REQUIRED | Private repo, need auth | "This repository requires authentication" |
|
||||
|
||||
## Testing Strategy
|
||||
|
||||
### Unit Tests (URL Parsing)
|
||||
- Test all GitHub URL patterns
|
||||
- Test all GitLab URL patterns
|
||||
- Test all Bitbucket URL patterns
|
||||
- Test valid URLs pass through unchanged
|
||||
- Test edge cases (subgroups, nested paths, etc.)
|
||||
|
||||
### Integration Tests
|
||||
- Test parse-url endpoint with various URLs
|
||||
- Test repository creation with browser URL (should suggest correction)
|
||||
- Test repository creation with force flag
|
||||
- Test clone operation with corrected URL
|
||||
|
||||
### Frontend Tests
|
||||
- Test URL input validation states
|
||||
- Test suggestion banner display
|
||||
- Test confirmation dialog flow
|
||||
- Test acceptance/rejection of suggestions
|
||||
@@ -0,0 +1,61 @@
|
||||
# Smart Git URL Parsing - Tasks
|
||||
|
||||
## Phase 1: Backend URL Parsing
|
||||
|
||||
- [ ] **Task 1.1**: Create URL parsing utilities
|
||||
- Create `src/utils/git_url_parser.py`
|
||||
- Implement `extract_base_repo_url()` function
|
||||
- Support GitHub, GitLab, Bitbucket patterns
|
||||
- Handle query parameters, branch paths, file paths
|
||||
- Add comprehensive unit tests
|
||||
|
||||
- [ ] **Task 1.2**: Create URL validation endpoint
|
||||
- Add `POST /git-repositories/parse-url` endpoint
|
||||
- Returns URLParseResult with original, base, validation status
|
||||
- Add tests for endpoint
|
||||
|
||||
- [ ] **Task 1.3**: Enhance repository creation endpoint
|
||||
- Update `POST /projects/{project_id}/repositories`
|
||||
- Detect browser URLs and return 422 with suggestion
|
||||
- Add `force_original_url` flag to bypass suggestion
|
||||
- Update response models
|
||||
|
||||
## Phase 2: Frontend Implementation
|
||||
|
||||
- [ ] **Task 2.1**: Create API client for URL parsing
|
||||
- Add `parseGitUrl()` function to `api/git_repositories.ts`
|
||||
- Add types for URLParseResult
|
||||
|
||||
- [ ] **Task 2.2**: Enhance repository creation form
|
||||
- Add real-time URL validation to input field
|
||||
- Show visual indicators (green/yellow/red)
|
||||
- Display inline suggestion banner
|
||||
- Add "Use Suggested" / "Keep Original" buttons
|
||||
|
||||
- [ ] **Task 2.3**: Create confirmation dialog
|
||||
- Create `URLCorrectionDialog` component
|
||||
- Shows original vs suggested URL comparison
|
||||
- Handles accept/reject/cancel actions
|
||||
- Integrate with repository creation flow
|
||||
|
||||
## Phase 3: Integration & Testing
|
||||
|
||||
- [ ] **Task 3.1**: Wire up frontend to backend
|
||||
- Call parse-url endpoint on URL input change (debounced)
|
||||
- Handle 422 responses from repository creation
|
||||
- Show confirmation dialog when needed
|
||||
|
||||
- [ ] **Task 3.2**: Add error handling
|
||||
- Handle network errors during URL validation
|
||||
- Show clear error messages for unsupported URLs
|
||||
- Handle clone failures gracefully
|
||||
|
||||
- [ ] **Task 3.3**: Run quality gates
|
||||
- Backend: ruff, mypy, pytest
|
||||
- Frontend: typecheck, lint, build
|
||||
|
||||
- [ ] **Task 3.4**: Manual testing
|
||||
- Test with GitHub URLs (tree, blob, pull)
|
||||
- Test with GitLab URLs (-/tree, -/blob)
|
||||
- Test with valid git URLs (should pass through)
|
||||
- Test force_original_url flag
|
||||
Reference in New Issue
Block a user