Split the proxy core into a shared library, add a Linux CLI

[svandragt]

Closes #8.

Problem

ProxyLight only ran as a macOS menu bar app. Everything lived in one target, so it couldn't build on Linux at all, even though most of the proxy has nothing macOS-specific in it.

Solution

Split the package into a portable core library, the existing macOS app, and a new command-line tool that runs on Linux and macOS.¹ The app behaves exactly as before; it now depends on the core instead of owning everything.²

The CLI covers starting the proxy and managing mappings, and nothing else.³ It prints the PAC URL and the CA certificate path; the user points their browser at the URL and imports the certificate by hand. No system-proxy automation, no trust-store install, no login-at-boot, no self-update, as agreed in #8.

Along the way this fixes a real bug: the CLI ignored Ctrl-C and kill, so it couldn't be run under a process manager.⁴

Tests are split the same way, and the portable suite passes on Linux.⁵ README and CLAUDE.md describe the new layout and the Linux build.⁶

Not in this PR

No CI job for Linux yet. Builds were checked by hand in Docker.

Test plan

• swift build and swift test on macOS: app unchanged, all tests pass
• docker run --rm -v "$PWD":/src -w /src swift:6.1-noble swift build --product proxylight-cli -c release --static-swift-stdlib produces a binary that runs on the host
• proxylight-cli mapping add … && proxylight-cli start serves http://127.0.0.1:9876/proxy.pac
• kill -TERM <pid> stops it

Footnotes

1. Package.swift now has three targets. ProxyLightCore: mapping engine, PAC generation, CA and leaf certificate generation, the SwiftNIO proxy pipeline, and a new ProxyOrchestrator extracted from AppState. ProxyLight: the macOS app. proxylight-cli: the executable, built on swift-argument-parser. ↩

2. macOS-only wrappers (SystemProxyManager, CATrustManager, SelfUpdater, LoginItemManager, ProxyRestoreStore) moved to Sources/ProxyLight/MacOS/. MappingStore gained an #if os(macOS) branch so the config directory is ~/Library/Application Support/ProxyLight on macOS and $XDG_CONFIG_HOME/proxylight (default ~/.config/proxylight) on Linux. ↩

3. Subcommands: start (default, --port), mapping add|list|remove (add --fallback-on-not-found for serve-local-first mode), import, export, ca-path. ↩

4. The SIGINT/SIGTERM DispatchSource was scheduled on DispatchQueue.main, which never drains because the CLI blocks the main thread on a semaphore instead of running a run loop. It now uses a dedicated queue. ↩

5. ProxyLightCoreTests (portable) and ProxyLightTests (macOS-only). The core suite is 86/86 against the swift:6.1 Docker image. ↩

6. The dependencies (swift-nio 2.101, swift-nio-ssl 2.37, swift-certificates 1.19) require Swift tools 6.1, so swift:6.0 images fail. --static-swift-stdlib is needed for the binary to run outside the build container. ↩

[svandragt]

• I need to Test
• change pr to ready

[stuartshields]

@svandragt Would this also work with Windows Powershell? I don't have a Windows laptop to try it out.

[svandragt]

I would presume not. Windows and Linux are very different. There are free Windows VMs available on Microsoft's site but I'd open a separate issue for that for now, it's not in scope.

Powershell the terminal app can run Windows cli executables fine though. Powershell the scripting language has its own syntax so I don't think that's what you mean.

If you mean WSL then it might work. Also worth testing in a separate issue

[stuartshields]

@svandragt Yeah WSL is what I meant. I agree that we can test this in a different issue.

[svandragt]

@stuartshields ready. Tested successfully on a DDEV WP project!