@git.zone/tsswift

@git.zone/tsswift is a TypeScript library and CLI for real-world Swift development. It walks up from your current directory, detects Package.swift, .xcodeproj, or .xcworkspace, then runs the right tool with consistent rules for scheme selection, platform targeting, simulator choice, app launch, screenshots, and watch/review loops.

Issue Reporting and Security

For reporting bugs, issues, or security vulnerabilities, please visit community.foss.global/. This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a code.foss.global/ account to submit Pull Requests directly.

What It Does

| Project type | tsswift does | | --- | --- | | Package.swift | Uses swift build, swift test, and swift run. | | .xcodeproj / .xcworkspace | Uses xcodebuild, resolves schemes and destinations, chooses simulators, and can launch apps on macOS or iOS/iPad simulators. |

• Detects the nearest Swift project by walking up parent directories.
• Prefers .xcworkspace over .xcodeproj, and .xcodeproj over Package.swift.
• Refuses to guess when a directory has multiple workspaces or projects; pass --path when there is ambiguity.
• Auto-selects the only shared Xcode scheme, or requires --scheme / defaultScheme when multiple schemes exist.
• Builds and tests a platform matrix from .smartconfig.json.
• Persists preferred iPhone and iPad simulators back to .smartconfig.json.
• Supports named remote macOS builders via a global builder registry under ~/.git.zone/tsswift/config.json.
• Exposes the same behavior as a library so you can embed it in your own tooling.

Installation

pnpm add -D @git.zone/tsswift

swift is required for SwiftPM projects. Xcode-oriented commands such as simulator selection, controlled launch, screenshots, and review loops require macOS with Xcode command line tools, either locally or through a configured remote builder.

Quick Start

pnpm exec tsswift doctor
pnpm exec tsswift build
pnpm exec tsswift test
pnpm exec tsswift run

Use doctor first. It prints the detected project kind, resolved defaults, selected platforms, available schemes, and the destination tsswift is going to use.

Commands

| Command | What it does | | --- | --- | | doctor | Inspect the detected project, config, schemes, platforms, and chosen defaults. | | config | Manage named global remote builders. | | build | Build the detected SwiftPM or Xcode project. | | test | Run tests for the detected SwiftPM or Xcode project. | | run | Build and launch one concrete target. | | emulators | List available iPhone and iPad simulators and mark the preferred ones. | | prefer-emulator | Save a preferred iPhone or iPad simulator into .smartconfig.json. | | launch | Build and launch an Xcode app with the file-based control channel wired in. | | command | Send a route or JSON payload to the control file used by launch, screenshots, or watch. | | screenshots | Launch the app and capture one platform's screenshot set from a scenario file. | | review | Capture screenshot sets across the configured review platforms. | | watch | Rebuild and relaunch the configured app platforms whenever source files change. |

Common Examples

pnpm exec tsswift build --configuration Release
pnpm exec tsswift config -g add-builder --name mac-builder --host builder.local --root-dir /Users/builder/project --platforms macos,ios,ipad
pnpm exec tsswift build --scheme MyApp --platform ios
pnpm exec tsswift test --platform ipad --parallel
pnpm exec tsswift run --platform macos
pnpm exec tsswift emulators
pnpm exec tsswift prefer-emulator --platform ios --name "iPhone 16 Pro" --runtime latest
pnpm exec tsswift launch --platform ios --route myapp://mailbox/inbox
pnpm exec tsswift command --json '{"kind":"compose"}'
pnpm exec tsswift screenshots --platform ipad
pnpm exec tsswift review
pnpm exec tsswift watch --platform ios --debounceMs 1200

Common Options

• --path <path>: explicitly target Package.swift, .xcodeproj, or .xcworkspace
• --scheme <name>: choose an Xcode scheme
• --platform <auto|macos|ios|ipad>: choose a platform
• --destination <value>: pass a full xcodebuild -destination
• --configuration <Debug|Release>: choose the build configuration
• --derivedDataPath <path>: choose the Xcode derived data directory
• --controlFile <path>: override the automation control file
• --scenariosFile <path>: override the screenshot scenario file
• --outputDir <path>: override the screenshot/review output directory
• --route <route>: send a route string during launch or command
• --json <json>: send a JSON string during launch or command
• --debounceMs <number>: set the watch debounce in milliseconds
• --parallel: run multi-platform Xcode build or test invocations in parallel
• --print: print the resolved commands instead of running them

Project Detection

tsswift walks upward from the current working directory until it finds a Swift project.

Resolution order is strict:

1. .xcworkspace
2. .xcodeproj
3. Package.swift

If a directory contains multiple workspaces or multiple projects, tsswift stops and tells you to use --path. That is intentional: the tool resolves projects aggressively, but it does not guess blindly.

