SPB Git

Repository Public

README.md 47.9 KB

SP Term logo



SP Term icon

# SP Term

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.

Author: Simon-Pierre Boucher

version platform distribution binary licence author

Swift SwiftUI Xcode XcodeGen SwiftPM SwiftTerm OpenSSH git Keychain

commits last commit activity language languages size branches tags clones

Swift files Swift lines modules automated tests package tests hosted tests smoke checks presets themes

bundle id signature notarization hardened runtime sandbox entitlements deployment target launch


# Table of contents


# 🎯 Overview

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.

Swift 6 · SwiftUI + AppKit · macOS 14 or later · Apple Silicon and Intel (universal build).

Status of every feature — what is tested, what is only implemented, what is missing — is in IMPLEMENTATION_STATUS.md. Test evidence: TEST_REPORT.md. Measurements: BENCHMARKS.md.

Version 1.0.0 (1), built 2026-11-17 on macOS 27.0 / Xcode 27.2
System macOS 14 or later (the app relies on the Observation framework and on SwiftUI APIs introduced in macOS 14)
Distribution outside the Mac App Store: Developer ID signature, hardened runtime, notarized and stapled (app and DMG)
Terminal engine SwiftTerm 1.99.2 (MIT), integrated and pinned, not rewritten
Interface language English only

SP Term is a standalone project of the spboucher.ai application family: it has no backend and no sister repository. Documentation map:

Document Content
ARCHITECTURE.md modules, engine choice, PTY lifecycle, workspace model, displays, storage, concurrency
IMPLEMENTATION_STATUS.md state of every feature: Tested / Implemented / Partial / Not done
TEST_REPORT.md suites, what each one proves, defects found, what was not tested
BENCHMARKS.md launch time, memory, throughput, latency, with their method
RELEASE.md release procedure, verification, state of the 1.0.0 release
docs/SECURITY.md distribution model, untrusted output, paste, broadcast, SSH, assistant, data at rest
docs/LICENSES.md third-party components
docs/RELEASE_NOTES.md release notes
Assets/Brand/BRAND.md mark, colour, typography, do / don't

# 📦 Install

Open the disk image from dist/, drag SP Term to Applications, launch it.

The 1.0.0 disk image is SPTerm-1.0.0.dmg (8.3 MB), SHA-256 9f07160dd2f174d19a4830e90d89656a1accc28f779650a8febeda2e24eb5a00. dist/ is a build output and is not versioned in this repository.

Run an isolated instance (own data folder, nothing restored):

sh
open "SP Term.app" --args -SPTermDataDir /tmp/spterm -SPTermFresh 1

# ✨ Features

Terminal. Real PTY sessions (zsh, bash, fish or any installed shell), login shells, TERM=xterm-256color, true colour, alternate screen, mouse reporting, bracketed paste, OSC 8 links, wide and combined characters, bounded scrollback with regex search, drag-and-drop of files (paths are shell-escaped). Emulation is provided by SwiftTerm (MIT).

Panes, tabs, windows. Recursive horizontal/vertical splits, mouse and keyboard resizing, keyboard focus navigation, temporary zoom, drag a pane by its header to rearrange or to another tab, move a pane or a tab to its own window and merge windows back — processes keep running throughout.

Displays. New windows open on the display you choose, windows can be sent to another display, layouts are saved with their display and restored on the displays available; when a display is unplugged its windows come back on screen. Presets: Code + Tests + Logs, SSH Fleet, Agent Command Center, 4 Panes, Dual Monitor, and 2/3/6/8-pane grids.

Workspaces. The arrangement is restored at launch — layout, titles, session types and directories. Processes are started fresh and SP Term says so; for sessions that survive a restart, use the built-in tmux/zellij entries of the Command Palette (shown when those tools are installed).

SSH. Hosts from ~/.ssh/config and profiles you add, groups and favourites, ProxyJump, one-click sessions or a grid of hosts. SP Term runs the system OpenSSH: keys stay in your agent, passwords are typed in the terminal and never stored, host keys are always verified by OpenSSH.

Git context. Branch, ahead/behind, staged/changed/untracked files, diffs and recent commits for the focused session — strictly read-only.

SP Intelligence (optional, off by default). Explain output, suggest or draft commands, review a diff, with Anthropic, OpenAI or a local OpenAI-compatible server. You pick what text is attached, you see the exact payload before it is sent, secrets are masked, a local-only mode refuses anything but this Mac, and no suggested command runs without your confirmation (a typed phrase for destructive ones). Installed agent CLIs such as Claude Code can be opened in their own panes, with their own authentication.

