Fallout Terminal

Приложение для ведущего настольной RPG: мастер редактирует терминалы в нативном окне macOS, а игроки видят общий Fallout-style терминал в браузере. Навигация, взлом, подключение новых игроков и восстановление соединения синхронизируются встроенным HTTP/WebSocket-сервером.

Приложение работает на Go + Wails v2. Текущий поддерживаемый профиль — персональное использование на macOS 13+ / Apple Silicon (arm64). Локально собранный и подписанный ad-hoc пакет Fallout Terminal.app принят для этого профиля. Сервер игроков является частью приложения: его не нужно и нельзя запускать отдельной командой.

Публичное распространение — отдельный условный профиль. Он запрещён, пока оператор не выполнит Developer ID signing, notarization, stapling, сборку DMG и проверку Gatekeeper. Отсутствие этих credentials не блокирует персональное использование.

Требования для разработки

• macOS 13 или новее на Apple Silicon;
• Xcode Command Line Tools;
• Go 1.26.x;
• Node.js 20+ и npm;
• Wails CLI строго версии 2.13.0;
• бинарник ngrok — только если нужен публичный доступ.

Установка и проверка Wails относятся к подготовке рабочего места, а не к ежедневному запуску:

go install github.com/wailsapp/wails/v2/cmd/wails@v2.13.0
wails doctor

Frontend-зависимости отдельно устанавливать не требуется: корневой wails.json поручает Wails выполнить npm ci, запустить Vite, собрать Go-приложение и поднять сервер игроков.

Запуск всей системы одной командой

После установки требований перейдите в корень репозитория и выполните ровно одну команду:

wails dev

Это единственная команда запуска разработки. Не запускайте отдельно npm run dev, go run, старый Node-сервер или второй терминал. Wails откроет окно мастера и внутри того же процесса поднимет адрес игроков на порту 3690, обычно http://<IP-мастера>:3690.

Если порт занят, приложение должно показать понятную ошибку и не сообщать о готовности. После нормального выхода окно, HTTP/WebSocket listener и принадлежащие приложению дочерние процессы должны завершиться.

Локальный и публичный режим

По умолчанию wails dev работает только в локальной сети и не запускает ngrok.

Для публичного режима сначала установите ngrok, настройте токен аккаунта и зарезервируйте используемый HTTPS-домен. Это одноразовая подготовка:

ngrok config add-authtoken <ВАШ_ТОКЕН>

Затем запустите всю систему одной командой из корня репозитория:

NGROK_ENABLED=1 NGROK_USERNAME=players NGROK_PASSWORD='<ПАРОЛЬ_ОТ_8_ДО_128_СИМВОЛОВ>' wails dev

Вместо пары переменных можно передать combined credential, сохранив тот же единственный вызов:

NGROK_ENABLED=1 NGROK_BASIC_AUTH='players:<ПАРОЛЬ_ОТ_8_ДО_128_СИМВОЛОВ>' wails dev

Дополнительные параметры:

• NGROK_DOMAIN — домен; по умолчанию fallout-terminal.ngrok.app;
• NGROK_BIN — полный путь к бинарнику, если ngrok отсутствует в PATH;
• NGROK_TIMEOUT — положительная Go-длительность, например 30s;
• NGROK_TIMEOUT_MS — положительный тайм-аут в миллисекундах.

Публичный режим fail-closed: без корректного логина и пароля процесс ngrok не запускается, а локальный адрес продолжает работать. HTTP и WebSocket защищаются одной Basic Auth policy. Кредентиалы не записываются в сессии или интерфейс; временный policy-файл имеет приватные права и удаляется после запуска или обработанной ошибки.

Для проверки уже собранного приложения с теми же переменными можно выполнить его бинарник одним вызовом:

NGROK_ENABLED=1 NGROK_USERNAME=players NGROK_PASSWORD='<ПАРОЛЬ>' './build/bin/Fallout Terminal.app/Contents/MacOS/Fallout Terminal'

Обычный локальный пользователь запускает установленный Fallout Terminal.app одним открытием в Finder; Go, Node, npm, Vite и Wails CLI для этого не нужны.

Сессии и данные macOS

• Новый файл по умолчанию предлагается в ~/Documents/Fallout Terminal/Sessions/. Каталог создаётся только после подтверждения диалога сохранения.
• Пользователь выбирает фактический путь файла; последующие атомарные сохранения продолжают писать туда же.
• Встроенный sessions/demo.json внутри ресурсов приложения доступен только для чтения. Для редактирования мастер явно создаёт пользовательскую копию.
• Метаданные приложения, если они понадобятся, размещаются в ~/Library/Application Support/com.vaulttec.fallout-terminal/. Содержимое сессий туда не переносится.
• Приложение не должно записывать пользовательские данные внутрь .app или рядом с ним.