Configuration

Project configuration lives under @git.zone/tsswift in .smartconfig.json.

tsswift resolves its config root like this:

1. nearest .smartconfig.json
2. nearest package.json
3. the Swift project root

Relative paths in config such as derivedDataPath, control.filePath, screenshots.scenariosFile, and screenshots.outputDir are resolved from that config root.

{
  "@git.zone/tsswift": {
    "defaultScheme": "MyApp",
    "defaultConfiguration": "Debug",
    "derivedDataPath": ".build/xcode-derived-data",
    "platforms": ["macos", "ios"],
    "buildPlatforms": ["macos", "ios"],
    "testPlatforms": ["macos", "ios", "ipad"],
    "watchPlatforms": ["macos", "ios"],
    "watchDebounceMs": 1200,
    "parallelBuilds": true,
    "parallelTests": true,
    "defaultPlatform": "macos",
    "remoteBuilder": {
      "name": "central-macos"
    },
    "app": {
      "bundleId": "com.example.myapp"
    },
    "control": {
      "filePath": "/tmp/myapp-control.txt",
      "fileEnvKey": "MYAPP_CONTROL_FILE",
      "pollMs": 250,
      "pollMsEnvKey": "MYAPP_CONTROL_POLL_MS",
      "initialCommand": "myapp://mailbox/inbox"
    },
    "screenshots": {
      "scenariosFile": "Automation/ui-screenshot-routes.txt",
      "outputDir": ".nogit/ui-review",
      "reviewPlatforms": ["ios", "ipad", "macos"],
      "launchDelayMs": 2000,
      "stepDelayMs": 1200,
      "initialCommand": "myapp://mailbox/inbox",
      "macosWindow": {
        "width": 1440,
        "height": 900,
        "x": 80,
        "y": 80
      },
      "macosLogFile": "/tmp/tsswift-macos-capture.log"
    },
    "targets": {
      "macos": {
        "destination": "platform=macOS,arch=arm64"
      },
      "ios": {
        "simulatorName": "iPhone 16 Pro",
        "simulatorUDID": "IOS-SIMULATOR-UDID",
        "runtime": "latest"
      },
      "ipad": {
        "simulatorName": "iPad mini (A17 Pro)",
        "simulatorUDID": "IPAD-SIMULATOR-UDID",
        "runtime": "18.0"
      }
    }
  }
}

What The Config Fields Mean

• platforms: fallback platform list for Xcode builds and tests
• buildPlatforms: build matrix for tsswift build
• testPlatforms: test matrix for tsswift test
• watchPlatforms: platforms relaunched by tsswift watch
• watchDebounceMs: debounce delay for watch mode
• parallelBuilds: enable parallel multi-platform Xcode builds
• parallelTests: enable parallel multi-platform Xcode tests
• defaultPlatform: single platform used by run and as a fallback elsewhere
• remoteBuilder.name: use a named builder from the global tsswift builder registry
• remoteBuilder.host: direct SSH host for a project-local remote builder override
• remoteBuilder.rootDir: remote project root on the builder machine
• remoteBuilder.port: optional SSH port
• remoteBuilder.sshKeyPath: optional SSH key path
• remoteBuilder.platforms: platforms handled by the remote builder
• remoteBuilder.rsyncExcludes: additional rsync exclude patterns for syncs
• remoteBuilder.rsyncDelete: whether sync uses --delete
• defaultScheme: Xcode scheme to use when the project has more than one
• defaultConfiguration: default build configuration
• derivedDataPath: default Xcode derived data directory
• app.bundleId: explicit app bundle identifier when launching or installing
• control.filePath: file that receives route or JSON payloads
• control.fileEnvKey: environment variable name that points the app at the control file
• control.pollMs: default polling interval for the control file
• control.pollMsEnvKey: environment variable name that tells the app how often to poll
• control.initialCommand: payload written before launch
• screenshots.scenariosFile: scenario file for screenshots and review
• screenshots.outputDir: base output directory for screenshots
• screenshots.reviewPlatforms: platforms used by review
• screenshots.launchDelayMs: delay after app launch before the first capture
• screenshots.stepDelayMs: delay after each scenario payload before capture
• screenshots.initialCommand: screenshot-specific initial payload override
• screenshots.macosWindow: target macOS window size and position before capture
• screenshots.macosLogFile: log file path for macOS capture helpers
• targets.<platform>.destination: full xcodebuild -destination override for macos, ios, or ipad
• targets.ios.simulatorName: preferred iPhone simulator name
• targets.ios.simulatorUDID: exact preferred iPhone simulator UDID
• targets.ios.runtime: preferred iPhone simulator runtime such as latest, 18, or 18.0
• targets.ipad.simulatorName: preferred iPad simulator name
• targets.ipad.simulatorUDID: exact preferred iPad simulator UDID
• targets.ipad.runtime: preferred iPad simulator runtime such as latest, 18, or 18.0

