9.4 KiB
9.4 KiB
spec, created, status
| spec | created | status |
|---|---|---|
| docs/specs/create-local-repository/spec.md | 2026-07-21 | completed |
Implementation Plan: Create a Local Repository During Task Creation
Overview
Add an explicit backend operation that owns directory creation, commitless Git initialization, and workspace repository persistence. Then add a selector action that opens a shared directory-browser form, merges the returned repository into workspace state, selects it in the originating task row, and moves the first task to a compatible direct local executor. Desktop and mobile use the same mutation/state logic with purpose-built Dialog and Drawer shells.
Backend
Initialization service
- Add
InitializeLocalRepositoryRequestandService.InitializeLocalRepositoryinapps/backend/internal/task/service/service_requests.goand a focused newapps/backend/internal/task/service/local_repository_initialization.go. - Validate that
Nameis a single non-empty host path segment andParentPathis an existing, writable absolute directory. Canonicalize the parent before joining the target, atomically create the absent target, and never modify an existing path. - Run
git init --initial-branch=mainwithout creating files, configuring an author, or committing. - Register the canonical target through the existing
CreateRepositorypath withsource_type=localanddefault_branch=main, preserving validation andrepository.createdpublication. - On a partial failure, leave no repository row and remove only the target created by this request when cleanup is safe; log cleanup failure without masking the primary error.
HTTP contract
- Register
POST /api/v1/workspaces/:id/repositories/initialize-localinapps/backend/internal/task/handlers/repository_handlers.go. - Bind
{name,parent_path}, verify workspace ownership/existence before filesystem mutation, map validation to400, target existence to409, and return the existing repository DTO with201. - Add handler coverage in
apps/backend/internal/task/handlers/repository_handlers_test.go.
Frontend
API and shared directory browser
- Add
initializeLocalRepository(workspaceId, { name, parentPath })toapps/web/lib/api/domains/workspace-api.ts, returningRepository. - Refactor
apps/web/components/folder-picker.tsxso its directory-listing, breadcrumb, loading, error, navigation, and current-folder selection are exported as a reusable browser body. Keep the existing None mode trigger behavior unchanged. - Add focused tests for target-path derivation, validation, error retention, and successful API
response handling in
apps/web/components/create-local-repository-surface.test.tsx.
Repository selector and creation surface
- Extend the cmdk-only
Pillcontract inapps/web/components/task-create-dialog-pill.tsxwith an optional command action rendered as aCommandItem; do not insert arbitrary interactive markup intoCommand. Cover keyboard and pointer activation inapps/web/components/task-create-dialog-pill.test.tsx. - Add
apps/web/components/create-local-repository-surface.tsx. It owns shared form state and renders a desktopDialogor mobileDrawerselected withuseResponsiveBreakpoint. - Thread a task-create-only Create new repository action through
apps/web/components/task-create-dialog-repo-chips.tsxandapps/web/components/task-create-dialog-workspace-repo-chips.tsx. Expose it only for a single repository row. Quick Chat callers ofWorkspaceRepoChipsdo not receive the opt-in action. - Add a repository-created handler in
apps/web/components/task-create-dialog-handlers.tsand its prop/type wiring inapps/web/components/task-create-dialog-types.ts,apps/web/components/task-create-dialog-prop-builders.ts, andapps/web/components/task-create-dialog.tsx. It directly patches the originating row with the new repository ID andmain, selects a compatible direct local executor/profile, updates task-create last-used state, and leaves sibling rows untouched. Surface the automatic executor change in the form; block confirmation without filesystem mutation when no direct local profile is available. - Merge the returned DTO into
repositories.itemsByWorkspaceId[workspaceId]through the existing workspace slice without waiting for an asynchronous refetch; deduplicate by repository ID. - Extend
apps/web/components/task-create-dialog-repo-chips.test.tsxandapps/web/components/task-create-dialog-handlers.test.tsfor action visibility, row targeting, cache merge, success, conflict, retry, and cancel behavior.
Mobile Design Contract
- Desktop keeps the repository search popover and opens a compact creation Dialog from its visible command action.
- Mobile keeps the repository selector entry point but opens an inset bottom Drawer modeled on
apps/web/components/task/mobile/mobile-picker-sheet.tsx. - The drawer has fixed name/target context, one internally scrolling directory list, and a fixed safe-area-aware primary footer. Directory and action rows are at least 44px high.
- Shared form state, validation, listing requests, creation request, cache merge, row selection, and direct-local executor selection are viewport-independent. Dismissal creates nothing and returns focus to the originating selector.
- The mobile E2E proves creation and selection, internal scrolling/viewport containment, touch target size, safe-area footer visibility, and absence of document horizontal overflow.
Tests
- Initialization success:
apps/backend/internal/task/service/local_repository_initialization_test.gousest.TempDir()and real Git to assert canonical path, unbornmain, the absence ofHEADcommits, persisted workspace record, and repository-created event. - Input and conflict safety: the same service test table covers invalid names, relative/missing/ non-directory parents, existing empty/non-empty targets, and no mutation or persistence.
- Partial failure cleanup: service tests inject or induce Git/persistence failures and assert no repository row plus request-owned target cleanup behavior.
- HTTP mapping:
apps/backend/internal/task/handlers/repository_handlers_test.gocovers201,400,404, and409, including no filesystem mutation for an unknown workspace. - Frontend form:
apps/web/components/create-local-repository-surface.test.tsxcovers validation, target preview, in-flight disablement, error retention/retry, success callback, and responsive shell. - Selector wiring: existing pill/repo-chip/handler tests prove the action is task-create-only, a returned repository updates only the originating row and active-workspace cache, a worktree selection changes to a direct local profile, missing local profiles prevent the mutation, and the action is absent from multi-repository tasks.
E2E Tests
- Desktop: add
apps/web/e2e/tests/task/create-task-new-local-repository.spec.ts. Open New Task, create a repository under the isolated backend home, assert it is selected withmain, submit the task, and verify the task is bound to the persisted repository, uses a direct local executor, and the filesystem has no commit. Add a target-conflict case that proves the existing directory remains unchanged. - Mobile: add
apps/web/e2e/tests/task/mobile-create-task-new-local-repository.spec.ts. Enter throughMobileKanbanPage.mobileFab, complete the same create-and-submit outcome, and assert Drawer containment, a scrollable internal list, 44px action rows, visible safe-area footer, focus/dismiss behavior, and zero document horizontal overflow.
Implementation Waves
Wave 1:
Wave 2 (after Wave 1):
- task-02-task-create-selector - done
Wave 3 (after integrated backend and frontend):
- task-03-e2e-and-verification - done
The frontend task is sequential because the shared picker, task-create handlers, and state wiring are one behavior and edit overlapping files. E2E follows the integrated product path.
Verification
make fmt
make typecheck
(cd apps/backend && go test ./internal/task/service ./internal/task/handlers)
(cd apps && pnpm --filter @kandev/web test -- --run \
components/create-local-repository-surface.test.tsx \
components/task-create-dialog-pill.test.tsx \
components/task-create-dialog-repo-chips.test.tsx \
components/task-create-dialog-handlers.test.ts)
(cd apps/web && pnpm e2e:run tests/task/create-task-new-local-repository.spec.ts)
(cd apps/web && pnpm e2e:run --no-build --project mobile-chrome \
tests/task/mobile-create-task-new-local-repository.spec.ts)
make test
make lint
Risks
- Filesystem and database persistence cannot share a transaction. The service must narrowly own and test partial-failure cleanup without ever deleting a pre-existing target.
- An unborn Git repository cannot support the existing branch/worktree flow. The form must switch the first task to a direct local executor and must not silently fall back to worktree, container, or remote execution.
- The repository list may already be hydrated while the event arrives asynchronously. Selection must use the returned DTO directly and cache insertion must be idempotent.
- Nested overlays inside the full-height mobile task dialog can break scroll and focus ownership. The directory browser must render inside the creation Drawer rather than opening another phone popover.