RFD 099: Native macOS App for Browsing Conversations

• Status: Accepted
• Category: Design
• Authors: Jean Mertz git@jeanmertz.com
• Date: 2026-07-31
• Summary: Native macOS app for browsing JP conversations via FFI, with public Workspace::open API extracted from CLI.

Summary

This RFD introduces a native macOS app for reading JP conversations, built in SwiftUI over a thin Rust FFI crate (jp_ffi) that links jp_workspace and jp_conversation directly into the app process. It adds Workspace::open so that "turn a path into a usable workspace" becomes a library capability instead of private CLI code, and ships a jp-gui command plugin so jp gui opens the current workspace in the app.

Motivation

JP conversations are readable from the terminal (jp conversation print) and, with RFD 072's plugin system, from a browser (jp serve web). Neither is a good fit for browsing: scrolling back through weeks of turns, skimming several conversations side by side, or reading on the machine where the work happened. That is what a Mac app is for, and it should be a real one: native windows, tabs, menus, keyboard, and state restoration, not a web view in a window.

The second motivation is structural. Workspace has had exactly one consumer since it was written, and its API shows it. The sequence that turns a filesystem path into a usable workspace is seven steps long and lives in load_workspace, a private function in jp_cli:

1. Walk up from a directory looking for .jp (Workspace::find_root).
2. Load the workspace Id from .jp/.
3. Build FsStorageBackend::new(.jp).
4. Resolve user_data_dir()/workspace as the user-storage root.
5. Wire user storage with with_user_storage(user_root, slug, id).
6. Workspace::new_with_id(root, id).with_backend(fs).
7. Persist the ID back with id().store(&storage).

Nothing outside jp_cli can call that. A second consumer has three options: depend on jp_cli (which pulls in clap, the printer, every LLM provider, and MCP), copy the forty lines, or extract them.

Copying is worse than it looks because of step 5. Skip it and everything compiles, Workspace::conversations() still returns results, and no error fires. You see a subset, because conversations are read from the user-local silo as well as .jp/ (see RFD 073). RFD 072 records this already happening once, when the web server was written without local storage wired up.

Meanwhile Workspace::new(path) is public, is the most inviting door in the API, and is the wrong one: it hands back an in-memory workspace with no filesystem backend. It exists so tests can build a workspace without touching disk, and to leave room for future designs that drop the user-storage requirement. Both are good reasons for the constructor to exist. Neither is a reason for it to be the one a new consumer finds first.

At N=1 consumer this cost was invisible. At N=2 it is the first thing the second consumer hits.

Design

User Experience

The app is a viewer: it opens workspaces and reads conversations. It never writes conversation data and has no compose field.

• Opening. File > Open presents a directory chooser; picking any directory inside a workspace opens that workspace, matching jp's own behavior of walking up to find .jp. File > Open Recent lists previously opened workspaces.
• Windows. One window per workspace, participating in native window tabbing, so tabs can be pulled out into their own windows.
• Layout. Two panes: conversation list on the left, conversation history on the right, split by a draggable divider whose position is restored across launches.
• Conversations. The list sorts by last activity and shows title and timestamp. Double-clicking a conversation opens it in its own window.
• Terminal integration. jp gui opens the current workspace in the app.

Menus, keyboard shortcuts, selection behavior, copy representations, and drag sources are designed as their own deliverable (see the Implementation Plan); this RFD fixes the shape of the app, not its affordance map.

Repository Layout

crates/jp_ffi/                 # staticlib: C ABI over jp_workspace + jp_conversation
crates/plugins/command/gui/    # jp-gui: launches the app at a workspace root
apps/macos/                    # Xcode project and Swift sources (not a cargo member)

