103 lines
5.6 KiB
Markdown
103 lines
5.6 KiB
Markdown
---
|
|
status: current
|
|
system: tasks
|
|
requirements:
|
|
- REQ-TASKS-OPEN-FOLDER-001
|
|
---
|
|
|
|
# Open task folder system design
|
|
|
|
## Purpose and boundaries
|
|
|
|
Add a discoverable session shortcut using the existing editors service folder operation.
|
|
This extends task workspace access; it introduces no persistence or new OS integration.
|
|
See [requirements](../requirements/open-task-folder.md) and
|
|
[workspace actions](attach-workspace-sources.md).
|
|
|
|
## Requirement mapping
|
|
|
|
| Requirement | Design sections |
|
|
| --- | --- |
|
|
| REQ-TASKS-OPEN-FOLDER-001 | Components, Selection and transport, Presentation and failures |
|
|
|
|
## Components
|
|
|
|
`apps/web/components/task/task-top-bar.tsx` renders `EditorsMenu` in
|
|
`TopbarToolsGroup`. Add an independent folder control immediately after `EditorsMenu`,
|
|
inside the existing unarchived-task branch. Do not tie it to enabled editors.
|
|
Use `open-task-folder-button.tsx` and shared `useTaskFolderAction` for selection
|
|
and opener focus. The existing `useOpenSessionFolder` owns native-launch requests,
|
|
immediate duplicate-request suppression, loading state, and localized errors. Reuse `buildWorktreeOptions` and `useSessionWorktrees`
|
|
for repository/branch labels rather than duplicating target resolution.
|
|
|
|
The phone Files workspace-actions menu already offers Open workspace folder.
|
|
Reuse that entry and its responsive menu treatment; route multiple-worktree choices
|
|
through `TaskFolderPicker`, using `Dialog` on desktop and `MobilePickerSheet` for
|
|
the short phone or coarse-pointer choice. The Files menu closes before opening
|
|
the picker and passes its persistent trigger for focus restoration.
|
|
Inspect `file-browser.tsx`, `file-browser-data.ts`, and the existing
|
|
`mobile-add-workspace-sources.spec.ts` as the current entry-point precedent.
|
|
|
|
## Selection and transport
|
|
|
|
Extend `openSessionFolder` in `lib/api/domains/session-api.ts` compatibly: retain
|
|
its existing second `ApiRequestOptions` argument and add an optional third payload
|
|
`{ worktree_id?: string }`. Extend the hook's `open` method to accept an optional
|
|
worktree ID. Existing no-argument callers retain their behavior.
|
|
|
|
The existing POST `/api/v1/task-sessions/:id/open-folder` already accepts
|
|
`OpenFolderRequest.WorktreeID`. `Service.OpenFolder` resolves it through
|
|
`resolveSessionPath`: a non-empty worktree ID must belong to the session or fail
|
|
with `ErrWorkspaceNotFound`. Only an empty ID permits the first-worktree and then
|
|
repository-local-path fallbacks. The browser sends identifiers, never a raw path
|
|
or shell command. Multiple choices must be explicit at the new shortcut and phone
|
|
entry point. Clear stale picker selection on session changes; closing a picker
|
|
must not issue a request.
|
|
|
|
Keep the existing backend host boundary. `OpenFolder` dispatches `open`,
|
|
`xdg-open`, or `explorer` with the resolved path as an argument. The backend also reports opener availability and rejects unavailable commands. Successful HTTP completion means the launch
|
|
request was accepted; it does not prove a native window became visible.
|
|
Remote/headless host limitations remain those of the existing action.
|
|
|
|
## Presentation and failures
|
|
|
|
Reuse translated folder copy when possible, adding a localized host-location hint
|
|
where needed. The control has an accessible name, keyboard activation, tooltip,
|
|
loading indicator, and disabled no-session/loading/unavailable states. Pending
|
|
folder launches are shared per session across all controls and clear only when
|
|
the initiating request settles; another session remains independent. Catch rejected requests
|
|
and use the existing localized toast pattern in `useOpenSessionInEditor` so callers
|
|
do not leave unhandled promise rejections. Return null after a surfaced error.
|
|
|
|
On phones, a visible Files menu opens a short temporary choice surface. The shared
|
|
mobile picker supplies one scrolling body, safe-area spacing, dismissal and focus
|
|
return. Its worktree rows have at least 44px hit areas. Keep desktop 28px control
|
|
geometry; do not inherit unconditional touch sizing into `TopbarToolsGroup`.
|
|
No layout/editor preferences or task runtime state change.
|
|
|
|
## Verification boundary
|
|
|
|
Frontend unit tests prove payload selection, stale-session handling, missing-session
|
|
behavior, failure recovery, and editor independence. Playwright proves the actual
|
|
button/menu flows and request payload on desktop and phone. Stub the native-opening
|
|
HTTP response in UI tests rather than launching file managers on CI. Existing Go
|
|
editor tests guard session/worktree resolution. A macOS smoke check proves Finder
|
|
opens the selected folder; record it separately if no macOS host is available.
|
|
|
|
## Host availability
|
|
|
|
The existing GET `/api/v1/editors` response includes `folder_opening_available`.
|
|
The editors service uses `exec.LookPath` for the platform command (`open`,
|
|
`xdg-open`, or `explorer`); unsupported platforms report false. The same command
|
|
mapping is used for opening, and the POST operation rejects unavailable openers.
|
|
The editors boot payload includes `folderOpeningAvailable` alongside its loaded
|
|
items. The shared editors store retains the capability; loaded editor items with
|
|
an unknown capability still trigger discovery. Each effect reads the live store
|
|
before claiming discovery so simultaneous consumers share one request/retry chain. Transient failure gets one delayed
|
|
retry while controls remain disabled; repeated failure settles to false. Unknown,
|
|
failed, or false discovery disables folder-opening controls in the task toolbar,
|
|
Files menu, and `file-actions-dropdown.tsx`, plus `useOpenSessionFolder`. Editor
|
|
entries retain their existing `editors` and `useOpenSessionInEditor` behavior.
|
|
No desktop dialog or mobile bottom sheet opens while unavailable. This checks
|
|
executable installation, like IDE discovery; launch-time failures still show errors.
|