chore: archive project-management and scaffold user-profile change

2026-05-17 20:26:30 +00:00
parent 71d9fe6406
commit 56f440db1b
14 changed files with 96 additions and 34 deletions
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-05-17
@@ -0,0 +1,3 @@
+# project-management
+
+Implement project CRUD, listing, and ownership workflows across API and frontend
@@ -0,0 +1,57 @@
+## Context
+
+Project management is defined in specs but not yet fully implemented across backend and frontend. The codebase now includes auth-oauth and frontend-foundation, so this change should connect authenticated users to project CRUD workflows and enforce ownership/security rules consistently.
+
+## Goals / Non-Goals
+
+**Goals:**
+- Provide authenticated CRUD endpoints for projects with owner-only updates/deletes.
+- Expose project listing payloads that include associated repositories and default SSH key metadata.
+- Add frontend project pages for listing, creating, editing, and deleting projects.
+- Support setting/changing a default SSH key per project with ownership validation.
+- Verify cascade behavior and authorization through tests.
+
+**Non-Goals:**
+- Advanced collaboration features (shared project ownership, invites, roles).
+- Bulk project operations.
+- Full analytics/activity stream implementation beyond simple listing metadata.
+
+## Decisions
+
+1. **Keep project logic in dedicated service layer with thin route handlers**
+   - Rationale: consistent with auth service separation and easier unit testing.
+   - Alternative: embed logic directly in route handlers. Rejected for maintainability.
+
+2. **Use authenticated user identity from internal JWT for ownership checks**
+   - Rationale: single trust path and no client-provided owner fields.
+   - Alternative: allow owner IDs in request body. Rejected for security risk.
+
+3. **Return normalized project DTOs with nested repository summaries**
+   - Rationale: reduces frontend round-trips and supports immediate dashboard/project page rendering.
+   - Alternative: fetch repositories separately per project. Rejected due to extra request overhead.
+
+4. **Implement optimistic-friendly frontend forms with explicit server error display**
+   - Rationale: better UX while preserving clear failure feedback.
+   - Alternative: full page reload after each action. Rejected due to poor interaction quality.
+
+## Risks / Trade-offs
+
+- **[Ownership bypass bugs]** -> enforce auth checks at service boundary and test unauthorized scenarios.
+- **[Cascade deletion surprises]** -> add integration tests that assert repository/association cleanup behavior.
+- **[Stale frontend lists after mutation]** -> centralize refresh calls after create/update/delete.
+- **[Default SSH key mismatch]** -> validate key belongs to user/project context before assignment.
+
+## Migration Plan
+
+1. Add/adjust backend project API routes and services.
+2. Add backend tests for CRUD, ownership, default-key, and cascade behavior.
+3. Implement frontend project pages and API integration.
+4. Add frontend tests for protected interactions and mutation flows.
+5. Run quality gates for backend and frontend.
+
+Rollback:
+- Revert project API and frontend pages; keep existing schema unchanged unless explicit migration is added.
+
+## Open Questions
+
+- Whether project descriptions should support markdown formatting (deferred; plain text for now).
@@ -0,0 +1,27 @@
+## Why
+
+The platform now has authentication, data models, and a frontend foundation, but users still cannot manage projects end-to-end. Implementing project management is the next core workflow needed to organize repositories and execute real work.
+
+## What Changes
+
+- Implement authenticated project CRUD APIs with ownership enforcement.
+- Add project listing views and project create/update/delete flows in the frontend.
+- Add default SSH key selection per project and validate key ownership.
+- Enforce cascading behavior for project deletion with related repositories and SSH key links.
+- Add backend and frontend tests that cover auth, ownership, and error cases.
+
+## Capabilities
+
+### New Capabilities
+- `project-management-ui`: Frontend project list/detail/form flows integrated with authenticated API.
+
+### Modified Capabilities
+- `project-management`: Expand requirement details for ownership checks, API contracts, and frontend-integrated project workflows.
+- `git-repo`: Clarify cascade/delete behavior when repositories are removed through project deletion.
+- `ssh-keys`: Clarify constraints for default project SSH key assignment.
+
+## Impact
+
+- Backend changes in `apps/api/src` (routes/services/models validation) and API tests.
+- Frontend changes in `apps/web/src` (project pages, API client calls, forms, state handling).
+- Potential migration adjustments if additional indexes/constraints are required for ownership/default-key integrity.
@@ -0,0 +1,10 @@
+## MODIFIED Requirements
+
+### Requirement: Repository Deletion
+The system SHALL remove repository records when their owning project is deleted through authorized project deletion flow.
+
+#### Scenario: Cascade repository cleanup
+- GIVEN a project with associated repositories
+- WHEN the project owner deletes the project
+- THEN repository records for that project are removed
+- AND repository listing no longer includes removed records
@@ -0,0 +1,69 @@
+## MODIFIED Requirements
+
+### Requirement: Project Creation
+The system SHALL allow authenticated users to create new projects and SHALL assign the creator as project owner.
+
+#### Scenario: Create project
+- GIVEN an authenticated user
+- WHEN they create a project with name and description
+- THEN a project record is created
+- AND the user is set as owner
+
+#### Scenario: Reject unauthenticated creation
+- GIVEN a request without a valid authenticated session
+- WHEN it attempts to create a project
+- THEN the system responds with unauthorized status
+
+### Requirement: Project Listing
+The system SHALL list projects owned by the authenticated user, including related repositories and default SSH key metadata.
+
+#### Scenario: List projects
+- GIVEN an authenticated user
+- WHEN they view the projects page
+- THEN all their projects are listed with associated repositories
+
+#### Scenario: Ownership-scoped listing
+- GIVEN multiple users with separate projects
+- WHEN one user requests their project list
+- THEN only that user's projects are returned
+
+### Requirement: Project Updates
+The system SHALL support updating project details for project owners only.
+
+#### Scenario: Update project
+- GIVEN a project owner
+- WHEN they update the name or description
+- THEN the changes are persisted
+
+#### Scenario: Non-owner update denied
+- GIVEN a user who is not the project owner
+- WHEN they attempt to update project details
+- THEN the system responds with forbidden status
+
+### Requirement: Project Deletion
+The system SHALL support cascading project deletion for project owners.
+
+#### Scenario: Delete project
+- GIVEN a project owner
+- WHEN they delete a project
+- THEN all associated repositories are deleted
+- AND all associated SSH keys are removed
+- AND the project record is deleted
+
+#### Scenario: Non-owner deletion denied
+- GIVEN a user who is not the project owner
+- WHEN they attempt to delete the project
+- THEN the system responds with forbidden status
+
+### Requirement: Default SSH Key
+The system SHALL allow project owners to set a default SSH key per project and SHALL validate ownership for selected keys.
+
+#### Scenario: Set default key
+- GIVEN a project with SSH keys
+- WHEN the owner selects a default key
+- THEN it's used for git operations in that project
+
+#### Scenario: Reject foreign key assignment
+- GIVEN a project owner
+- WHEN they try setting a default SSH key that does not belong to their allowed scope
+- THEN the system rejects the request with validation error
@@ -0,0 +1,14 @@
+## MODIFIED Requirements
+
+### Requirement: Key Association
+The system SHALL only allow project default-key assignment using keys valid for the authenticated owner's project scope.
+
+#### Scenario: Valid default key assignment
+- GIVEN a project owner and an eligible SSH key
+- WHEN the owner sets the key as default for the project
+- THEN the project stores that key reference
+
+#### Scenario: Invalid default key assignment
+- GIVEN a project owner
+- WHEN the owner attempts to set an ineligible SSH key as project default
+- THEN the system responds with validation failure
@@ -0,0 +1,25 @@
+## 1. Backend project API and ownership enforcement
+
+- [x] 1.1 Add/extend project API routes for create, list, update, delete, and default-ssh-key set operations.
+- [x] 1.2 Implement project service layer ownership checks using authenticated user identity.
+- [x] 1.3 Implement/verify cascade semantics for project deletion with repository cleanup behavior.
+- [x] 1.4 Add backend tests for authenticated CRUD, ownership-denied scenarios, and default-key validation.
+
+## 2. Frontend project management flows
+
+- [x] 2.1 Add project API client methods for list/create/update/delete/default-key operations.
+- [x] 2.2 Implement projects page with list and empty/loading/error states.
+- [x] 2.3 Implement project create/edit form interactions and validation messaging.
+- [x] 2.4 Implement delete flow and UI refresh behavior after mutations.
+- [x] 2.5 Add frontend tests for protected project routes and mutation flows.
+
+## 3. Verification and OpenSpec tracking
+
+- [x] 3.1 Run backend checks (`pytest`, `ruff check src tests`, `mypy src`) and fix findings.
+- [x] 3.2 Run frontend checks (`npm test`, `npm run typecheck`, `npm run lint`, `npm run build`) and fix findings.
+- [x] 3.3 Update this tasks file with completed checkboxes and document blockers/follow-ups.
+
+## Blockers / Follow-ups
+
+- No blocking issues remain for this change.
+- Frontend test run shows non-blocking Vite deprecation warnings related to esbuild options from `vite:react-babel`; behavior is unaffected and can be handled in a later tooling cleanup change.