Repository Public
1<div align="center">23<img src="docs/brand/logo.svg" alt="SP Term logo" width="560">45<br><br>67<img src="docs/brand/icon.png" alt="SP Term icon" width="112" height="112">89# SP Term1011**A native macOS terminal built for several displays, several windows and many panes — with SSH profiles, git context and an optional, bring-your-own-key assistant that never acts without you.**1213**Author: [Simon-Pierre Boucher](https://www.spboucher.ai)**14151617181920212223242526272829303132[](https://git.spboucher.ai/sp-term/commits)33[](https://git.spboucher.ai/sp-term/commits)34[](https://git.spboucher.ai/sp-term/insights)35[](https://git.spboucher.ai/sp-term)36[](https://git.spboucher.ai/sp-term/insights)37[](https://git.spboucher.ai/sp-term)38[](https://git.spboucher.ai/sp-term/branches)39[](https://git.spboucher.ai/sp-term/tags)40[](https://git.spboucher.ai/sp-term)414243444546474849505152535455565758596061</div>6263---6465## Table of contents6667- [Overview](#-overview)68- [Install](#-install)69- [Features](#-features)70- [Shortcuts](#-shortcuts)71- [Screenshots](#-screenshots)72- [Architecture](#-architecture)73- [Stack](#-stack)74- [Repository layout](#-repository-layout)75- [Build from source](#-build-from-source)76- [Configuration and data](#-configuration-and-data)77- [Security and privacy](#-security-and-privacy)78- [Testing](#-testing)79- [Benchmarks](#-benchmarks)80- [Release](#-release)81- [Brand](#-brand)82- [Limitations and known issues](#-limitations-and-known-issues)83- [Third-party components](#-third-party-components)84- [Author](#-author)85- [License](#-license)8687---8889## 🎯 Overview9091A native macOS terminal built for several displays, several windows and many panes — with SSH profiles,92git context and an optional, bring-your-own-key assistant that never acts without you.9394Swift 6 · SwiftUI + AppKit · macOS 14 or later · Apple Silicon and Intel (universal build).9596> Status of every feature — what is tested, what is only implemented, what is missing — is in97> [IMPLEMENTATION_STATUS.md](IMPLEMENTATION_STATUS.md). Test evidence: [TEST_REPORT.md](TEST_REPORT.md).98> Measurements: [BENCHMARKS.md](BENCHMARKS.md).99100| | |101|---|---|102| Version | 1.0.0 (1), built 2026-11-17 on macOS 27.0 / Xcode 27.2 |103| System | macOS 14 or later (the app relies on the Observation framework and on SwiftUI APIs introduced in macOS 14) |104| Distribution | outside the Mac App Store: Developer ID signature, hardened runtime, notarized and stapled (app and DMG) |105| Terminal engine | SwiftTerm 1.99.2 (MIT), integrated and pinned, not rewritten |106| Interface language | English only |107108SP Term is a standalone project of the [spboucher.ai](https://www.spboucher.ai) application family: it has no backend109and no sister repository. Documentation map:110111| Document | Content |112|---|---|113| [ARCHITECTURE.md](ARCHITECTURE.md) | modules, engine choice, PTY lifecycle, workspace model, displays, storage, concurrency |114| [IMPLEMENTATION_STATUS.md](IMPLEMENTATION_STATUS.md) | state of every feature: Tested / Implemented / Partial / Not done |115| [TEST_REPORT.md](TEST_REPORT.md) | suites, what each one proves, defects found, what was not tested |116| [BENCHMARKS.md](BENCHMARKS.md) | launch time, memory, throughput, latency, with their method |117| [RELEASE.md](RELEASE.md) | release procedure, verification, state of the 1.0.0 release |118| [docs/SECURITY.md](docs/SECURITY.md) | distribution model, untrusted output, paste, broadcast, SSH, assistant, data at rest |119| [docs/LICENSES.md](docs/LICENSES.md) | third-party components |120| [docs/RELEASE_NOTES.md](docs/RELEASE_NOTES.md) | release notes |121| [Assets/Brand/BRAND.md](Assets/Brand/BRAND.md) | mark, colour, typography, do / don't |122123---124125## 📦 Install126127Open the disk image from `dist/`, drag **SP Term** to **Applications**, launch it.128129The 1.0.0 disk image is `SPTerm-1.0.0.dmg` (8.3 MB), SHA-256130`9f07160dd2f174d19a4830e90d89656a1accc28f779650a8febeda2e24eb5a00`. `dist/` is a build output and is not versioned in131this repository.132133Run an isolated instance (own data folder, nothing restored):134135```sh136open "SP Term.app" --args -SPTermDataDir /tmp/spterm -SPTermFresh 1137```138139---140141## ✨ Features142143**Terminal.** Real PTY sessions (zsh, bash, fish or any installed shell), login shells, `TERM=xterm-256color`,144true colour, alternate screen, mouse reporting, bracketed paste, OSC 8 links, wide and combined characters,145bounded scrollback with regex search, drag-and-drop of files (paths are shell-escaped). Emulation is provided146by SwiftTerm (MIT).147148**Panes, tabs, windows.** Recursive horizontal/vertical splits, mouse and keyboard resizing, keyboard focus149navigation, temporary zoom, drag a pane by its header to rearrange or to another tab, move a pane or a tab to150its own window and merge windows back — processes keep running throughout.151152**Displays.** New windows open on the display you choose, windows can be sent to another display, layouts are153saved with their display and restored on the displays available; when a display is unplugged its windows come154back on screen. Presets: *Code + Tests + Logs*, *SSH Fleet*, *Agent Command Center*, *4 Panes*, *Dual Monitor*,155and 2/3/6/8-pane grids.156157**Workspaces.** The arrangement is restored at launch — layout, titles, session types and directories.158Processes are started fresh and SP Term says so; for sessions that survive a restart, use the built-in159tmux/zellij entries of the Command Palette (shown when those tools are installed).160161**SSH.** Hosts from `~/.ssh/config` and profiles you add, groups and favourites, ProxyJump, one-click sessions162or a grid of hosts. SP Term runs the system OpenSSH: keys stay in your agent, passwords are typed in the163terminal and never stored, host keys are always verified by OpenSSH.164165**Git context.** Branch, ahead/behind, staged/changed/untracked files, diffs and recent commits for the focused166session — strictly read-only.167168**SP Intelligence (optional, off by default).** Explain output, suggest or draft commands, review a diff, with169Anthropic, OpenAI or a local OpenAI-compatible server. You pick what text is attached, you see the exact payload170before it is sent, secrets are masked, a local-only mode refuses anything but this Mac, and no suggested command171runs without your confirmation (a typed phrase for destructive ones). Installed agent CLIs such as Claude Code can172be opened in their own panes, with their own authentication.173174**Also.** Command palette, customizable shortcuts, snippets with variables, quick terminal on a global hotkey,175session export with secret masking, themes (dark, light, high contrast), opacity and blur, focus and176presentation modes, per-task CPU/memory in the status bar, optional notifications.177178<details>179<summary><b>The nine layout presets</b> (<code>Packages/SPTermKit/Sources/WorkspaceKit/Presets.swift</code>)</summary>180181| Preset | Description |182|---|---|183| Code + Tests + Logs | a large editor pane with tests and logs stacked on the right |184| SSH Fleet | a grid with one pane per selected host |185| Agent Command Center | one supervisor shell and a column of agent panes, each with its own PTY |186| 4 Panes | a 2 × 2 grid of shells |187| Dual Monitor | one window per display: work on the primary, monitoring on the second |188| 2 Panes · 3 Panes · 6 Panes · 8 Panes | grids |189190</details>191192<details>193<summary><b>Feature status at a glance</b> (summary of <code>IMPLEMENTATION_STATUS.md</code>)</summary>194195Legend — **Tested**: covered by an automated test or an observed end-to-end check · **Implemented**: code in place and196compiling, behaviour not verified beyond what is stated · **Partial** / **Not done**: as described. Nothing is marked197Tested on the basis of "it should work".198199| Area | Tested | Implemented, not verified live | Partial / not done |200|---|---|---|---|201| Terminal core | real PTY, job control, signals, resize, no descriptor leak, engine conformance (15 tests, malformed corpus, 60 fuzz rounds), vim / less / top / python / ssh, scrollback and search | fish and other shells, selection and ⌘-click, drop gesture, Metal renderer (off by default) | ligatures follow the font (no switch); line spacing fixed by the engine; inline images not validated; nvim / htop / nano not verified |202| Windows, panes, displays | tabs, recursive splits (incl. 200 random operation sequences), keyboard resize and focus, zoom, detach / merge keeping the shell alive, presets, broadcast guards, native full screen | divider drag, tab reorder by drag | multi-display on **simulated displays** only; Spaces not specifically handled; pane count hint only |203| Sessions and workspaces | new / duplicate / rename / restart, layout autosave and restore, versioned storage with migration v1→v2 and corruption recovery, private mode, opt-in history | quit confirmation when busy | tmux / zellij: palette entries only; per-directory profiles not done |204| SSH, git, tools | `~/.ssh/config` parsing, command builder rules, hostile names refused, one live session to a LAN host, failure diagnosis and reconnect, read-only git, snippets, Finder "open with" | known_hosts in the dashboard, resource monitor, notifications, quick terminal, Finder Services entry | SFTP opens the system `sftp` in a tab; SSH latency not done; no automatic updates |205| SP Intelligence | preview before send, secret masking (28 cases), local-only mode, consent gate, 118 risk-analyzer cases, Keychain round trip — **with a mock transport: no request was ever sent to a real provider** | the five modes (answer quality not evaluated), agent CLIs in panes | streaming exists in the client; the panel uses non-streaming requests |206| Interface | command palette, themes (contrast ratios asserted), font 6–72 pt, shortcut model | opacity and blur, focus and presentation modes | VoiceOver not audited; no localization |207208</details>209210---211212## ⌨️ Shortcuts213214Defaults — all editable in Settings › Shortcuts.215216| | | | |217|---|---|---|---|218| New window | ⌘N | New tab | ⌘T |219| Split right / down | ⌘D / ⇧⌘D | Close pane / tab / window | ⌘W / ⌥⌘W / ⇧⌘W |220| Focus pane | ⌥⌘ arrows | Next / previous pane | ⌘] / ⌘[ |221| Resize pane | ⌃⌘ arrows | Zoom pane | ⇧⌘↩ |222| Next / previous tab | ⇧⌘] / ⇧⌘[ | Tab 1–9 | ⌘1 … ⌘9 |223| Command palette | ⇧⌘P | Find / next / previous | ⌘F / ⌘G / ⇧⌘G |224| Sidebar | ⌥⌘S | SSH hosts | ⇧⌘H |225| Snippets | ⇧⌘S | Git context | ⌥⌘G |226| SP Intelligence | ⇧⌘A | Broadcast input | ⌥⌘I |227| Move window to next display | ⌃⌥⌘→ | Save workspace | ⌘S |228| Text size | ⌘= / ⌘- / ⌘0 | Clear scrollback | ⌘K |229| Focus mode | ⌃⌘M | Full screen | ⌃⌘F |230| Restart session | ⇧⌘R | Quick terminal (when enabled) | ⌃⌥` |231232---233234## 🖼 Screenshots235236Evidence captured from the running app during testing (`docs/evidence/`, 8 files).237238| | |239|---|---|240| <img src="docs/evidence/01-first-launch.png" alt="First launch" width="400"><br>First launch | <img src="docs/evidence/02-three-panes.png" alt="Three panes" width="400"><br>Three panes |241| <img src="docs/evidence/03-vim.png" alt="vim in a pane" width="400"><br>vim in a pane | <img src="docs/evidence/04-palette.png" alt="Command palette" width="400"><br>Command palette |242| <img src="docs/evidence/05-dark.png" alt="Dark theme" width="400"><br>Dark theme | <img src="docs/evidence/06-sidebar-git.png" alt="Sidebar and git context" width="400"><br>Sidebar and git context |243| <img src="docs/evidence/07-assistant-off.png" alt="Assistant, off by default" width="400"><br>Assistant, off by default | <img src="docs/evidence/11-restored.png" alt="Restored workspace" width="400"><br>Restored workspace |244245---246247## 🏗 Architecture248249Swift 6 (strict concurrency), SwiftUI for the chrome, AppKit for windows, focus, menus, screens and the terminal250view. Full text: [ARCHITECTURE.md](ARCHITECTURE.md).251252```mermaid253flowchart TB254 APP["SP Term.app<br/>App/Sources/SPTerm — AppKit lifecycle, SwiftUI views<br/>AppModel · WorkspaceWindowController · panels"]255 subgraph KIT["Packages/SPTermKit — core"]256 PTY["PTYProcess<br/>forkpty → posix_spawn SETEXEC"]257 CORE["TerminalCore<br/>session = PTY + emulator view<br/>paste / broadcast guards"]258 WS["WorkspaceKit<br/>recursive split tree, tabs, windows, presets"]259 WM["WindowManager<br/>placement on displays, rescue, tiling"]260 STORE["SessionStore<br/>versioned JSON, migrations, recovery"]261 SET["SettingsModel<br/>preferences, key chords"]262 DS["DesignSystem<br/>themes, contrast maths"]263 end264 subgraph REMOTE["Packages/SPRemoteKit"]265 SSH["SSHKit<br/>ssh config parser, argv builder,<br/>known_hosts inspector, error classifier"]266 GIT["GitKit<br/>read-only git context"]267 PROC["SPProcess (internal)<br/>bounded, time-limited subprocesses"]268 end269 subgraph AI["Packages/SPIntelligence"]270 ASSIST["AIAssistant<br/>BYOK clients, Keychain store, secret redactor,<br/>risk analyzer, consent gate, network policy"]271 end272 ST["SwiftTerm 1.99.2<br/>VT/xterm parser + renderer (MIT, pinned)"]273 APP --> CORE & WS & WM & STORE & SET & DS & PTY274 APP --> SSH & GIT275 APP --> ASSIST276 CORE --> PTY & DS & SET277 CORE --> ST278 WM --> WS279 STORE --> WS & SET280 SET --> DS281 SSH --> PROC282 GIT --> PROC283 SSH -. "argv only" .-> OSSH["/usr/bin/ssh · /usr/bin/sftp"]284 GIT -. "allow-listed subcommands" .-> OGIT["/usr/bin/git"]285```286287Dependency rule: models (`WorkspaceKit`, `WindowManager`, `SettingsModel`, `DesignSystem`) import no UI framework288beyond CoreGraphics types and never touch `NSScreen`/`NSWindow`, which is what lets the multi-monitor logic be tested289with simulated displays. The app reads `NSScreen` in exactly one place (`ScreenReader`).290291### Engine choice292293| Option | Decision |294|---|---|295| Write a VT/xterm emulator from scratch | Rejected: a correct emulator (alternate screen, scroll regions, wide/combining text, mouse modes, bracketed paste, OSC 8/52, reflow…) is years of work; claiming one after a short build would be dishonest. |296| libghostty | Not used: no stable public embedding API at the time of writing; building it needs the Zig toolchain and a Metal toolchain component that was missing when it was evaluated. |297| **SwiftTerm 1.99.2** | **Chosen.** MIT licence, pure Swift, actively maintained, native `NSView`, thread-safe feed, built-in search, accessibility service, optional Metal renderer. Pinned to an exact version. |298299What is home-made on top of the engine: the PTY layer, the session object, launch planning, paste and broadcast300guards, the whole window/tab/pane/workspace system, persistence, SSH/Git/AI modules and the UI. `ConformanceTests`301pin the engine behaviours SP Term depends on (15 tests including malformed input and fuzzing).302303### PTY and process lifecycle304305```mermaid306sequenceDiagram307 autonumber308 participant S as TerminalSession (main actor)309 participant P as PTYProcess (one serial queue)310 participant C as Child process311 participant E as SwiftTerm engine312 S->>P: init(program, argv, env, cwd, size)313 P->>C: forkpty(termios IUTF8, winsize) — new session + controlling terminal on fds 0/1/2314 C->>C: posix_spawn(SETEXEC, CLOEXEC_DEFAULT, SETSIGDEF, SETSIGMASK, chdir)315 Note over C: the program replaces the child and inherits no descriptor of the app316 C-->>P: output on the master (O_NONBLOCK, read source)317 P-->>E: bytes fed straight from the PTY queue (thread-safe feed)318 S->>P: write(keys) — pending buffer, never blocks the UI319 S->>P: resize → TIOCSWINSZ (kernel raises SIGWINCH)320 C-->>P: exit → waitpid → drain remaining output321 P-->>S: onExit(status) — output always before exit322```323324- Only async-signal-safe calls happen between `forkpty` and exec; argv/envp/attributes are built before. On failure325 errno is written to a close-on-exec pipe and the launch throws.326- `terminate` = `SIGHUP` to the session, then `SIGKILL` after a grace period; `deinit` hangs up and reaps, so no327 zombie and no orphan survives.328- Foreground job detection uses `tcgetpgrp` on the master; cwd/CPU/memory come from `libproc`.329- An earlier design used `posix_spawn` alone with `POSIX_SPAWN_SETSID`. Tests showed that on macOS the slave is then330 *not* acquired as controlling terminal (zsh lost job control), hence `forkpty`.331332### Session, workspace model, displays333334- **Session** (`TerminalCore.TerminalSession`, `@MainActor @Observable`) owns one `SPTerminalView` (a335 `SwiftTerm.TerminalView` subclass) and one `PTYProcess`. Byte counters are sampled once per second on the main336 actor, so heavy output never floods the main thread with observation updates. A session is independent from337 windows: moving a pane only re-parents its view.338- **`UserInputScope`** marks key-event dispatch, pastes and drops; only bytes sent inside that scope are offered to339 broadcast input, so automatic terminal replies are never mirrored.340- **`LayoutNode`** is an n-ary split tree (value type): `.pane(id)` or `.split(axis, fractions, children)`, always341 normalized (no single-child split, no nested split of the same axis, fractions sum to 1). Operations: split,342 remove, swap, move-to-edge, divider resize, keyboard resize, equalize, geometric neighbour lookup, frames/dividers343 for a rectangle, grid builders.344- **`PlacementEngine`** guarantees that every frame it returns is reachable (title bar inside the visible area of an345 existing display). `resolve` restores a saved window (same display → kept; another resolution → rescaled; display346 id changed → matched by name + size; display gone → moved to the main display keeping proportions). `rescue` is347 called on `didChangeScreenParametersNotification` and moves only windows that became unreachable.348- **`AppModel`** (main actor, observable) owns sessions (`[PaneID: TerminalSession]`), window states and all349 operations.350351### Concurrency352353Swift 6 language mode with complete checking in every target. UI state is `@MainActor`. `PTYProcess` confines its354mutable state to one serial queue (`@unchecked Sendable`, documented). Git and AI calls are `async`; AI requests can355only be built from an `ApprovedPreview`, commands can only run from an `ApprovedCommand` — both types have no public356initializer.357358### Assistant consent flow359360```mermaid361sequenceDiagram362 autonumber363 participant U as User364 participant A as Assistant panel365 participant R as SecretRedactor366 participant G as ConsentGate367 participant P as Provider (BYOK)368 U->>A: question (+ optional "Selected text" or "Last 60 lines")369 A->>R: mask secrets370 R-->>A: ContextPreview — destination, model, byte count, masked text371 A-->>U: exact payload shown372 U->>A: Send373 A->>P: AIClient.send(ApprovedPreview)374 P-->>A: answer with suggested command (text only)375 U->>A: Review & Run376 A->>G: full command, target, host, directory, risk reasons377 G-->>U: confirmation (typed phrase when destructive, sudo, network transfer or multi-host)378 U->>G: confirm379 G-->>A: ApprovedCommand → typed into the session380```381382---383384## 🧱 Stack385386| Layer | Technology | Version | Role |387|---|---|---|---|388| Language | Swift | language mode 6.0, `SWIFT_STRICT_CONCURRENCY: complete` (`project.yml`) | everything |389| UI | SwiftUI + AppKit | system | chrome · windows, focus, menus, screens, terminal view |390| Project | XcodeGen (`project.yml`) → `SPTerm.xcodeproj` | `xcodeVersion: 27.2` | targets `SPTerm` and `SPTermTests` |391| Packages | SwiftPM, swift-tools 6.0, platform macOS 14 | 3 local packages | `SPTermKit` (7 libraries), `SPRemoteKit` (2 libraries + internal `SPProcess`), `SPIntelligence` (1 library) |392| Terminal engine | [SwiftTerm](https://github.com/migueldeicaza/SwiftTerm) | 1.99.2, exact pin, MIT | VT/xterm parser, buffer, renderer, search, accessibility |393| SSH | system OpenSSH (`/usr/bin/ssh`, `/usr/bin/sftp`, `/usr/bin/ssh-keygen`) | system | SP Term builds an argument vector, no crypto of its own |394| Git | system `/usr/bin/git` | system | read-only, allow-listed subcommands |395| Assistant | Anthropic, OpenAI, OpenAI-compatible HTTP APIs | bring your own key | optional, off by default |396| Secrets | macOS Keychain (service `ai.spboucher.spterm.ai`) | system | API keys only |397| Process probes | `libproc`, `tcgetpgrp` | system | cwd, CPU, memory, foreground job |398| Tests | Swift Testing (packages) · XCTest hosted in the app · System Events smoke script | Xcode 27.2, Swift 6.4.2 in the test report | 257 automated tests + 29 end-to-end checks |399400---401402## 🗂 Repository layout403404155 tracked files; 79 Swift files, 16 549 lines (tests included).405406```407App/408 Sources/SPTerm/ 19 files — application target409 App/ AppDelegate, Actions, SearchSupport410 Model/ AppModel, WindowState411 Panels/ AssistantPanel, GitPanel, HostsAndSnippets412 Views/ WindowRootView, PaneViews, SidebarView, CommandPaletteView, SettingsView, Sheets, Styling, SPColor413 Windows/ WorkspaceWindowController, QuickTerminalController, Notifier414 Tests/SPTermTests/ hosted integration tests (WorkspaceTests, SafetyTests, PerformanceTests, Support)415Packages/416 SPTermKit/ PTYProcess · TerminalCore · WorkspaceKit · WindowManager · SessionStore · SettingsModel · DesignSystem (+ 6 test targets)417 SPRemoteKit/ SSHKit · GitKit · SPProcess (+ 2 test targets)418 SPIntelligence/ AIAssistant (+ 1 test target)419Assets/Brand/ icon sources (SVG), three concepts, PNG exports 1024–16 px, brand guide, render.sh420Resources/ Info.plist, SPTerm.entitlements, Assets.xcassets (AppIcon, AccentColor)421Scripts/ build, kit, smoke, drive, bench, release, notarize, window-shot422docs/ SECURITY.md, LICENSES.md, RELEASE_NOTES.md, evidence/ (8 screenshots), brand/ (logo, icon)423ARCHITECTURE.md · IMPLEMENTATION_STATUS.md · TEST_REPORT.md · BENCHMARKS.md · RELEASE.md424project.yml XcodeGen definition425```426427---428429## 🛠 Build from source430431You need Xcode 27 and [XcodeGen](https://github.com/yonaskolb/XcodeGen).432433```sh434Scripts/build.sh generate # creates SPTerm.xcodeproj from project.yml435Scripts/build.sh run # debug build + launch436Scripts/build.sh kits # unit tests of the three Swift packages437Scripts/build.sh test # integration tests hosted in the app438```439440| Script | Purpose |441|---|---|442| `Scripts/build.sh` | build helper: `generate`, `debug`, `release`, `run`, `kits`, `test`, `app-path` (filters the Xcode 27.2 plug-in noise that is irrelevant to a macOS app) |443| `Scripts/kit.sh` | builds / tests one local package and prints only the useful diagnostics: `Scripts/kit.sh test SPTermKit --filter Name` |444| `Scripts/smoke.sh` | end-to-end smoke test of the real application, driven through System Events; every check is observed outside the app |445| `Scripts/drive.sh` | sends keystrokes to the running app through System Events (used by the smoke tests) |446| `Scripts/bench.sh` | launch time (5 launches after one warm-up) and memory of a built app |447| `Scripts/release.sh` | universal Release build, Developer ID signature, hardened runtime, verification → `dist/SP Term.app` |448| `Scripts/notarize.sh` | notarizes and staples the app, then builds, signs, notarizes and staples the DMG and writes its SHA-256 |449| `Scripts/window-shot.swift` | captures the frontmost window of a named app to a PNG |450| `Assets/Brand/render.sh` | regenerates every icon PNG and the `AppIcon.appiconset` (needs `rsvg-convert`) |451452---453454## ⚙️ Configuration and data455456| Setting | Value | Where |457|---|---|---|458| Bundle identifier | `ai.spboucher.spterm` (tests: `ai.spboucher.spterm.tests`) | `project.yml` |459| Team | `3YM54G49SN` | `project.yml` |460| Version | `MARKETING_VERSION` 1.0.0 · `CURRENT_PROJECT_VERSION` 1 | `project.yml` |461| Deployment target | macOS 14.0 | `project.yml` |462| Architectures | Debug: `arm64` · Release: `arm64 x86_64` | `project.yml` |463| Category | `public.app-category.developer-tools` | `Resources/Info.plist` |464| Finder integration | opens folders (`public.folder`, alternate handler); Services entry "New SP Term Window Here" | `Resources/Info.plist` |465| Launch arguments | `-SPTermDataDir <dir>` (own data folder) · `-SPTermFresh 1` (nothing restored) | `App/Sources/SPTerm/App/AppDelegate.swift` |466| Notarization profile | `NOTARY_PROFILE` environment variable, default `MacLustr-Notarize` (a `notarytool` keychain profile, referred to by name only) | `Scripts/notarize.sh` |467468Data directory `~/Library/Application Support/SP Term/` (0700), files 0600, each a versioned envelope469`{"schemaVersion": N, "payload": …}` written atomically (temp file + rename):470471| File | Content |472|---|---|473| `settings.json` | preferences and shortcut overrides |474| `last-session.json` | layout autosaved while running (schema 2; schema 1 is migrated) |475| `workspaces.json` | named workspaces |476| `snippets.json` | command snippets |477| `hosts.json` | SSH profiles added in the app (no secrets) |478| `ai-providers.json` | provider label, URL, model — never the key |479| `history.jsonl` | opt-in command history (snippets / assistant / broadcast only) |480481An unreadable or newer-schema file is renamed `*.unreadable-<timestamp>` and defaults are used; a damaged layout is482repaired tab by tab. API keys are in the Keychain. Terminal output is never written to disk unless the user exports a483session.484485---486487## 🛡 Security and privacy488489In short (details: [docs/SECURITY.md](docs/SECURITY.md)):490491- Distributed outside the Mac App Store with a Developer ID signature and the hardened runtime; **not sandboxed**492 (a terminal must run arbitrary programs with your permissions). One entitlement only: Apple Events automation493 for programs you run.494- Nothing about your sessions leaves the Mac unless you press *Send* in the assistant after reviewing the payload.495- No terminal output is written to disk unless you export it. Private mode disables layout saving, history and notifications.496- Pastes with several lines ask first; pastes containing escape sequences always ask. Programs cannot read the497 clipboard (OSC 52) unless you allow it, and writing it asks by default.498- Broadcast input is off at every launch, needs a confirmation, shows a permanent banner and holds destructive lines.499- API keys live in the macOS Keychain. SSH keys and passwords are never read, copied or stored.500501| Mechanism | State |502|---|---|503| Hardened runtime | On. No `allow-jit`, no `allow-unsigned-executable-memory`, no `disable-library-validation`, no `get-task-allow`, no debugger entitlement |504| Entitlements | Exactly one: `com.apple.security.automation.apple-events`, so that programs the user runs (e.g. `osascript`) can send Apple Events — each target still requires the user's consent in a system prompt |505| TCC (privacy prompts) | Not bypassed. When a program in a session touches Desktop / Documents / Downloads, the local network, etc., macOS asks on behalf of SP Term; the usage strings explain that a program in a session triggered it |506| Privileges | The app never asks for root, installs no helper, no launch agent, no kernel / system extension, and never touches SIP or Gatekeeper settings |507| Child processes | Inherit no file descriptor of the app (tested), get default signal handling and a cleaned environment (`DYLD_*`, `XPC_*` and debugging variables are stripped) |508509<details>510<summary><b>Untrusted terminal output</b></summary>511512- **Escape sequences**: parsed by the engine; malformed / unknown sequences are ignored (conformance + fuzz tests).513- **Window title** (OSC 0/2): control characters removed, length capped.514- **Clipboard** (OSC 52): *write* is `ask` by default (the text and the requesting program are shown), *read* is `deny` by default. Both are settings.515- **Links** (OSC 8 and detected URLs): `http`, `https`, `mailto` open directly on ⌘-click; `file:` is only revealed in Finder, never launched; `javascript:` / `data:` are blocked; any other scheme asks first.516- **Notifications**: only process name and duration are shown, never terminal text.517518</details>519520<details>521<summary><b>Paste, broadcast, SSH</b></summary>522523- Several lines → confirmation with a preview where control characters are made visible (configurable). Text containing524 escape sequences or the bracketed-paste terminator → always asks, and the default action pastes a sanitized version.525 Sanitized pastes never end with a line break, so nothing runs before the user presses Return.526- Dropped files insert shell-escaped paths (round-trip tested against a real shell with 17 hostile names).527- Broadcast: off at every launch (never persisted); enabling it shows which sessions will receive input and requires a528 confirmation; a full-width banner and coloured pane borders stay visible; lines that look destructive or use `sudo`529 are held for the other panes until the user types the confirmation phrase. Limit: the pane being typed in is a normal530 terminal — the line runs there as typed; the guard protects the fan-out.531- SSH: every field is validated against an allow-list (no leading `-`, no whitespace, no shell metacharacters); the532 builder never emits `StrictHostKeyChecking`, `UserKnownHostsFile`, `BatchMode` or password options; extra `-o`533 options go through an allow-list. Host key verification is OpenSSH's interactive prompt in the terminal; SP Term534 never answers it. Opening a host runs `ssh` only — no command is sent to remote hosts.535536</details>537538<details>539<summary><b>Assistant guarantees, enforced by types and tests</b></summary>5405411. No request without a preview: `AIClient.send` only accepts an `ApprovedPreview`, which can only be made from a `ContextPreview` the user has seen.5422. The preview is the exact payload (destination, model, byte count, masked text). Secrets are always masked first.5433. Terminal text is attached only when the user selects *Selected text* or *Last 60 lines*.5444. Local-only mode refuses every non-loopback destination before any I/O; plain HTTP to a remote host is refused.5455. API keys are stored in the Keychain, sent in a header, and wrapped in a type whose description is redacted.5466. Suggested commands are text. *Insert* types them without Return. *Review & Run* goes through the consent gate: full command, target, host, directory, risk reasons; destructive, sudo, network-transfer and multi-host commands need a typed phrase.547548</details>549550**Not stored**: terminal output, keystrokes typed at prompts, API keys, SSH credentials. There is no plugin system551and no scripting bridge: SP Term loads no third-party code and exposes no automation interface that could run commands.552553**Known limits**: the risk analyzer and the secret redactor are pattern based — `safe` means "no known risky pattern",554and an unusual secret format can pass unmasked (the preview exists so the user can check). A program running in a555session has the user's full permissions; SP Term does not confine it. Exported session files contain whatever was on556screen (masked by default); they are created 0600.557558---559560## ✅ Testing561562Report: [TEST_REPORT.md](TEST_REPORT.md) — 2026-11-17, MacBook Pro Apple M5 Max, macOS 27.0, Xcode 27.2, Swift 6.4.2,563one display. All numbers are copied from the output of the listed commands.564565| Suite | Command | Result |566|---|---|---|567| SPTermKit (core) | `Scripts/kit.sh test SPTermKit` | **98 tests passed** (PTY 17, terminal core 34, workspace 19, placement 13, storage 10, themes 5) |568| SPRemoteKit | `Scripts/kit.sh test SPRemoteKit` | **65 tests passed** (SSH 39, git 26) |569| SPIntelligence | `Scripts/kit.sh test SPIntelligence` | **56 tests passed** (parameterized: 118 risk cases, 28 redaction cases, 27 loopback hosts) |570| App integration (hosted in the app) | `Scripts/build.sh test` | **38 tests passed** (workspace 8, displays 6, broadcast 3, paste/clipboard 5, assistant 6, remote/registry 7, performance 3) |571| End-to-end on the running app | `Scripts/smoke.sh` | 29 checks; six runs, from 23 to **29 passed**; last run on the signed Release build: 29/29 |572| **Total automated tests** | | **257** unit / integration tests, 0 failing at the last run |573574<details>575<summary><b>What each suite proves</b></summary>576577- **PTY** (real processes) — output and exit code; a real controlling terminal; `SIGWINCH` delivered with the new578 size; Ctrl+C interrupts the foreground job and not the shell; Ctrl+Z suspends and job control works in zsh; Ctrl+D is579 end-of-file; Unicode round trip (accents, CJK, ZWJ emoji); terminate ends and reaps the session; the child inherits no580 descriptor of the app; 200 000 lines are delivered completely before the exit is reported; 300 KB of input is581 accepted without blocking.582- **Engine conformance** (SwiftTerm 1.99.2 headless) — cursor addressing, erase / insert / delete line, SGR including583 256 and true colour, alternate screen, scrolling region, bracketed paste, mouse and focus-report modes, OSC 0/2/8/52,584 wide / combining / ZWJ / flag sequences, wrap and reflow, bounded scrollback, a corpus of malformed sequences and585 invalid UTF-8, 60 fuzz rounds of 4 000 random chunks with random resizes. These are checks of the integrated engine,586 not of an emulator written for SP Term.587- **Layout and workspace model** — recursive splits, exact tiling without overlap for 2/3/4/6/8 panes, divider and588 keyboard resizing with minimum sizes, geometric focus navigation, Codable round trip, **200 random operation589 sequences** preserving all invariants.590- **Multi-display placement (simulated monitors)** — **500 random configuration changes** (1–3 displays, a projector,591 random frames) never leave a window unreachable; hosted versions run against real `NSWindow` objects.592- **Storage** — 0600 / 0700 permissions, corrupt file set aside not deleted, newer schema refused and preserved,593 migration from schema 1, history opt-in, private mode, masking.594- **SSH and git** — config parsing fixtures, every command-builder security rule, hostile host names refused,595 read-only git on temporary repositories, the allow-list refusing mutating subcommands. One real session to a LAN host596 was opened by hand through the palette.597- **Safety (hosted)** — broadcast guards, paste policy including escape injection, OSC 52, and the assistant: no598 request without preview and explicit send (counted on a mock transport), masked payload, the API key never in the599 body or in descriptions, execution only through the consent gate.600601</details>602603**End-to-end.** XCUITest cannot be used on this toolchain (Xcode 27.2 on macOS 27.0 times out "enabling automation604mode"), so `Scripts/smoke.sh` drives the real app with System Events and observes results from outside (files written605by commands typed into panes, window counts, the saved layout).606607<details>608<summary><b>Defects found by testing and fixed</b></summary>609610| Found by | Defect | Fix |611|---|---|---|612| PTY tests (Ctrl+Z) | zsh had no controlling terminal: opening the slave after `POSIX_SPAWN_SETSID` does not acquire it on macOS | launch through `forkpty` + exec-mode `posix_spawn` |613| PTY tests | exit of very short programs could be missed (process source registered after the exit) | registration handler + end-of-file triggered polling |614| PTY tests (crash, signal 5) | releasing a suspended dispatch write source | the source is cancelled and recreated instead of suspended |615| Screenshot after a split | keyboard stayed in the previous pane while the new one was highlighted | the terminal container claims first responder when its view enters the window |616| Screenshot of an ended SSH pane | status bar showed "Exited" twice and a local directory for a remote session | status bar corrected |617| Benchmark | reading the whole 200 000-line buffer in a polling loop stalled the parser (a flaw of the test, 0.4 MB/s) | completion observed through a sentinel file and the visible rows |618| Theme tests | secondary text below 4.5:1 on the two light themes | darker secondary text on light themes |619620</details>621622<details>623<summary><b>Not tested</b></summary>624625- More than one physical display (only simulated displays were available); Spaces.626- VoiceOver; the app was not run with VoiceOver on.627- Mouse gestures: divider dragging, tab and pane drag & drop, ⌘-click on links, text selection.628- Quick terminal hotkey, notifications, the Finder Services entry, the session export save panel.629- Real AI providers (no request was sent), real agent CLIs inside panes.630- fish, nvim, htop, nano (first three not installed on the reference machine); tmux attach entry.631- Intel execution: the x86_64 slice is built and signed but was not run.632- macOS 14 and 15: the deployment target is 14.0 but the app only ran on macOS 27.0.633- Long-duration use, sleep / wake, very large numbers of sessions.634635</details>636637---638639## ⚡ Benchmarks640641Measured on 2026-11-17 on one machine (MacBook Pro, Apple M5 Max, 48 GB RAM, macOS 27.0), single runs unless a spread642is given: orders of magnitude, not guarantees. Renderer under test: the engine's default **CoreGraphics** renderer; the643Metal renderer was **not measured** and SP Term makes no claim of GPU acceleration. Full text: [BENCHMARKS.md](BENCHMARKS.md).644645| Measure | Result | Method |646|---|---|---|647| Launch → first window on screen | **250–259 ms** (median 255, 5 launches) | `Scripts/bench.sh`, signed universal Release build |648| Memory, 1 pane, idle | **57 MB** physical footprint (100 MB resident) | `footprint`, `ps` |649| Memory, 8 panes (8 shells), idle | **64 MB** footprint (107 MB resident) | preset `grid8` |650| CPU, 8 idle panes | 1.2 % | `ps` |651| Bundle size / DMG size | 23 MB / 8.3 MB | universal binary |652| Large stdout: `cat` of 51 MB / 400 000 lines | **0.51 s — ≈ 100 MB/s** (Debug: 13.5 s) | in-process, window not on screen: excludes drawing |653| Echo latency: key → PTY → echo → screen buffer | **median 0.26 ms**, p95 0.36 ms (200 keys) | stops at the screen buffer |654| 300 view resizes while a loop prints | **0.32 s** | `setFrameSize` × 300, then `stty size` |655| Memory with a full 200 000-line scrollback | ≈ 365 MB more | `task_info` before / after |656| Backward search in 200 000 lines | **2.5 s** | `findPrevious` |657658Reading these numbers: **typing latency to glass was not measured** (the 0.26 ms figure stops at the screen buffer);659throughput is without drawing; a long scrollback is memory-hungry (roughly 1.8 KB per line at this width — the default660is 20 000 lines, the setting goes up to 1 000 000); searching a 200 000-line scrollback runs on the main thread; Debug661builds are 10–25 times slower on the parsing paths, always measure Release.662663---664665## 🚀 Release666667Procedure: [RELEASE.md](RELEASE.md). Prerequisites are checked, never created, by the scripts: Xcode 27, XcodeGen, a668**Developer ID Application** certificate in the login keychain, and a `notarytool` keychain profile referred to by669name only.670671```sh672Scripts/build.sh kits # 1. unit tests of the three packages673Scripts/build.sh test # 2. integration tests hosted in the app674Scripts/release.sh # 3. universal Release build, Developer ID signature, hardened runtime, verification675Scripts/smoke.sh "dist/SP Term.app" # 4. end-to-end check of the signed build676Scripts/notarize.sh # 5. notarize + staple the app, build/sign/notarize/staple the DMG, SHA-256677```678679Versioning: `MARKETING_VERSION` and `CURRENT_PROJECT_VERSION` live in `project.yml`. Bump them, add a section to680`docs/RELEASE_NOTES.md` and to the changelog of `RELEASE.md`, then regenerate the project (`Scripts/build.sh generate`).681682Verification of a finished release:683684```sh685codesign --verify --deep --strict --verbose=2 "dist/SP Term.app"686codesign -d --entitlements - --xml "dist/SP Term.app" | plutil -p -687xcrun stapler validate "dist/SP Term.app"688xcrun stapler validate dist/SPTerm-<version>.dmg689spctl --assess --type execute --verbose=2 "dist/SP Term.app"690spctl --assess --type open --context context:primary-signature --verbose=2 dist/SPTerm-<version>.dmg691shasum -a 256 -c dist/SPTerm-<version>.dmg.sha256692```693694| State of 1.0.0 (1) | Result (from `RELEASE.md`) |695|---|---|696| Tag | `v1.0.0` |697| `dist/SP Term.app` | universal (`x86_64 arm64`), Developer ID Application: Simon-Pierre Boucher (3YM54G49SN), hardened runtime, one entitlement |698| Notarization | app and DMG **Accepted** by Apple |699| Stapling | app and DMG validated with `stapler validate` |700| Gatekeeper | `spctl`: accepted, `source=Notarized Developer ID` (app, DMG, app inside the mounted DMG) |701| `dist/SPTerm-1.0.0.dmg` | 8 287 990 bytes, SHA-256 `9f07160dd2f174d19a4830e90d89656a1accc28f779650a8febeda2e24eb5a00` |702| Published by the scripts | No — nothing is uploaded except to Apple's notary service; the DMG stays in `dist/` |703704**Updates.** No automatic update mechanism is enabled: there is no feed URL. Sparkle (EdDSA-signed appcasts served705over HTTPS, private key kept off the repository) is the intended mechanism once a distribution URL exists.706707---708709## 🎨 Brand710711The mark is an **SP monogram drawn as a monoline**, with a **glowing block cursor** parked under the bowl of the P:712read left to right it says `SP▮`. Guide: [Assets/Brand/BRAND.md](Assets/Brand/BRAND.md).713714| File | Purpose |715|---|---|716| `Assets/Brand/SPTermIcon.svg` | master drawing, used for 64 px and above |717| `Assets/Brand/SPTermIcon-small.svg` | simplified drawing, used for the 16 and 32 px renders |718| `Assets/Brand/SPTermGlyph.svg` | single-colour template glyph (menus, toolbar, in-app) |719| `Assets/Brand/Concepts/` | the three explored concepts (A is the winner, chosen on small-size legibility) |720| `Assets/Brand/Exports/` | RGBA exports 1024–16 px |721| `docs/brand/` | README lockup (`logo.svg`) and 256 px icon (`icon.png`) |722723Brand gradient: `#22D3EE → #4C8DFF → #9B6CFF` (cyan at the bottom-left, violet at the top-right) on graphite surfaces724(`#0D0F13` … `#323844`). UI font SF Pro, terminal font SF Mono (default 13 pt). The wordmark is written **SP Term**.725726```bash727Assets/Brand/render.sh # needs rsvg-convert (brew install librsvg)728```729730---731732## 🚧 Limitations and known issues733734See [IMPLEMENTATION_STATUS.md](IMPLEMENTATION_STATUS.md) for the full list.735736- Restored sessions are new processes; persistence across restarts relies on tmux/zellij.737- Ligatures depend on the chosen font; line spacing is not adjustable; inline images depend on the engine's738 default support and are not validated.739- Metal rendering is an experimental switch, not the measured default.740- Automatic updates are not included (no update feed is configured).741- Multi-display behaviour is covered by simulated-display tests; it was exercised on real hardware with one display only.742- The Intel slice of the universal binary was built and signed but never executed; macOS 14 and 15 were not run.743- No request was ever sent to a real AI provider: the assistant is tested with a mock transport.744- The interface is in English only; VoiceOver was not audited.745746Known issues:747748- The 16 px icon is soft (strokes are not pixel-hinted).749- During one automated run a second window opened without a traceable cause; it could not be reproduced in two replays750 of the same keystrokes (other automation was active on the machine at the time).751- System Events key injection is unreliable when keystrokes are sent faster than about 1 per second on the reference752 machine; the smoke test therefore runs slowly and can report a spurious failure.753- A 200 000-line scrollback costs several hundred MB of memory; the default is 20 000.754- Exported text keeps soft-wrapped lines as separate lines.755756---757758## 📚 Third-party components759760| Component | Version | Licence | Use |761|---|---|---|---|762| [SwiftTerm](https://github.com/migueldeicaza/SwiftTerm) | 1.99.2 (exact pin) | MIT — © 2019-2026 Miguel de Icaza, xterm.js authors, SourceLair, Christopher Jeffrey | terminal emulation engine (parser, buffer, renderer, search, accessibility) |763| swift-argument-parser | 1.8.2 (transitive, build tools of SwiftTerm only) | Apache-2.0 | not linked into the app |764765SwiftTerm is used unmodified through Swift Package Manager. SP Term subclasses its `TerminalView` (`SPTerminalView`)766to add guarded paste, file drops and a host context menu; no source of the engine is patched. The MIT notice is shown767in the About panel and reproduced in the distribution. System tools executed at the user's request, not redistributed:768`/usr/bin/ssh`, `/usr/bin/sftp`, `/usr/bin/ssh-keygen`, `/usr/bin/git`, the user's shells, and optional769`tmux` / `zellij` / agent CLIs. All colour themes, the icon and the brand assets are original to SP Term.770Details: [docs/LICENSES.md](docs/LICENSES.md).771772---773774## 👤 Author775776<div align="center">777778<img src="docs/brand/icon.png" width="64" height="64" alt="">779780**Simon-Pierre Boucher** — design, development, operations781782[www.spboucher.ai](https://www.spboucher.ai) · [git.spboucher.ai](https://git.spboucher.ai) · contact@spboucher.ai783784</div>785786## 📄 License787788© 2026 Simon-Pierre Boucher. All rights reserved.789Terminal emulation by SwiftTerm, © Miguel de Icaza and contributors (MIT).790