feat(ui): browse filesystem for new projects

peter commented

2026-06-24 22:44:01 +02:00

Owner

Why

The Sessions and Projects dashboard pages should have obvious creation actions, but they should not do the same job:

New project should add/start from a local directory chosen from this machine.
New session should start from a project ocman already knows about.

Pre-populating the New project flow with known projects was confusing, because selecting a known project does not add anything new. Reusing the filesystem browser for New session was confusing in the other direction, because starting a session is usually a project-list action once projects exist.

Observed

The dashboard sessions/projects views did not expose clear create actions from those pages.
The project picker opened with known projects before the user started browsing.
After adding the filesystem browser, the Sessions page's New session action also opened that directory browser because both actions shared one palette mode.
Search results could show the same absolute directory more than once when the typed query was itself an existing directory.
Clicking a directory result cleared the search input, making it awkward to continue narrowing into a selected subdirectory.
The picker had a "Use current directory" row that immediately finalized selection, which conflicted with the intended "Use this directory" confirmation flow.

Inferred / Assumed

For "New project", the primary job is local filesystem discovery, not choosing from already-known projects.
For "New session", the primary job is choosing an existing known project and starting a session there.
Directory rows should browse/navigate only; final project/session creation from the filesystem browser should happen through the explicit "Use this directory" button.
A small, bounded backend search endpoint is easier to test and reason about than recursive filesystem search logic in the frontend.
The filesystem browser should operate on the ocman server's local machine; remote-host browsing is out of scope for this change.

Changes

Add "New session" / "New project" actions to the dashboard sessions/projects views.
Add localhost-only filesystem browse/search endpoints:
- GET /api/filesystem/directories?dir=...
- GET /api/filesystem/directory-search?root=&q=&limit=50
Keep Project page "New project" in a filesystem browser/search mode.
Add a separate known-project picker mode for Sessions page "New session", Alt+N, and "New session in project".
Remove the extra "Browse this machine" and "Use current directory" paths.
Keep the selected directory path in the input after opening a search result so typing can continue within that directory.
Deduplicate exact absolute-directory search results.
Refresh project/session queries after creating a session from a browsed directory.
Update first-run empty state copy to point users at adding a project first.
Add focused backend integration tests and command-palette render tests for browse/search/create-session behavior and the split project/session picker modes.

Caveats

Filesystem browse/search is intentionally local-only and bounded; it is not a full Spotlight/Finder replacement.
Search skips common generated/heavy directories, skips symlinked directories, and limits traversal depth/visited directories, so it favors responsiveness over exhaustive results.
In multi-remote setups, this browser only sees the filesystem of the ocman server handling the request; browsing remote machines would need a separate host-aware design.
If no projects are known yet, the New session picker has nothing useful to show; the first-run path is to add a project directory or run opencode in a project first.

Verification

cd frontend && pnpm exec vitest run src/components/CommandPalette.render.test.tsx src/components/GettingStartedEmpty.test.tsx
cd frontend && pnpm exec tsc -b
cd frontend && pnpm lint
cd frontend && pnpm test
make lint
git diff --check
make build
Browser smoke on http://127.0.0.1:8228:
- /projects → "New project" opens Browse project directories... with Use this directory.
- / → "New session" opens Select a project to start a session... with known projects and no filesystem confirm button.
Backend endpoint coverage from the PR:
- GOCACHE=/Users/peter/workspace/ocman/tmp/go-build go test ./internal/server -run 'TestHandleFilesystem|TestHandleCreateSession_RefreshesProjectsIndex|TestHandleProjects_UsesInMemoryIndexUntilRefresh'
- GOCACHE=/Users/peter/workspace/ocman/tmp/go-build go test ./...

## Why The Sessions and Projects dashboard pages should have obvious creation actions, but they should not do the same job: - **New project** should add/start from a local directory chosen from this machine. - **New session** should start from a project ocman already knows about. Pre-populating the New project flow with known projects was confusing, because selecting a known project does not add anything new. Reusing the filesystem browser for New session was confusing in the other direction, because starting a session is usually a project-list action once projects exist. ## Observed - The dashboard sessions/projects views did not expose clear create actions from those pages. - The project picker opened with known projects before the user started browsing. - After adding the filesystem browser, the Sessions page's New session action also opened that directory browser because both actions shared one palette mode. - Search results could show the same absolute directory more than once when the typed query was itself an existing directory. - Clicking a directory result cleared the search input, making it awkward to continue narrowing into a selected subdirectory. - The picker had a "Use current directory" row that immediately finalized selection, which conflicted with the intended "Use this directory" confirmation flow. ## Inferred / Assumed - For "New project", the primary job is local filesystem discovery, not choosing from already-known projects. - For "New session", the primary job is choosing an existing known project and starting a session there. - Directory rows should browse/navigate only; final project/session creation from the filesystem browser should happen through the explicit "Use this directory" button. - A small, bounded backend search endpoint is easier to test and reason about than recursive filesystem search logic in the frontend. - The filesystem browser should operate on the ocman server's local machine; remote-host browsing is out of scope for this change. ## Changes - Add "New session" / "New project" actions to the dashboard sessions/projects views. - Add localhost-only filesystem browse/search endpoints: - `GET /api/filesystem/directories?dir=...` - `GET /api/filesystem/directory-search?root=&q=&limit=50` - Keep Project page "New project" in a filesystem browser/search mode. - Add a separate known-project picker mode for Sessions page "New session", `Alt+N`, and "New session in project". - Remove the extra "Browse this machine" and "Use current directory" paths. - Keep the selected directory path in the input after opening a search result so typing can continue within that directory. - Deduplicate exact absolute-directory search results. - Refresh project/session queries after creating a session from a browsed directory. - Update first-run empty state copy to point users at adding a project first. - Add focused backend integration tests and command-palette render tests for browse/search/create-session behavior and the split project/session picker modes. ## Caveats - Filesystem browse/search is intentionally local-only and bounded; it is not a full Spotlight/Finder replacement. - Search skips common generated/heavy directories, skips symlinked directories, and limits traversal depth/visited directories, so it favors responsiveness over exhaustive results. - In multi-remote setups, this browser only sees the filesystem of the ocman server handling the request; browsing remote machines would need a separate host-aware design. - If no projects are known yet, the New session picker has nothing useful to show; the first-run path is to add a project directory or run `opencode` in a project first. ## Verification - `cd frontend && pnpm exec vitest run src/components/CommandPalette.render.test.tsx src/components/GettingStartedEmpty.test.tsx` - `cd frontend && pnpm exec tsc -b` - `cd frontend && pnpm lint` - `cd frontend && pnpm test` - `make lint` - `git diff --check` - `make build` - Browser smoke on `http://127.0.0.1:8228`: - `/projects` → "New project" opens `Browse project directories...` with `Use this directory`. - `/` → "New session" opens `Select a project to start a session...` with known projects and no filesystem confirm button. - Backend endpoint coverage from the PR: - `GOCACHE=/Users/peter/workspace/ocman/tmp/go-build go test ./internal/server -run 'TestHandleFilesystem|TestHandleCreateSession_RefreshesProjectsIndex|TestHandleProjects_UsesInMemoryIndexUntilRefresh'` - `GOCACHE=/Users/peter/workspace/ocman/tmp/go-build go test ./...`

peter added 2 commits

2026-06-24 22:44:01 +02:00