How it works

Components#

PalanaCore is a Swift library containing host discovery, directory listing, address parsing, plan composition, transfer execution, and verification. Palana is the SwiftUI application containing window state, panels, keyboard routing, local file watching, remote pane refresh, shells, and settings.

The plan engine is a pure function from a request and gathered facts to a Plan value. Host reads and transport execution occur outside that function, which lets tests check command composition without contacting a host.

SSH and processes#

Remote commands use the system ssh binary with the user's configuration, keys, agent, and jump-host rules. The SSH conduit reuses a ControlMaster connection per host. A proxy transfer uses two SSH processes whose input and output streams are joined on the Mac.

Cancellation sends termination to the active process group. A proxy transfer terminates both process halves and waits for both exits.

Reads and refresh#

A local pane uses a filesystem event source and a 0.3-second debounce. A remote pane performs a quiet listing every ten seconds while the app is active and once when the app returns to the foreground. The quiet path preserves the cursor and selection.

Field topology is cached separately and changes after explicit probes or completed ZFS operations. The cache stores timestamps so the interface can show the age of each fact.

Local state#

The directory ~/Library/Application Support/palana/ contains field-cache.json, session.json, settings.json, favorites.json, columns.json, and operations.log. Session data stores pane locations and display state; it does not store directory entries.

macOS UserDefaults, the standard preference store, contains appearance, text scale, update-check choice, and some floating-panel positions.

Deleting field-cache.json removes remembered topology. Deleting session.json resets pane restoration, deleting settings or favorites resets those values, deleting columns.json resets hidden columns, and deleting the log removes local operation history.

Process and network lifecycle#

The application installs no daemon or launch agent. Closing the process stops pane refresh, closes SSH sessions, and terminates application-owned commands.

A packaged release checks the GitHub Releases API once at launch by default. The request reads the latest release tag, has an eight-second timeout, and does not download or install a release. Settings can disable the launch check.

Source and tests#

The project uses Swift 6, Swift Package Manager, strict concurrency checks, and a 90 percent line-coverage floor for PalanaCore. Source, tests, and the design record are in the GPL-3.0 repository.