Перед экспериментами используйте копии важных .json-сессий. Формат совместимости остаётся версией 1; runtime-состояние трансляции, взлома, игроков и туннеля в файл не сохраняется.

Проверки

Основные автоматические проверки из корня репозитория:

gofmt -l .
go vet ./...
go test ./...
go test -race ./...
npm ci --prefix frontend
npm run build --prefix frontend

gofmt -l . не должен печатать имена Go-файлов. Race-проверка обязательна для live/player кода. Полный ручной сценарий с 4–7 браузерами, reconnect, звуком, публичным доступом и упаковкой находится в quickstart миграции.

Активная персональная сборка macOS

Собрать тестовый Apple Silicon .app без релизных credentials:

wails build -clean -platform darwin/arm64

Ожидаемый результат — build/bin/Fallout Terminal.app. Это активный персональный пакет: он должен запускаться без dev-серверов и инструментов, открывать локальный адрес игроков, содержать все master/player assets и корректно завершать listener. Wails создаёт локальную ad-hoc подпись; при первом запуске перенесённого пакета macOS может потребовать одноразовое разрешение через System Settings → Privacy & Security → Open Anyway. Не отключайте Gatekeeper глобально и не публикуйте этот пакет как Developer ID release.

Условный публичный релиз и notarization

Релизный DMG допустим только после полного конвейера: Developer ID Application signing с hardened runtime, проверка codesign, отправка через xcrun notarytool с Keychain profile, успешная notarization, stapling и проверка Gatekeeper через spctl.

Репозиторный entry point для этого конвейера — scripts/build-macos.sh. Если скрипт ещё отсутствует или не исполняемый, релизный путь для данного checkout не готов; ограничьтесь unsigned-сборкой:

test -x scripts/build-macos.sh
scripts/build-macos.sh

Секреты должны передаваться скрипту только по документированным ссылкам на Developer ID/Keychain profile и не попадать в командный вывод. Оператор обязан сохранить не секреты, а проверяемые результаты: архитектуру, SHA-256, codesign --verify, hardened-runtime flags, notarization ID/status, stapling и spctl --assess.

На данный момент README не утверждает, что подписанный/notarized/stapled DMG уже получен или прошёл Gatekeeper. Такое утверждение допустимо только после записи реального evidence в quickstart миграции. Официальные справки: Apple — notarizing macOS software и Apple — distribution and releases.

Восстановление после ошибки

• Порт 3690 занят: корректно закройте предыдущий экземпляр Fallout Terminal или другой известный процесс, затем снова выполните единственную команду запуска. Не поднимайте сервер игроков вручную на другом порту.
• Публичный режим не запускается: локальная игра остаётся доступна. Проверьте NGROK_USERNAME, длину пароля, NGROK_BIN, зарезервированный HTTPS-домен и токен ngrok; либо уберите NGROK_ENABLED и перезапустите локально.
• Прерван wails dev с активным ngrok: предпочтительно сначала закрыть нативное приложение через Quit. Если supervisor был аварийно остановлен, найдите только тестовый процесс командой pgrep -fl '[n]grok' и завершите конкретный PID через kill -TERM <PID>; не используйте широкое удаление процессов.
• Сессия не открывается: исходный файл не заменяется при ошибке валидации. Сохраните его копию и проверьте, что это корректный JSON формата version 1.
• Новая Wails-сборка не прошла персональный acceptance: переключитесь на зафиксированный Electron rollback commit или артефакт по процедуре отката. Публичные trust gates не влияют на решение о персональном откате.

Отложенные платформы

Первый поддерживаемый релиз — только macOS 13+ / Apple Silicon. Intel Mac, universal macOS binary и Windows/WebView2 отложены и не должны считаться проверенными или распространяться как поддерживаемые сборки. Текущий путь разработки Wails всегда начинается с wails dev; Electron-исходники доступны только через зафиксированную rollback-ревизию.

Основные каталоги

• frontend/ — интерфейс мастера для Wails;
• client/ — встроенная браузерная страница игроков, шрифты и звуки;
• internal/ — домен, сессии, live-state, player server, tunnel и platform boundaries;
• sessions/ — встроенные version-1 примеры;
• build/ — metadata, icon и локальные build artifacts;
• specs/001-wails-v2-migration/ — требования, контракты и подробный acceptance guide.