docs: add repo import list helper design spec
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
mika kuns
@@ -0,0 +1,138 @@
|
|||||||
|
# Repo Import List Helper — Design
|
||||||
|
|
||||||
|
**Date:** 2026-05-29
|
||||||
|
**Status:** Approved (pending spec review)
|
||||||
|
|
||||||
|
## Problem
|
||||||
|
|
||||||
|
Creating lists is one-at-a-time: click `+ New list`, then open List Settings to set the
|
||||||
|
working directory. Users with many repos under a few parent folders want to wire them all up
|
||||||
|
in one pass.
|
||||||
|
|
||||||
|
## Goal
|
||||||
|
|
||||||
|
A "list helper" that scans one or more parent folders for git repos, presents them as a
|
||||||
|
checklist, and bulk-creates a list (with `WorkingDir` pre-filled) for each ticked repo.
|
||||||
|
|
||||||
|
## Entry Points
|
||||||
|
|
||||||
|
1. **Help menu** — the title-bar dropdown in `MainWindow.axaml` that contains `About…`,
|
||||||
|
`Worktrees…`, etc. Add a new `MenuItem` `Add repos as lists…` wired to a command on
|
||||||
|
`MainWindowViewModel`.
|
||||||
|
2. **Lists island** — a small folder icon button beside the existing `+ New list` button in
|
||||||
|
`ListsIslandView.axaml`, wired to a command on `ListsIslandViewModel`.
|
||||||
|
|
||||||
|
Both open the same modal.
|
||||||
|
|
||||||
|
## Components
|
||||||
|
|
||||||
|
### `RepoScanner` (new, `ClaudeDo.Ui/Services` or `ClaudeDo.Data`)
|
||||||
|
|
||||||
|
Pure filesystem helper, no git library. Given a parent folder path, enumerates immediate
|
||||||
|
subdirectories and returns those that contain a `.git` entry (directory or file). Kept
|
||||||
|
separate from the VM so it is unit-testable.
|
||||||
|
|
||||||
|
```
|
||||||
|
IReadOnlyList<RepoCandidate> Scan(string parentFolder)
|
||||||
|
record RepoCandidate(string Name, string FullPath)
|
||||||
|
```
|
||||||
|
|
||||||
|
- Skips the parent itself; only immediate children are considered (non-recursive).
|
||||||
|
- `.git` may be a directory (normal repo) or a file (worktree/submodule) — both count.
|
||||||
|
- Returns empty on missing/unreadable folder rather than throwing.
|
||||||
|
|
||||||
|
### `RepoImportModalViewModel` (new, `ClaudeDo.Ui/ViewModels/Modals`)
|
||||||
|
|
||||||
|
Follows the existing modal-VM pattern (`CloseAction`, resolved from DI).
|
||||||
|
|
||||||
|
Dependencies:
|
||||||
|
- `IDbContextFactory<ClaudeDoDbContext>` — load existing lists' `WorkingDir` values (for the
|
||||||
|
"already added" check) and create new `ListEntity` rows. Same dependency
|
||||||
|
`ListsIslandViewModel` already uses.
|
||||||
|
|
||||||
|
State:
|
||||||
|
- `ObservableCollection<RepoImportItemViewModel> Repos` — the combined checklist.
|
||||||
|
- A set of parent folder paths already scanned (to de-dupe re-adds).
|
||||||
|
- `CreateCount` — computed count of ticked-and-new rows (drives the confirm button label).
|
||||||
|
|
||||||
|
Commands:
|
||||||
|
- `AddFolderAsync` — invokes the folder picker (via view code-behind callback, see below),
|
||||||
|
scans each chosen folder with `RepoScanner`, appends new candidates. De-dupes by full path
|
||||||
|
(case-insensitive) against rows already present.
|
||||||
|
- `CreateAsync` — for each ticked, non-existing row, create a `ListEntity` via
|
||||||
|
`ListRepository.AddAsync` (Name = folder name, WorkingDir = full path,
|
||||||
|
DefaultCommitType = `CommitTypeRegistry.DefaultType`, fresh `Guid` id, `CreatedAt` = now).
|
||||||
|
Then `CloseAction()`.
|
||||||
|
- `Cancel` — `CloseAction()`.
|
||||||
|
|
||||||
|
On load, fetch all existing lists once and capture their `WorkingDir`s into a case-insensitive
|
||||||
|
set; each appended candidate whose path is in that set is marked `AlreadyAdded`.
|
||||||
|
|
||||||
|
### `RepoImportItemViewModel` (new)
|
||||||
|
|
||||||
|
- `Name`, `FullPath` (display).
|
||||||
|
- `AlreadyAdded` (bool) — true if a list already points at this path.
|
||||||
|
- `IsChecked` ([ObservableProperty]) — defaults `true` for new repos. For already-added rows it
|
||||||
|
is forced `true` and the checkbox is disabled.
|
||||||
|
- `CanToggle` => `!AlreadyAdded` (binds to checkbox `IsEnabled`).
|
||||||
|
|
||||||
|
### `RepoImportModalView` (new, `ClaudeDo.Ui/Views/Modals`)
|
||||||
|
|
||||||
|
A `Window` styled like the other modals (header bar, body, footer), shown via
|
||||||
|
`ShowDialog(owner)`.
|
||||||
|
|
||||||
|
- **Header:** title `ADD REPOS AS LISTS` + close button.
|
||||||
|
- **Top of body:** `Add folder…` button.
|
||||||
|
- **Body:** scrollable `ItemsControl` over `Repos`. Each row = `CheckBox` (IsChecked two-way,
|
||||||
|
IsEnabled = `CanToggle`) + repo name + dim full path + `(already added)` label when
|
||||||
|
`AlreadyAdded`.
|
||||||
|
- **Footer:** `Create {CreateCount} lists` button (disabled when `CreateCount == 0`) + `Cancel`.
|
||||||
|
- Folder picker lives in the code-behind (mirrors `ListSettingsModalView.BrowseClicked`):
|
||||||
|
`OpenFolderPickerAsync` with `AllowMultiple = true`, results handed to the VM's
|
||||||
|
`AddFolderAsync`.
|
||||||
|
|
||||||
|
## Data Flow
|
||||||
|
|
||||||
|
1. User opens the modal from either entry point → modal loads existing lists' `WorkingDir`s.
|
||||||
|
2. User clicks `Add folder…` → picks one or more parent folders → `RepoScanner` finds repos →
|
||||||
|
rows appended (de-duped), already-added rows shown ticked+disabled.
|
||||||
|
3. User adjusts ticks → clicks `Create N lists`.
|
||||||
|
4. VM creates one `ListEntity` per ticked-new row via `ListRepository`.
|
||||||
|
5. Modal closes → the **caller reloads the Lists island** so new lists appear:
|
||||||
|
- Lists-island entry point: `ListsIslandViewModel.LoadAsync()`.
|
||||||
|
- Help-menu entry point: `MainWindowViewModel` reloads its `Lists` (the
|
||||||
|
`ListsIslandViewModel` instance) after the modal closes.
|
||||||
|
|
||||||
|
## DI / Wiring
|
||||||
|
|
||||||
|
- Register `RepoImportModalViewModel` (transient) alongside other modal VMs.
|
||||||
|
- Register `RepoScanner` if implemented as an injected service; a static helper needs no
|
||||||
|
registration.
|
||||||
|
- `ListsIslandViewModel` gains `Func<RepoImportModalViewModel, Task>? ShowRepoImportModal` and
|
||||||
|
an `OpenRepoImportCommand`, wired in `ListsIslandView.axaml.cs` (mirrors
|
||||||
|
`ShowListSettingsModal`).
|
||||||
|
- `MainWindowViewModel` gains the same `Func` + an `OpenRepoImportCommand`, wired in
|
||||||
|
`MainWindow.axaml.cs`.
|
||||||
|
|
||||||
|
## Error Handling
|
||||||
|
|
||||||
|
- Unreadable / missing folders: `RepoScanner` returns empty, no crash.
|
||||||
|
- Re-adding a folder already scanned: de-duped by path, no duplicate rows.
|
||||||
|
- Two ticked repos sharing a folder name: both created (list names are not unique) — acceptable.
|
||||||
|
- List creation failure (rare): best-effort per the existing pattern; do not block remaining
|
||||||
|
creations.
|
||||||
|
|
||||||
|
## Testing
|
||||||
|
|
||||||
|
- `RepoScanner` unit tests (the testable seam): a temp directory tree with a mix of git repos
|
||||||
|
(`.git` dir), a `.git`-file repo, plain folders, and an empty/missing parent. Assert only the
|
||||||
|
repo subfolders are returned and missing folders yield empty.
|
||||||
|
- VM-level "already added" logic and `CreateCount` can be exercised if a test seam is convenient,
|
||||||
|
but the filesystem scanner is the primary unit under test. UI wiring verified manually.
|
||||||
|
|
||||||
|
## Out of Scope (YAGNI)
|
||||||
|
|
||||||
|
- Recursive / deep scanning.
|
||||||
|
- Inline editing of the list name before creation.
|
||||||
|
- Setting model / system prompt / agent during import (tuned later per-list in List Settings).
|
||||||
|
- Picking repo folders directly (only parent-folder scan, per decision).
|
||||||
Reference in New Issue
Block a user