apps/macos/ sits outside crates/ so the cargo workspace globs (crates/jp_*, crates/plugins/command/*, crates/contrib/*) are unaffected and cargo build at the root stays a pure Rust build. crates/contrib/ is for standalone Rust crates and is a poor fit for a Swift target.

Workspace::open

The seven-step sequence moves into jp_workspace, which already owns find_root, Id::load, and user_data_dir():

impl Workspace {
    /// Open the workspace containing `dir`, wiring filesystem and user-local
    /// storage.
    pub fn open(dir: &Utf8Path) -> Result<Self>;

    /// The filesystem storage backend, when opened from disk.
    pub fn fs_storage(&self) -> Option<&Arc<FsStorageBackend>>;
}

jp_cli::load_workspace keeps its workspace-ID lookup branch and --no-persist handling, and delegates the path case to Workspace::open. Behavior is identical, including the writes on open (silo creation, symlink repair, ID persistence).

To stop the wrong door being the obvious one, the in-memory constructors are renamed to say what they are:

Verb	Method	Consumer
in_memory	Workspace::in_memory{,_with_id}(root)	tests
open	Workspace::open(dir)	CLI, app, future
(create)	explicit builder, unchanged	jp init

jp init is creating rather than opening (there is no .jp yet and it mints the ID), so it keeps building explicitly. A Workspace::create verb can be introduced when a second creator exists.

The rename touches 106 call sites of Workspace::new / Workspace::new_with_id across crates/, all but two of them in test code. It is mechanical, and it is the moment to do it: the API is about to acquire its second consumer.

The FFI Boundary

jp_ffi compiles as a static library with a C ABI. Six entry points:

pub extern "C" fn jp_workspace_open(path: *const c_char) -> *mut WorkspaceRef;
pub extern "C" fn jp_workspace_conversations(ws: *mut WorkspaceRef) -> *mut c_char;
pub extern "C" fn jp_workspace_events(ws: *mut WorkspaceRef, id: *const c_char) -> *mut c_char;
pub extern "C" fn jp_workspace_close(ws: *mut WorkspaceRef);
pub extern "C" fn jp_string_free(s: *mut c_char);
pub extern "C" fn jp_last_error() -> *mut c_char;

Rules the boundary holds to:

• Every entry point wraps its body in catch_unwind. A panic unwinding across the FFI boundary is undefined behavior. This wrapper is what makes an in-process boundary acceptable rather than reckless.
• Failures return null and set a thread-local error, retrieved with jp_last_error().
• Owned data only. Reads copy out and drop their parking_lot guard before returning. No guard, reference, or borrow crosses the boundary.
• Rust frees what Rust allocates. Swift calls jp_string_free.
• JSON payloads, decoded into Swift Codable structs. Three payload types hand-maintained on the Swift side.

jp_ffi depends on jp_workspace and jp_conversation. Not jp_config, not jp_cli. A reader needs no config: there is no per-tool style to apply, no reasoning display mode, no hidden-tool filtering. Keeping jp_config out keeps the layered load pipeline (which lives in jp_cli) out with it.

Events already serialize to JSON: the plugin host answers PluginToHost::ReadEvents with Vec<Value> today, so jp_workspace_events is the same projection behind a different door.

Build Integration

just owns the Rust build (cargo build -p jp_ffi), producing libjp_ffi.a and a generated header. Xcode invokes just from a Run Script build phase and links the artifact, so there is one build entry point rather than two competing ones. An .xcframework is only worth assembling when the app is distributed.

jp gui

A command plugin under RFD 072. InitMessage.workspace.root already carries a resolved workspace root, so the plugin needs no path logic: it sends Ready, launches the app with the root as an argument, and sends Exit.

jp gui uses the current directory's workspace; jp -w ../other gui targets another one, since -w/--workspace is already a global flag. A trailing path (jp gui .) arrives in init.args and is validated against the resolved root.

Drawbacks

• A second language in the repository. CI needs a macOS runner for the Swift target, and contributors on other platforms cannot build the app. The Rust workspace is unaffected, but "run the tests" stops being one command.
• No failure isolation. A bug in jp_workspace crashes the app. The catch_unwind wrapper converts panics into errors; it does nothing about aborts or memory corruption.
• A hand-maintained mirror. Swift Codable structs duplicate the shape of Rust types with no compiler checking that they match. Cheap at three types, and the reason the Alternatives section names a trigger for adopting a bindings generator.
• Workspace grows a second public shape. fs_storage() means Workspace knows one concrete backend type alongside its trait objects. The alternative is returning a tuple from open and threading it through every caller, which is worse at more call sites.
• A rename with a wide diff. 106 call sites, almost all tests, in one mechanical commit.

Alternatives

Sidecar process speaking a protocol

The app spawns a jp child per window and talks JSON-lines over pipes. This buys real failure isolation and a protocol testable from both sides without Xcode. It costs process supervision, protocol versioning, and one child process per window, and the existing plugin protocol cannot be reused as-is: jp is the parent that issues Init, and the app needs to be the parent, so the roles invert. For a read-only viewer with no long-running Rust state, that is complexity without a matching benefit. Write support (sending a query from the app) is the condition that flips this call.

Shelling out to jp ... --format json

Fastest to start and the worst contract. jp_cli::output builds JSON from table rows, so the app would bind to presentation-derived shapes that are explicitly not stable yet, and Hyrum's Law would freeze them the moment the app shipped. It also pays a full workspace load per read, in a UI that scrolls.

UniFFI or swift-bridge from the start

Both generate typed Swift bindings and error mapping, removing the hand-maintained mirror. Both also add a codegen step to the build at the moment when the build is the risky part. Six functions and three payload types do not justify it. The trigger to adopt one: the surface passing roughly ten calls, or needing Rust-to-Swift callbacks for live updates.

Swift reading .jp/ directly

Rejected. It reimplements the storage format in a second language and freezes the on-disk layout as a public contract.

A separate repository for the app

Rejected. The FFI boundary changes on both sides at once, and a split repository turns every signature change into a two-repository dance.

Non-Goals

• Writing. No compose field, no editing, no archiving, no config mutation. The app opens conversations and reads them.
• Noticing on its own. Every read through the boundary re-reads the conversation index first, so a call made after a concurrent jp query sees that query's turns and any conversation it started. What the app does not do is notice: nothing watches the store, so the view changes only when something asks it to. The Live Workspace View draft is the mechanism for a workspace that pushes.
• Read-only workspace opening. Opening a workspace creates the user-local silo, repairs its symlink, and persists the workspace ID, exactly as jp does today. Making that side-effect-free is out of scope.
• Renaming Project / Workspace / Storage. Workspace::open is a new door on the existing vocabulary. The Project, Workspace and Storage draft owns the terminology question.
• Tool calls, attachments, and reasoning display. Events other than user messages and assistant messages render as a minimal placeholder.
• iOS, iPadOS, Catalyst, App Store distribution, sandboxing.
• Sharing the render projection. The app is the third consumer that walks a ConversationStream to decide what to show, after terminal print and serve-web. Extracting a presentation-neutral projection is defensible at three consumers, but not in this RFD.

Risks and Open Questions

• Xcode build integration is the real risk, not SwiftUI. Linking a Rust static library, header generation, signing, and keeping the inner loop fast are all unknowns until tried. Phase 2 exists to find out early.
• Recents without a document-based app. A workspace is a directory, not a file, which makes SwiftUI's DocumentGroup an awkward fit. The lean is WindowGroup plus NSOpenPanel with a hand-managed recents list, but whether File > Open Recent can be populated cleanly outside an NSDocument app needs verifying in Phase 2.
• Payload type reuse. jp_plugin::message::ConversationSummary already has exactly the fields the list needs, and jp_plugin is a light crate. Reusing it saves a definition but couples the FFI payload to the plugin wire format, which will eventually diverge. The lean is to reuse it for v0.1 and fork when the shapes disagree.
• Concurrent reads while jp query writes. The app reads files another process appends to. serve-web has the same exposure and no reported corruption, but a partially written event file has not been deliberately tested.
• Threading. Workspace reads are synchronous and take locks. FFI calls must run off the main thread, or the UI stalls behind a lock held by a slow read.

Implementation Plan

Phase 1: Workspace::open

• Move the path branch of jp_cli::load_workspace into jp_workspace::Workspace::open; add fs_storage().
• Rename new / new_with_id to in_memory / in_memory_with_id.
• Characterization test first: opening a workspace whose conversations exist only in the user-local silo returns them.
• No behavior change. Merges independently, and pays for itself in jp_cli alone.

Phase 2: The seam

• crates/jp_ffi with jp_workspace_open, jp_workspace_conversations, jp_string_free, jp_last_error, each wrapped in catch_unwind.
• apps/macos/ Xcode project, just recipe for the static library, Run Script build phase.
• One SwiftUI List showing conversation titles from a hardcoded workspace path.
• Nothing else. This phase exists to prove the build, not the app.
• Depends on Phase 1.

Phase 3: The reader

• jp_workspace_events, jp_workspace_close.
• Two-pane split view, conversation list sorted by last activity, history pane rendering user and assistant messages as native text with markdown.
• File > Open with a directory chooser and workspace-root resolution.
• This phase satisfies the MVP goal: open the JP workspace, browse and scroll conversations.

Phase 4: Mac behavior and jp gui

• Affordance map covering menus, shortcuts, selection, copy representations, drag sources, and accessibility roles for the list and history panes.
• Window tabbing, per-window state restoration (split position, selection, scroll position), File > Open Recent.
• Double-click to open a conversation in its own window.
• Manual QA checklist against the Mac behavior test plan.
• crates/plugins/command/gui implementing the RFD 072 protocol, launching the app at InitMessage.workspace.root and exiting. Folded in here rather than given a phase of its own: it is one small plugin that needs only an app accepting a workspace path, which Phase 3 delivers.

References

• RFD 072 for the command plugin protocol that jp-gui speaks.
• RFD 073 for why user-local storage must be wired before conversations can be listed.
• Mac-arsed Mac App skill for the native-behavior bar the app is held to.