Automation And Screenshots

The automation flow is file-based on purpose. launch starts the app with environment variables that point to a control file, and command writes payloads into that file. Your app is responsible for reading that file and reacting to the payloads.

screenshots and review work with remote builders too. When you do not configure an explicit screenshot output directory, tsswift stores captures in ./.nogit/tsswift-shots under the project config root and syncs remote captures back to that local directory.

Default values when you do not configure anything:

• control file: /tmp/tsswift-control.txt
• scenario file: ui-screenshot-routes.txt
• screenshot output: ./.nogit/tsswift-shots
• watch debounce: 800
• screenshot launch delay: 2000
• screenshot step delay: 1200

Global Builder Registry

Named remote builders live in:

~/.git.zone/tsswift/config.json

Manage them with:

pnpm exec tsswift config -g add-builder --name mac-builder --host builder.local --root-dir /Users/builder/project --platforms macos,ios,ipad
pnpm exec tsswift config -g list-builders
pnpm exec tsswift config -g show
pnpm exec tsswift config -g remove-builder --name mac-builder

Projects can then reference the builder by name in .smartconfig.json instead of embedding SSH details per repo.

Scenario File Format

Use one line per screenshot step in name|payload format. Blank lines and lines starting with # are ignored.

# name|payload
inbox|myapp://mailbox/inbox
thread-42|myapp://thread/42
compose|{"kind":"compose","draft":true}

Automation Examples

pnpm exec tsswift launch --platform ios
pnpm exec tsswift launch --platform macos --route myapp://mailbox/inbox
pnpm exec tsswift command --route myapp://thread/42
pnpm exec tsswift command --json '{"kind":"compose"}'
pnpm exec tsswift screenshots --platform ios --scenariosFile Automation/ui-screenshot-routes.txt
pnpm exec tsswift review --outputDir .nogit/ui-review
pnpm exec tsswift watch

Library Usage

Everything in ts/index.ts is re-exported from the package, so you can use tsswift as a CLI, as a small Swift/Xcode toolkit, or as plumbing inside a larger automation script.

runSwiftAction() executes the resolved command set and returns the invocations it used. If you want to audit the generated commands first, pass printOnly: true.

Detect A Project And Run An Action

import {
  findSwiftProject,
  readTsswiftConfig,
  runSwiftAction,
} from '@git.zone/tsswift';

const project = await findSwiftProject();
const config = await readTsswiftConfig(project.rootDir);

console.log(project.kind);
console.log(config.defaultScheme);

await runSwiftAction('build', {
  platform: 'ios',
});

Inspect Simulator Inventory Or Persist A Preferred Device

import {
  getAvailableSimulatorInventory,
  selectPreferredSimulator,
} from '@git.zone/tsswift';

const inventory = await getAvailableSimulatorInventory();
console.log(inventory.ios[0]);

await selectPreferredSimulator(process.cwd(), 'ios', {
  simulatorName: 'iPhone 16 Pro',
  runtime: 'latest',
});

Drive Automation From Code

import {
  launchAutomationApp,
  sendAutomationCommand,
  captureAutomationScreenshots,
} from '@git.zone/tsswift';

await launchAutomationApp({ platform: 'ios' });
await sendAutomationCommand({ route: 'myapp://mailbox/inbox' });
await captureAutomationScreenshots({ platform: 'ios' });

Behavior Notes

• run always launches one concrete platform. If config leaves both macos and ios in play, set defaultPlatform or pass --platform.
• Parallel execution only applies to Xcode build and test. It does not affect SwiftPM commands and it does not parallelize run.
• On pure SwiftPM projects, launch falls back to run unless you try to use the automation control channel.
• Controlled launch, screenshots, and review are implemented for Xcode app projects. They do not work for pure SwiftPM executables.
• macOS screenshot capture uses AppleScript and screencapture, so Accessibility permission is required to inspect and move the app window.
• prefer-emulator writes the selected simulator name, UDID, and runtime back into .smartconfig.json.
• watch ignores build output and dependency directories such as .git, node_modules, .swiftpm, .build, dist, dist_ts, and derived data.
• --print is the easiest way to audit what tsswift will run before it touches anything.

License and Legal Information

This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the LICENSE file.

Please note: The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.

Trademarks

This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.

Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.

Company Information

Task Venture Capital GmbH
Registered at District Court Bremen HRB 35230 HB, Germany

For any legal inquiries or further information, please contact us via email at [email protected].

By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.