headquarter/openspec/changes/archive/2026-05-19-repo-workspace/tasks.md

Repository Workspace - Tasks

Phase 1: Backend File APIs

• Task 1.1: Create git file utilities

  • Create src/utils/git_files.py
  • list_tree() - list files in directory using git ls-tree
  • get_file_content() - get file content using git show
  • list_branches() - list branches using git branch
  • commit_file() - commit file changes using git add + git commit
  • Add tests

• Task 1.2: Add file listing endpoint

  • Add GET /projects/{id}/repositories/{id}/files to git_repositories.py
  • Query params: branch, path
  • Returns FileTreeEntry list
  • Handle errors (missing branch, missing path)

• Task 1.3: Add file content endpoint

  • Add GET /projects/{id}/repositories/{id}/files/content to git_repositories.py
  • Query params: branch, path
  • Returns FileContent with language detection
  • Detect binary files

• Task 1.4: Add branches endpoint

  • Add GET /projects/{id}/repositories/{id}/branches to git_repositories.py
  • Returns branch list with default branch marked

• Task 1.5: Add file update endpoint

  • Add POST /projects/{id}/repositories/{id}/files/content to git_repositories.py
  • Body: path, branch, content, commit_message, author info
  • Create commit with changes
  • Return commit hash

Phase 2: Project List Navigation

• Task 2.1: Make project list clickable

  • Update ProjectsPage to link to workspace
  • Route: /projects/:projectId
  • Remove placeholder, use workspace

• Task 2.2: Update app navigation

  • Ensure project routes are correct
  • Add breadcrumb or back button

Phase 3: Workspace Page Shell

• Task 3.1: Create RepoWorkspace page

  • Create pages/repo-workspace.tsx
  • Layout: Sidebar + Main Content
  • Fetch project repos on load
  • Select first repo by default

• Task 3.2: Create RepoSelector component

  • Dropdown to switch between project repos
  • Show active repo name
  • Update URL when switching

• Task 3.3: Create BranchSelector component

  • Dropdown to switch branches
  • Show active branch
  • Mark default branch
  • Fetch branches from API

Phase 4: File Browser

• Task 4.1: Create FileTree component

  • Recursive tree view
  • Expandable/collapsible folders
  • File icons by extension
  • Click to open file
  • Active file highlight
  • Fetch tree data from API

• Task 4.2: Add file tree loading

  • Load root on repo/branch change
  • Lazy load subdirectories
  • Show loading state

Phase 5: File Viewer

• Task 5.1: Create FileViewer component

  • Display file content
  • Line numbers
  • Syntax highlighting (prismjs or similar)
  • Breadcrumb navigation
  • Show file metadata (size, last commit)

• Task 5.2: Add edit mode

  • Toggle between view/edit
  • Textarea for editing
  • Save button (calls update API)
  • Cancel button
  • Commit message input

Phase 6: Integration & Polish

• Task 6.1: Sync URL state

  • Repo ID in URL
  • Branch in URL
  • Path in URL
  • Parse on load, update on change

• Task 6.2: Add error handling

  • Repo not found
  • Branch not found
  • File not found
  • Binary files
  • Network errors

• Task 6.3: Add CSS styles

  • Workspace layout
  • File tree styles
  • File viewer styles
  • Sidebar styles
  • Responsive design

• Task 6.4: Run quality gates

  • Backend: ruff, mypy, pytest
  • Frontend: typecheck, lint, build

Phase 7: Route Updates

• Task 7.1: Update router

  • /projects/:projectId → RepoWorkspace (default)
  • Move old project details to /projects/:projectId/details or remove
  • Keep /projects/:projectId/repositories for repo management

• Task 7.2: Update navigation

  • Project list links to workspace
  • Add "Manage Repositories" link in workspace