Developer
caadd59441
Move the following audited-and-implemented changes into openspec/changes/archive/2026-06-12-completed-changes-archive/: - backend-frontend-refactoring - config-profile-git-mounts - config-profile-includes-ui - config-profile-multi-repo-mounts - container-monitoring-notifications - git-mount-url-validation - home-path-expansion - mobile-terminal-ux - mount-specificity-ordering - notification-center - persistent-terminal-sessions - session-list-overhaul - ssh-key-mounting - terminal-fullscreen-unified-header - tool-session-progress-and-updates Also regenerated .pi-map*.md files for openspec/changes so the remaining active changes (multi-session-terminal-ux, reorganize-long-files, working-copies, workspace-first-ui) reflect the new layout.
71 lines
4.1 KiB
Markdown
71 lines
4.1 KiB
Markdown
## Context
|
|
|
|
The config profiles backend already supports full ordered include composition:
|
|
- `PUT /config-profiles/{id}/includes` accepts an ordered array of profile IDs
|
|
- The API validates ownership, self-inclusion, existence, and cycles
|
|
- `GET /config-profiles/{id}/preview` resolves includes and shows merged output
|
|
- The frontend profile editor (`config-profiles.tsx`) already loads all profiles via `listConfigProfiles()`
|
|
|
|
However, the profile editor UI currently has no includes management surface. Users can create individual profiles but cannot compose them. This design adds a drag-and-drop includes management section to the existing profile editor.
|
|
|
|
## Goals / Non-Goals
|
|
|
|
**Goals:**
|
|
- Allow users to see which profiles a profile includes
|
|
- Allow users to add, remove, and reorder includes
|
|
- Prevent invalid includes (self, duplicates, cycles) in the UI
|
|
- Show scope badges on included profiles for clarity
|
|
- Display include count in the profile list sidebar
|
|
- Save includes together with the profile form
|
|
|
|
**Non-Goals:**
|
|
- Backend changes (APIs already fully support this)
|
|
- Drag-and-drop library dependency (use native HTML5 DnD)
|
|
- Profile dependency graph visualization (future enhancement)
|
|
- Validation of include compatibility at the scope level (backend handles this)
|
|
|
|
## Decisions
|
|
|
|
### Use Native HTML5 Drag and Drop
|
|
**Rationale:** No additional dependency needed. The includes list is small (typically < 10 items), so native DnD is sufficient and lightweight. Libraries like react-beautiful-dnd add bundle size and complexity for this use case.
|
|
**Alternative considered:** `@dnd-kit/core` — rejected to keep dependencies minimal.
|
|
|
|
### Save Includes with Main Form
|
|
**Rationale:** The user explicitly requested this. It's simpler UX than a separate save button and matches the mental model of "editing a profile."
|
|
**Implementation:** On save, first update profile fields via `updateConfigProfile()`, then update includes via `updateProfileIncludes()`. If either fails, show error and don't clear dirty state.
|
|
|
|
### Frontend Cycle Detection
|
|
**Rationale:** Prevents the user from even selecting profiles that would create a cycle, providing immediate feedback instead of waiting for the API to reject it.
|
|
**Implementation:** Build a graph from the current `profiles` array (which includes `includes` data), then traverse from each candidate profile to check if it can reach the current profile.
|
|
|
|
### Scope Badge Display
|
|
**Rationale:** Helps users understand why certain profiles are or aren't available for inclusion, and what scope each layer operates at.
|
|
**Implementation:** Reuse existing scope badge logic from the profile list sidebar (Global, Project scoped, Tool scoped, Project + Tool scoped).
|
|
|
|
### Include Count Badge in Sidebar
|
|
**Rationale:** Quick visual indicator of which profiles are composite vs. standalone.
|
|
**Implementation:** Add a small numeric badge next to the profile name when `profile.includes.length > 0`.
|
|
|
|
## Risks / Trade-offs
|
|
|
|
**[Risk]** Saving profile and includes as two separate API calls could lead to partial success (profile saved, includes not saved).
|
|
→ **Mitigation:** Show clear error state if either call fails. The user can retry. Since includes are independent of profile content, partial failure is recoverable.
|
|
|
|
**[Risk]** Large number of profiles could make the "Add Include" dropdown unwieldy.
|
|
→ **Mitigation:** Cap the dropdown height and add scroll. Typical users have < 20 profiles.
|
|
|
|
**[Risk]** Drag-and-drop reordering may feel clunky on mobile.
|
|
→ **Mitigation:** This is primarily a desktop admin/settings interface. Mobile support is nice-to-have but not critical.
|
|
|
|
## Migration Plan
|
|
|
|
No migration needed — this is a pure frontend addition. Existing profiles with includes (created via API) will immediately show those includes in the UI.
|
|
|
|
## Open Questions
|
|
|
|
1. Should we show a preview of the resolved output (with includes applied) in real-time as includes change?
|
|
- *Tentative: No, keep the existing Preview button. Real-time resolution could be expensive and is not requested.*
|
|
|
|
2. Should we allow including profiles from other users (shared profiles)?
|
|
- *Tentative: No, backend already restricts to own profiles. Keep it simple.*
|