Also. Command palette, customizable shortcuts, snippets with variables, quick terminal on a global hotkey, session export with secret masking, themes (dark, light, high contrast), opacity and blur, focus and presentation modes, per-task CPU/memory in the status bar, optional notifications.

The nine layout presets (Packages/SPTermKit/Sources/WorkspaceKit/Presets.swift)
Preset Description
Code + Tests + Logs a large editor pane with tests and logs stacked on the right
SSH Fleet a grid with one pane per selected host
Agent Command Center one supervisor shell and a column of agent panes, each with its own PTY
4 Panes a 2 × 2 grid of shells
Dual Monitor one window per display: work on the primary, monitoring on the second
2 Panes · 3 Panes · 6 Panes · 8 Panes grids
Feature status at a glance (summary of IMPLEMENTATION_STATUS.md)

Legend — Tested: covered by an automated test or an observed end-to-end check · Implemented: code in place and compiling, behaviour not verified beyond what is stated · Partial / Not done: as described. Nothing is marked Tested on the basis of "it should work".

Area Tested Implemented, not verified live Partial / not done
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
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
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
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
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
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

# ⌨️ Shortcuts

Defaults — all editable in Settings › Shortcuts.

New window ⌘N New tab ⌘T
Split right / down ⌘D / ⇧⌘D Close pane / tab / window ⌘W / ⌥⌘W / ⇧⌘W
Focus pane ⌥⌘ arrows Next / previous pane ⌘] / ⌘[
Resize pane ⌃⌘ arrows Zoom pane ⇧⌘↩
Next / previous tab ⇧⌘] / ⇧⌘[ Tab 1–9 ⌘1 … ⌘9
Command palette ⇧⌘P Find / next / previous ⌘F / ⌘G / ⇧⌘G
Sidebar ⌥⌘S SSH hosts ⇧⌘H
Snippets ⇧⌘S Git context ⌥⌘G
SP Intelligence ⇧⌘A Broadcast input ⌥⌘I
Move window to next display ⌃⌥⌘→ Save workspace ⌘S
Text size ⌘= / ⌘- / ⌘0 Clear scrollback ⌘K
Focus mode ⌃⌘M Full screen ⌃⌘F
Restart session ⇧⌘R Quick terminal (when enabled) ⌃⌥`

# 🖼 Screenshots

Evidence captured from the running app during testing (docs/evidence/, 8 files).

First launch
First launch
Three panes
Three panes
vim in a pane
vim in a pane
Command palette
Command palette
Dark theme
Dark theme
Sidebar and git context
Sidebar and git context
Assistant, off by default
Assistant, off by default
Restored workspace
Restored workspace

# 🏗 Architecture

Swift 6 (strict concurrency), SwiftUI for the chrome, AppKit for windows, focus, menus, screens and the terminal view. Full text: ARCHITECTURE.md.

flowchart TB
  APP["SP Term.app<br/>App/Sources/SPTerm — AppKit lifecycle, SwiftUI views<br/>AppModel · WorkspaceWindowController · panels"]
  subgraph KIT["Packages/SPTermKit — core"]
    PTY["PTYProcess<br/>forkpty → posix_spawn SETEXEC"]
    CORE["TerminalCore<br/>session = PTY + emulator view<br/>paste / broadcast guards"]
    WS["WorkspaceKit<br/>recursive split tree, tabs, windows, presets"]
    WM["WindowManager<br/>placement on displays, rescue, tiling"]
    STORE["SessionStore<br/>versioned JSON, migrations, recovery"]
    SET["SettingsModel<br/>preferences, key chords"]
    DS["DesignSystem<br/>themes, contrast maths"]
  end
  subgraph REMOTE["Packages/SPRemoteKit"]
    SSH["SSHKit<br/>ssh config parser, argv builder,<br/>known_hosts inspector, error classifier"]
    GIT["GitKit<br/>read-only git context"]
    PROC["SPProcess (internal)<br/>bounded, time-limited subprocesses"]
  end
  subgraph AI["Packages/SPIntelligence"]
    ASSIST["AIAssistant<br/>BYOK clients, Keychain store, secret redactor,<br/>risk analyzer, consent gate, network policy"]
  end
  ST["SwiftTerm 1.99.2<br/>VT/xterm parser + renderer (MIT, pinned)"]
  APP --> CORE & WS & WM & STORE & SET & DS & PTY
  APP --> SSH & GIT
  APP --> ASSIST
  CORE --> PTY & DS & SET
  CORE --> ST
  WM --> WS
  STORE --> WS & SET
  SET --> DS
  SSH --> PROC
  GIT --> PROC
  SSH -. "argv only" .-> OSSH["/usr/bin/ssh · /usr/bin/sftp"]
  GIT -. "allow-listed subcommands" .-> OGIT["/usr/bin/git"]

Dependency rule: models (WorkspaceKit, WindowManager, SettingsModel, DesignSystem) import no UI framework beyond CoreGraphics types and never touch NSScreen/NSWindow, which is what lets the multi-monitor logic be tested with simulated displays. The app reads NSScreen in exactly one place (ScreenReader).

# Engine choice

Option Decision
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.
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.
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.

What is home-made on top of the engine: the PTY layer, the session object, launch planning, paste and broadcast guards, the whole window/tab/pane/workspace system, persistence, SSH/Git/AI modules and the UI. ConformanceTests pin the engine behaviours SP Term depends on (15 tests including malformed input and fuzzing).

# PTY and process lifecycle

sequenceDiagram
  autonumber
  participant S as TerminalSession (main actor)
  participant P as PTYProcess (one serial queue)
  participant C as Child process
  participant E as SwiftTerm engine
  S->>P: init(program, argv, env, cwd, size)
  P->>C: forkpty(termios IUTF8, winsize) — new session + controlling terminal on fds 0/1/2
  C->>C: posix_spawn(SETEXEC, CLOEXEC_DEFAULT, SETSIGDEF, SETSIGMASK, chdir)
  Note over C: the program replaces the child and inherits no descriptor of the app
  C-->>P: output on the master (O_NONBLOCK, read source)
  P-->>E: bytes fed straight from the PTY queue (thread-safe feed)
  S->>P: write(keys) — pending buffer, never blocks the UI
  S->>P: resize → TIOCSWINSZ (kernel raises SIGWINCH)
  C-->>P: exit → waitpid → drain remaining output
  P-->>S: onExit(status) — output always before exit
  • Only async-signal-safe calls happen between forkpty and exec; argv/envp/attributes are built before. On failure errno is written to a close-on-exec pipe and the launch throws.
  • terminate = SIGHUP to the session, then SIGKILL after a grace period; deinit hangs up and reaps, so no zombie and no orphan survives.
  • Foreground job detection uses tcgetpgrp on the master; cwd/CPU/memory come from libproc.
  • An earlier design used posix_spawn alone with POSIX_SPAWN_SETSID. Tests showed that on macOS the slave is then not acquired as controlling terminal (zsh lost job control), hence forkpty.

# Session, workspace model, displays

  • Session (TerminalCore.TerminalSession, @MainActor @Observable) owns one SPTerminalView (a SwiftTerm.TerminalView subclass) and one PTYProcess. Byte counters are sampled once per second on the main actor, so heavy output never floods the main thread with observation updates. A session is independent from windows: moving a pane only re-parents its view.
  • UserInputScope marks key-event dispatch, pastes and drops; only bytes sent inside that scope are offered to broadcast input, so automatic terminal replies are never mirrored.
  • LayoutNode is an n-ary split tree (value type): .pane(id) or .split(axis, fractions, children), always normalized (no single-child split, no nested split of the same axis, fractions sum to 1). Operations: split, remove, swap, move-to-edge, divider resize, keyboard resize, equalize, geometric neighbour lookup, frames/dividers for a rectangle, grid builders.
  • PlacementEngine guarantees that every frame it returns is reachable (title bar inside the visible area of an existing display). resolve restores a saved window (same display → kept; another resolution → rescaled; display id changed → matched by name + size; display gone → moved to the main display keeping proportions). rescue is called on didChangeScreenParametersNotification and moves only windows that became unreachable.
  • AppModel (main actor, observable) owns sessions ([PaneID: TerminalSession]), window states and all operations.

# Concurrency

Swift 6 language mode with complete checking in every target. UI state is @MainActor. PTYProcess confines its mutable state to one serial queue (@unchecked Sendable, documented). Git and AI calls are async; AI requests can only be built from an ApprovedPreview, commands can only run from an ApprovedCommand — both types have no public initializer.

sequenceDiagram
  autonumber
  participant U as User
  participant A as Assistant panel
  participant R as SecretRedactor
  participant G as ConsentGate
  participant P as Provider (BYOK)
  U->>A: question (+ optional "Selected text" or "Last 60 lines")
  A->>R: mask secrets
  R-->>A: ContextPreview — destination, model, byte count, masked text
  A-->>U: exact payload shown
  U->>A: Send
  A->>P: AIClient.send(ApprovedPreview)
  P-->>A: answer with suggested command (text only)
  U->>A: Review & Run
  A->>G: full command, target, host, directory, risk reasons
  G-->>U: confirmation (typed phrase when destructive, sudo, network transfer or multi-host)
  U->>G: confirm
  G-->>A: ApprovedCommand → typed into the session

# 🧱 Stack

Layer Technology Version Role
Language Swift language mode 6.0, SWIFT_STRICT_CONCURRENCY: complete (project.yml) everything
UI SwiftUI + AppKit system chrome · windows, focus, menus, screens, terminal view
Project XcodeGen (project.yml) → SPTerm.xcodeproj xcodeVersion: 27.2 targets SPTerm and SPTermTests
Packages SwiftPM, swift-tools 6.0, platform macOS 14 3 local packages SPTermKit (7 libraries), SPRemoteKit (2 libraries + internal SPProcess), SPIntelligence (1 library)
Terminal engine SwiftTerm 1.99.2, exact pin, MIT VT/xterm parser, buffer, renderer, search, accessibility
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
Git system /usr/bin/git system read-only, allow-listed subcommands
Assistant Anthropic, OpenAI, OpenAI-compatible HTTP APIs bring your own key optional, off by default
Secrets macOS Keychain (service ai.spboucher.spterm.ai) system API keys only
Process probes libproc, tcgetpgrp system cwd, CPU, memory, foreground job
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

# 🗂 Repository layout

155 tracked files; 79 Swift files, 16 549 lines (tests included).

text
App/
  Sources/SPTerm/          19 files — application target
    App/                   AppDelegate, Actions, SearchSupport
    Model/                 AppModel, WindowState
    Panels/                AssistantPanel, GitPanel, HostsAndSnippets
    Views/                 WindowRootView, PaneViews, SidebarView, CommandPaletteView, SettingsView, Sheets, Styling, SPColor
    Windows/               WorkspaceWindowController, QuickTerminalController, Notifier
  Tests/SPTermTests/       hosted integration tests (WorkspaceTests, SafetyTests, PerformanceTests, Support)
Packages/
  SPTermKit/               PTYProcess · TerminalCore · WorkspaceKit · WindowManager · SessionStore · SettingsModel · DesignSystem (+ 6 test targets)
  SPRemoteKit/             SSHKit · GitKit · SPProcess (+ 2 test targets)
  SPIntelligence/          AIAssistant (+ 1 test target)
Assets/Brand/              icon sources (SVG), three concepts, PNG exports 1024–16 px, brand guide, render.sh
Resources/                 Info.plist, SPTerm.entitlements, Assets.xcassets (AppIcon, AccentColor)
Scripts/                   build, kit, smoke, drive, bench, release, notarize, window-shot
docs/                      SECURITY.md, LICENSES.md, RELEASE_NOTES.md, evidence/ (8 screenshots), brand/ (logo, icon)
ARCHITECTURE.md · IMPLEMENTATION_STATUS.md · TEST_REPORT.md · BENCHMARKS.md · RELEASE.md
project.yml                XcodeGen definition

# 🛠 Build from source

You need Xcode 27 and XcodeGen.

sh
Scripts/build.sh generate      # creates SPTerm.xcodeproj from project.yml
Scripts/build.sh run           # debug build + launch
Scripts/build.sh kits          # unit tests of the three Swift packages
Scripts/build.sh test          # integration tests hosted in the app
Script Purpose
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)
Scripts/kit.sh builds / tests one local package and prints only the useful diagnostics: Scripts/kit.sh test SPTermKit --filter Name
Scripts/smoke.sh end-to-end smoke test of the real application, driven through System Events; every check is observed outside the app
Scripts/drive.sh sends keystrokes to the running app through System Events (used by the smoke tests)
Scripts/bench.sh launch time (5 launches after one warm-up) and memory of a built app
Scripts/release.sh universal Release build, Developer ID signature, hardened runtime, verification → dist/SP Term.app
Scripts/notarize.sh notarizes and staples the app, then builds, signs, notarizes and staples the DMG and writes its SHA-256
Scripts/window-shot.swift captures the frontmost window of a named app to a PNG
Assets/Brand/render.sh regenerates every icon PNG and the AppIcon.appiconset (needs rsvg-convert)

# ⚙️ Configuration and data

Setting Value Where
Bundle identifier ai.spboucher.spterm (tests: ai.spboucher.spterm.tests) project.yml
Team 3YM54G49SN project.yml
Version MARKETING_VERSION 1.0.0 · CURRENT_PROJECT_VERSION 1 project.yml
Deployment target macOS 14.0 project.yml
Architectures Debug: arm64 · Release: arm64 x86_64 project.yml
Category public.app-category.developer-tools Resources/Info.plist
Finder integration opens folders (public.folder, alternate handler); Services entry "New SP Term Window Here" Resources/Info.plist
Launch arguments -SPTermDataDir <dir> (own data folder) · -SPTermFresh 1 (nothing restored) App/Sources/SPTerm/App/AppDelegate.swift
Notarization profile NOTARY_PROFILE environment variable, default MacLustr-Notarize (a notarytool keychain profile, referred to by name only) Scripts/notarize.sh

Data directory ~/Library/Application Support/SP Term/ (0700), files 0600, each a versioned envelope {"schemaVersion": N, "payload": …} written atomically (temp file + rename):

File Content
settings.json preferences and shortcut overrides
last-session.json layout autosaved while running (schema 2; schema 1 is migrated)
workspaces.json named workspaces
snippets.json command snippets
hosts.json SSH profiles added in the app (no secrets)
ai-providers.json provider label, URL, model — never the key
history.jsonl opt-in command history (snippets / assistant / broadcast only)

An unreadable or newer-schema file is renamed *.unreadable-<timestamp> and defaults are used; a damaged layout is repaired tab by tab. API keys are in the Keychain. Terminal output is never written to disk unless the user exports a session.


# 🛡 Security and privacy

In short (details: docs/SECURITY.md):

  • Distributed outside the Mac App Store with a Developer ID signature and the hardened runtime; not sandboxed (a terminal must run arbitrary programs with your permissions). One entitlement only: Apple Events automation for programs you run.
  • Nothing about your sessions leaves the Mac unless you press Send in the assistant after reviewing the payload.
  • No terminal output is written to disk unless you export it. Private mode disables layout saving, history and notifications.
  • Pastes with several lines ask first; pastes containing escape sequences always ask. Programs cannot read the clipboard (OSC 52) unless you allow it, and writing it asks by default.
  • Broadcast input is off at every launch, needs a confirmation, shows a permanent banner and holds destructive lines.
  • API keys live in the macOS Keychain. SSH keys and passwords are never read, copied or stored.
Mechanism State
Hardened runtime On. No allow-jit, no allow-unsigned-executable-memory, no disable-library-validation, no get-task-allow, no debugger entitlement
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
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
Privileges The app never asks for root, installs no helper, no launch agent, no kernel / system extension, and never touches SIP or Gatekeeper settings
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)
Untrusted terminal output
  • Escape sequences: parsed by the engine; malformed / unknown sequences are ignored (conformance + fuzz tests).
  • Window title (OSC 0/2): control characters removed, length capped.
  • Clipboard (OSC 52): write is ask by default (the text and the requesting program are shown), read is deny by default. Both are settings.
  • 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.
  • Notifications: only process name and duration are shown, never terminal text.
Paste, broadcast, SSH
  • Several lines → confirmation with a preview where control characters are made visible (configurable). Text containing escape sequences or the bracketed-paste terminator → always asks, and the default action pastes a sanitized version. Sanitized pastes never end with a line break, so nothing runs before the user presses Return.
  • Dropped files insert shell-escaped paths (round-trip tested against a real shell with 17 hostile names).
  • Broadcast: off at every launch (never persisted); enabling it shows which sessions will receive input and requires a confirmation; a full-width banner and coloured pane borders stay visible; lines that look destructive or use sudo are held for the other panes until the user types the confirmation phrase. Limit: the pane being typed in is a normal terminal — the line runs there as typed; the guard protects the fan-out.
  • SSH: every field is validated against an allow-list (no leading -, no whitespace, no shell metacharacters); the builder never emits StrictHostKeyChecking, UserKnownHostsFile, BatchMode or password options; extra -o options go through an allow-list. Host key verification is OpenSSH's interactive prompt in the terminal; SP Term never answers it. Opening a host runs ssh only — no command is sent to remote hosts.
Assistant guarantees, enforced by types and tests
  1. No request without a preview: AIClient.send only accepts an ApprovedPreview, which can only be made from a ContextPreview the user has seen.
  2. The preview is the exact payload (destination, model, byte count, masked text). Secrets are always masked first.
  3. Terminal text is attached only when the user selects Selected text or Last 60 lines.
  4. Local-only mode refuses every non-loopback destination before any I/O; plain HTTP to a remote host is refused.
  5. API keys are stored in the Keychain, sent in a header, and wrapped in a type whose description is redacted.
  6. 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.

Not stored: terminal output, keystrokes typed at prompts, API keys, SSH credentials. There is no plugin system and no scripting bridge: SP Term loads no third-party code and exposes no automation interface that could run commands.

Known limits: the risk analyzer and the secret redactor are pattern based — safe means "no known risky pattern", and an unusual secret format can pass unmasked (the preview exists so the user can check). A program running in a session has the user's full permissions; SP Term does not confine it. Exported session files contain whatever was on screen (masked by default); they are created 0600.


# ✅ Testing

Report: TEST_REPORT.md — 2026-11-17, MacBook Pro Apple M5 Max, macOS 27.0, Xcode 27.2, Swift 6.4.2, one display. All numbers are copied from the output of the listed commands.

Suite Command Result
SPTermKit (core) Scripts/kit.sh test SPTermKit 98 tests passed (PTY 17, terminal core 34, workspace 19, placement 13, storage 10, themes 5)
SPRemoteKit Scripts/kit.sh test SPRemoteKit 65 tests passed (SSH 39, git 26)
SPIntelligence Scripts/kit.sh test SPIntelligence 56 tests passed (parameterized: 118 risk cases, 28 redaction cases, 27 loopback hosts)
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)
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
Total automated tests 257 unit / integration tests, 0 failing at the last run
What each suite proves
  • PTY (real processes) — output and exit code; a real controlling terminal; SIGWINCH delivered with the new size; Ctrl+C interrupts the foreground job and not the shell; Ctrl+Z suspends and job control works in zsh; Ctrl+D is end-of-file; Unicode round trip (accents, CJK, ZWJ emoji); terminate ends and reaps the session; the child inherits no descriptor of the app; 200 000 lines are delivered completely before the exit is reported; 300 KB of input is accepted without blocking.
  • Engine conformance (SwiftTerm 1.99.2 headless) — cursor addressing, erase / insert / delete line, SGR including 256 and true colour, alternate screen, scrolling region, bracketed paste, mouse and focus-report modes, OSC 0/2/8/52, wide / combining / ZWJ / flag sequences, wrap and reflow, bounded scrollback, a corpus of malformed sequences and invalid UTF-8, 60 fuzz rounds of 4 000 random chunks with random resizes. These are checks of the integrated engine, not of an emulator written for SP Term.
  • Layout and workspace model — recursive splits, exact tiling without overlap for 2/3/4/6/8 panes, divider and keyboard resizing with minimum sizes, geometric focus navigation, Codable round trip, 200 random operation sequences preserving all invariants.
  • Multi-display placement (simulated monitors) — 500 random configuration changes (1–3 displays, a projector, random frames) never leave a window unreachable; hosted versions run against real NSWindow objects.
  • Storage — 0600 / 0700 permissions, corrupt file set aside not deleted, newer schema refused and preserved, migration from schema 1, history opt-in, private mode, masking.
  • SSH and git — config parsing fixtures, every command-builder security rule, hostile host names refused, read-only git on temporary repositories, the allow-list refusing mutating subcommands. One real session to a LAN host was opened by hand through the palette.
  • Safety (hosted) — broadcast guards, paste policy including escape injection, OSC 52, and the assistant: no request without preview and explicit send (counted on a mock transport), masked payload, the API key never in the body or in descriptions, execution only through the consent gate.

End-to-end. XCUITest cannot be used on this toolchain (Xcode 27.2 on macOS 27.0 times out "enabling automation mode"), so Scripts/smoke.sh drives the real app with System Events and observes results from outside (files written by commands typed into panes, window counts, the saved layout).

Defects found by testing and fixed
Found by Defect Fix
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
PTY tests exit of very short programs could be missed (process source registered after the exit) registration handler + end-of-file triggered polling
PTY tests (crash, signal 5) releasing a suspended dispatch write source the source is cancelled and recreated instead of suspended
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
Screenshot of an ended SSH pane status bar showed "Exited" twice and a local directory for a remote session status bar corrected
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
Theme tests secondary text below 4.5:1 on the two light themes darker secondary text on light themes
Not tested
  • More than one physical display (only simulated displays were available); Spaces.
  • VoiceOver; the app was not run with VoiceOver on.
  • Mouse gestures: divider dragging, tab and pane drag & drop, ⌘-click on links, text selection.
  • Quick terminal hotkey, notifications, the Finder Services entry, the session export save panel.
  • Real AI providers (no request was sent), real agent CLIs inside panes.
  • fish, nvim, htop, nano (first three not installed on the reference machine); tmux attach entry.
  • Intel execution: the x86_64 slice is built and signed but was not run.
  • macOS 14 and 15: the deployment target is 14.0 but the app only ran on macOS 27.0.
  • Long-duration use, sleep / wake, very large numbers of sessions.

# ⚡ Benchmarks

Measured on 2026-11-17 on one machine (MacBook Pro, Apple M5 Max, 48 GB RAM, macOS 27.0), single runs unless a spread is given: orders of magnitude, not guarantees. Renderer under test: the engine's default CoreGraphics renderer; the Metal renderer was not measured and SP Term makes no claim of GPU acceleration. Full text: BENCHMARKS.md.

Measure Result Method
Launch → first window on screen 250–259 ms (median 255, 5 launches) Scripts/bench.sh, signed universal Release build
Memory, 1 pane, idle 57 MB physical footprint (100 MB resident) footprint, ps
Memory, 8 panes (8 shells), idle 64 MB footprint (107 MB resident) preset grid8
CPU, 8 idle panes 1.2 % ps
Bundle size / DMG size 23 MB / 8.3 MB universal binary
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
Echo latency: key → PTY → echo → screen buffer median 0.26 ms, p95 0.36 ms (200 keys) stops at the screen buffer
300 view resizes while a loop prints 0.32 s setFrameSize × 300, then stty size
Memory with a full 200 000-line scrollback ≈ 365 MB more task_info before / after
Backward search in 200 000 lines 2.5 s findPrevious

Reading these numbers: typing latency to glass was not measured (the 0.26 ms figure stops at the screen buffer); throughput is without drawing; a long scrollback is memory-hungry (roughly 1.8 KB per line at this width — the default is 20 000 lines, the setting goes up to 1 000 000); searching a 200 000-line scrollback runs on the main thread; Debug builds are 10–25 times slower on the parsing paths, always measure Release.


# 🚀 Release

Procedure: RELEASE.md. Prerequisites are checked, never created, by the scripts: Xcode 27, XcodeGen, a Developer ID Application certificate in the login keychain, and a notarytool keychain profile referred to by name only.

sh
Scripts/build.sh kits          # 1. unit tests of the three packages
Scripts/build.sh test          # 2. integration tests hosted in the app
Scripts/release.sh             # 3. universal Release build, Developer ID signature, hardened runtime, verification
Scripts/smoke.sh "dist/SP Term.app"   # 4. end-to-end check of the signed build
Scripts/notarize.sh            # 5. notarize + staple the app, build/sign/notarize/staple the DMG, SHA-256

Versioning: MARKETING_VERSION and CURRENT_PROJECT_VERSION live in project.yml. Bump them, add a section to docs/RELEASE_NOTES.md and to the changelog of RELEASE.md, then regenerate the project (Scripts/build.sh generate).

Verification of a finished release:

sh
codesign --verify --deep --strict --verbose=2 "dist/SP Term.app"
codesign -d --entitlements - --xml "dist/SP Term.app" | plutil -p -
xcrun stapler validate "dist/SP Term.app"
xcrun stapler validate dist/SPTerm-<version>.dmg
spctl --assess --type execute --verbose=2 "dist/SP Term.app"
spctl --assess --type open --context context:primary-signature --verbose=2 dist/SPTerm-<version>.dmg
shasum -a 256 -c dist/SPTerm-<version>.dmg.sha256
State of 1.0.0 (1) Result (from RELEASE.md)
Tag v1.0.0
dist/SP Term.app universal (x86_64 arm64), Developer ID Application: Simon-Pierre Boucher (3YM54G49SN), hardened runtime, one entitlement
Notarization app and DMG Accepted by Apple
Stapling app and DMG validated with stapler validate
Gatekeeper spctl: accepted, source=Notarized Developer ID (app, DMG, app inside the mounted DMG)
dist/SPTerm-1.0.0.dmg 8 287 990 bytes, SHA-256 9f07160dd2f174d19a4830e90d89656a1accc28f779650a8febeda2e24eb5a00
Published by the scripts No — nothing is uploaded except to Apple's notary service; the DMG stays in dist/

Updates. No automatic update mechanism is enabled: there is no feed URL. Sparkle (EdDSA-signed appcasts served over HTTPS, private key kept off the repository) is the intended mechanism once a distribution URL exists.


# 🎨 Brand

The mark is an SP monogram drawn as a monoline, with a glowing block cursor parked under the bowl of the P: read left to right it says SP▮. Guide: Assets/Brand/BRAND.md.

File Purpose
Assets/Brand/SPTermIcon.svg master drawing, used for 64 px and above
Assets/Brand/SPTermIcon-small.svg simplified drawing, used for the 16 and 32 px renders
Assets/Brand/SPTermGlyph.svg single-colour template glyph (menus, toolbar, in-app)
Assets/Brand/Concepts/ the three explored concepts (A is the winner, chosen on small-size legibility)
Assets/Brand/Exports/ RGBA exports 1024–16 px
docs/brand/ README lockup (logo.svg) and 256 px icon (icon.png)

Brand gradient: #22D3EE → #4C8DFF → #9B6CFF (cyan at the bottom-left, violet at the top-right) on graphite surfaces (#0D0F13 … #323844). UI font SF Pro, terminal font SF Mono (default 13 pt). The wordmark is written SP Term.

bash
Assets/Brand/render.sh   # needs rsvg-convert (brew install librsvg)

# 🚧 Limitations and known issues

See IMPLEMENTATION_STATUS.md for the full list.

  • Restored sessions are new processes; persistence across restarts relies on tmux/zellij.
  • Ligatures depend on the chosen font; line spacing is not adjustable; inline images depend on the engine's default support and are not validated.
  • Metal rendering is an experimental switch, not the measured default.
  • Automatic updates are not included (no update feed is configured).
  • Multi-display behaviour is covered by simulated-display tests; it was exercised on real hardware with one display only.
  • The Intel slice of the universal binary was built and signed but never executed; macOS 14 and 15 were not run.
  • No request was ever sent to a real AI provider: the assistant is tested with a mock transport.
  • The interface is in English only; VoiceOver was not audited.

Known issues:

  • The 16 px icon is soft (strokes are not pixel-hinted).
  • During one automated run a second window opened without a traceable cause; it could not be reproduced in two replays of the same keystrokes (other automation was active on the machine at the time).
  • System Events key injection is unreliable when keystrokes are sent faster than about 1 per second on the reference machine; the smoke test therefore runs slowly and can report a spurious failure.
  • A 200 000-line scrollback costs several hundred MB of memory; the default is 20 000.
  • Exported text keeps soft-wrapped lines as separate lines.

# 📚 Third-party components

Component Version Licence Use
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)
swift-argument-parser 1.8.2 (transitive, build tools of SwiftTerm only) Apache-2.0 not linked into the app

SwiftTerm is used unmodified through Swift Package Manager. SP Term subclasses its TerminalView (SPTerminalView) to add guarded paste, file drops and a host context menu; no source of the engine is patched. The MIT notice is shown in the About panel and reproduced in the distribution. System tools executed at the user's request, not redistributed: /usr/bin/ssh, /usr/bin/sftp, /usr/bin/ssh-keygen, /usr/bin/git, the user's shells, and optional tmux / zellij / agent CLIs. All colour themes, the icon and the brand assets are original to SP Term. Details: docs/LICENSES.md.


# 👤 Author

Simon-Pierre Boucher — design, development, operations

www.spboucher.ai · git.spboucher.ai · contact@spboucher.ai

# 📄 License

© 2026 Simon-Pierre Boucher. All rights reserved. Terminal emulation by SwiftTerm, © Miguel de Icaza and contributors (MIT).

Files main
Menu

Theme