kandev/docs/plans/editor-dropdown-folder/plan.md

created, status, requirements, system_design, legacy_specs

created	status	requirements	system_design	legacy_specs
2026-09-22	implemented	REQ-TASKS-OPEN-FOLDER-001	../../specs/tasks/system-design/open-task-folder.md

Implementation plan: Editor dropdown folder action

Overview

One sequential work order relocates the standalone button added in PR #3784 (commit 32d640f26) into the usual editor dropdown. Estimate: 45-90 minutes including focused browser verification. Tasks owns this capability because the selected task session determines the target workspace.

Confirmed intent: remove the added standalone control and expose folder opening inside the editor dropdown. Keep existing native opening, host availability, worktree selection, and Files-menu access. This is a targeted UI relocation, not a wholesale revert of PR #3784. No unresolved product decisions.

Scope

In scope: dropdown composition and focus, removal of unused button, migration of its regression tests, desktop browser flow, phone regression and public usage copy. Out of scope: backend changes, editor preferences, archived-task visibility, remote mounting, and redesigning phone task navigation.

Technical approach

Follow the design. Reuse the existing folder action and responsive picker. Decouple dropdown availability from enabled-editor count while preserving primary editor behavior. Extract a focused presentation component only if needed for component limits. Update docs/public/developer-tools.md with the new menu path during implementation; leave published instructions matching shipped behavior during this design turn. No ADR: the existing ownership, transport and native-launch boundaries remain.

ASCII UI preview

UI-01: Desktop editor dropdown, expanded

Before: [Open in editor | v] [Folder]

[Open in editor | v]
                 +------------------------+
                 | Existing editor entries|
                 |------------------------|
                 | Open folder            |
                 +------------------------+
                   -> Choose a folder (multiple worktrees only)

UI-02: Phone Files workspace actions, expanded

[Files                         ...]
       [Add repositories          ]
       [Open workspace folder     ]
          -> [Choose a folder     ]
             [repo-a / branch-a   ]
             [repo-b / branch-b   ]

Structural requirements: no standalone toolbar folder button; folder row follows editor choices, independently enabled. No editors: disabled editor primary action and no-editors row, usable dropdown and available folder action. No session: dropdown disabled. Unknown/unavailable opener or pending request: folder row disabled. Opening has a localized live status; errors produce a retryable localized toast. Desktop controls remain 28px. Phone retains its visible Files trigger and existing inset menu/picker, 44px targets, one internal scroller and safe-area spacing; no horizontal page overflow. This temporary choice uses the shipped MobilePickerSheet exemplar. Menu closes before picker opens; dismissal restores the persistent trigger. Icons and spacing are illustrative. Maps to AC-TASKS-OPEN-FOLDER-001.1 through .4 and desktop/mobile folder E2E suites.

Tests

Migrate open-task-folder-button.test.tsx coverage into editors-menu.test.tsx before removing the old suite. Add failing tests for placement/removal, zero editors, keyboard activation, host unavailability, busy state, errors/retry, single/multiple worktrees, cancellation/focus restoration and session changes. Preserve editor launching/default behavior. Use the hook suite for duplicate suppression and payload failures (AC .1-.3, .5). Update all three desktop folder browser scenarios to enter through the dropdown, add zero-editor coverage, and assert absence of the separate control. Retain phone folder scenarios for selection and unavailable hosts, with touch geometry and no-overflow checks (AC .4). Stub native launch HTTP responses; do not open the host GUI in CI. Inspect desktop and phone screenshots against UI-01/UI-02.

Work orders

• Task 01: Relocate folder action

Verification commands

From repository root; install workspace dependencies from apps/ if missing. The managed E2E runner builds the backend, Vite assets and plugin fixtures; separate build commands are unnecessary. Ensure Go is on PATH and set PLAYWRIGHT_BROWSERS_PATH to a writable installed browser cache when required.

(cd apps/web && pnpm exec vitest run components/task/editors-menu.test.tsx components/task/editors-menu-availability.test.ts components/task/editor-worktree-options.test.ts components/task/task-top-bar.test.tsx hooks/use-open-session-folder.test.ts components/task/file-browser-toolbar.test.tsx)
(cd apps/web && NODE_OPTIONS=--max-old-space-size=4096 pnpm run typecheck)
(cd apps/web && pnpm run i18n:check)
(cd apps/web && pnpm e2e:run tests/task/open-task-folder.spec.ts)
(cd apps/web && pnpm e2e:run --project mobile-chrome tests/task/mobile-open-task-folder.spec.ts)
node scripts/validate-public-docs.mjs
node --test scripts/validate-public-docs.test.mjs
python3 scripts/list-docs.py validate
python3 scripts/lint-spec-files.py --all
git diff --check

Verification results

Implemented on 2026-09-23.

• RED: the migrated test failed because the editor dropdown was disabled with zero editors; the remaining folder-menu regressions failed because its folder entry did not exist. The error/retry regression also failed before implementation.
• GREEN: pnpm exec vitest run with the six suites listed above passed 49 tests. All eight original folder-button behaviors are retained in the migrated suite, plus error/retry and independent editor-launch coverage.
• NODE_OPTIONS=--max-old-space-size=4096 pnpm run typecheck passed. The default 2 GiB heap exhausted memory; rerunning with 4 GiB resolved that environment limit.
• Changed-file ESLint passed for both editor components, the migrated test, task topbar and desktop E2E spec.
• Managed E2E built the Go runtime/helpers, production Vite assets and plugin fixture. Desktop folder suite passed 3/3; unchanged phone folder suite passed 2/2. Final runs reused those fresh artifacts with --no-build, Go on PATH, and PLAYWRIGHT_BROWSERS_PATH=/tmp/kandev-folder-browsers.
• node scripts/validate-public-docs.mjs passed (47 pages), and its test file passed 62 tests. Spec catalog validation (299 decisions, 1108 specifications), full spec lint and diff whitespace checks passed.

Localization baseline exception

pnpm run i18n:check fails on 32 missing Japanese keys: 22 executors:sshReachability* and 10 task:launchWarning* entries. git diff --quiet HEAD -- apps/web/src/locales confirms all catalogs are unchanged. This change reuses existing localized copy. The remaining five i18n checks were run directly and passed: Trans indices, inline plurals, module-scope translations, em dashes, and non-JSX copy. This unrelated catalog failure is retained as an explicit validation exception.

Browser evidence and limits

Screenshots retained in /tmp/editor-folder-evidence/: desktop folder menu, desktop repository picker and mobile repository picker. Phone evidence shows an inset sheet, contained 44px rows and no horizontal overflow. Desktop tests verify the removed button, 28px dropdown trigger, menu reachability without editors, selected-worktree payload, keyboard use, cancellation focus and retry. Native opening is HTTP-stubbed; these tests do not assert Finder/Explorer window visibility. No backend native-launch behavior changed.

Risks

The editor-count guard can accidentally hide folder opening. Dropdown focus restoration can dismiss a newly opened picker unless opening waits for menu close. The original package records an unrelated source-attachment E2E baseline failure; this package targets the folder suites. Native window visibility remains outside HTTP-stubbed browser evidence.

PR review remediation (2026-09-24)

Claude's inline finding and summary suggestion identified the editor-only accessible name on a menu that also opens folders. The trigger now announces "Editor and folder actions" through task:editorActions in all six locales and the pseudo locale; Traditional Chinese values use the repository converter. The new focused regression failed before the change.

Post-fix checks: pnpm exec vitest run components/task/editors-menu.test.tsx passes 11 tests; changed-file ESLint passes; a fresh managed production build and pnpm e2e:run --host tests/task/open-task-folder.spec.ts pass all 3 browser tests, including the accessible-name assertion. The local full i18n check still reports the previously recorded Japanese keys, which are already fixed on current main; none of its findings concern the new label.