feat: register cockatrice:// and cockatrice-oracle:// protocol handlers

Adds OS-level URL-scheme handlers so users can click a link in a browser,
chat client, or third-party tool to launch Cockatrice straight into a
server / game / Oracle update.

Supported URL forms:
  cockatrice://joingame?hostname=H&port=P&roomid=R&gameid=G[&spectate=1]
  cockatrice-oracle://update[?spoilers=1]

Credentials passed via URL (username/password query params) are deliberately
ignored — URLs leak through shell history, browser history, EDR capture, etc.
If the target server requires auth and no saved credentials match, the Connect
dialog opens pre-filled with the URL's host/port so the user types their
password locally.

OS integration
- Linux: MimeType=x-scheme-handler/cockatrice (and -oracle) added to the
  .desktop files; Exec=cockatrice %u passes the URL through.
- Windows: NSIS installer writes HKCR\cockatrice and HKCR\cockatrice-oracle
  registry entries; uninstaller removes them.
- macOS: per-app Info.cockatrice.plist / Info.oracle.plist declare
  CFBundleURLTypes; a QFileOpenEvent filter is installed on QApplication
  before any nested event loop so cold-start URLs aren't lost.

New abstractions
- Intent (libcockatrice_utility/libcockatrice/utility/intent.h): abstract base
  for chained async actions.  Guarantees finished() fires at most once,
  execute() is idempotent, self-deletes via deleteLater, and
  startTimeoutSafetyNet() arms a configurable per-stage deadline.  Concrete
  intents (IntentConnectToServer, IntentLogin, IntentJoinServerRoom,
  IntentJoinServerGame) compose the joingame flow via UrlParser.
- SingleInstanceManager: async per-user local-socket primary/secondary
  handshake; URL forwarded from secondary to primary with QDataStream framing
  both ways.  shared_ptr-backed resolved flag survives every lambda capture.
- UrlSchemeEventFilter (new libcockatrice_utility_gui sibling library): QObject
  event filter that translates macOS QFileOpenEvent into a urlReceived(QString)
  signal.  Lives in its own Gui-bearing lib so libcockatrice_utility stays
  Core+Network only and doesn't drag Qt::Gui into servatrice.
- UrlUtils (header-only): pure URL parsing, fully unit-tested.

Wiring
- MainWindow::handleUrl(QString) — single entry point for any URL source.
- DlgConnect::prefillNewHost(host, port) — pre-fills new-host inputs.
- ServersSettings::findSavedCredsByHostPort — case-insensitive saved-creds
  lookup.
- TabSupervisor::requestJoinRoom + roomJoinedById / roomJoinFailedById signals,
  TabServer::roomAlreadyJoined for the short-circuit "already in this room"
  path — single source of truth for duplicate-join handling.

Tests
- 36 new unit tests across four single-purpose targets in tests/:
  - url_utils_test (22 tests) — scheme matching, port/room/game validation,
    spectator flag, credentials ignored, case-insensitivity.
  - url_scheme_event_filter_test (3 tests) — QFileOpenEvent capture.
  - intent_test (7 tests) — self-delete, abort propagation, parent-destruction-
    mid-flight, finish-once gate, execute() idempotence.
  - single_instance_manager_test (4 tests) — per-user socket naming, becoming-
    primary alone, forwarding to an existing primary, single-emission of
    roleResolved.

Build tooling (incidental)
- Dockerfile.format, docker-compose.format.yml, Makefile — a docker-based
  runner for format.sh that mirrors CI's desktop-lint step.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

cockatrice/src/main.cpp

@@ -35,12 +35,16 @@
 #include <QCryptographicHash>
 #include <QDateTime>
 #include <QDebug>
+#include <QEventLoop>
 #include <QLibraryInfo>
 #include <QLocale>
 #include <QSystemTrayIcon>
 #include <QTranslator>
 #include <libcockatrice/card/database/card_database_manager.h>
 #include <libcockatrice/rng/rng_sfmt.h>
+#include <libcockatrice/utility/single_instance_manager.h>
+#include <libcockatrice/utility/url_utils.h>
+#include <libcockatrice/utility_gui/url_scheme_event_filter.h>
 
 QTranslator *translator, *qtTranslator;
 RNG_Abstract *rng;
@@ -230,6 +234,9 @@ int main(int argc, char *argv[])
         {{{"c", "connect"}, QCoreApplication::translate("main", "Connect on startup"), "user:pass@host:port"},
          {{"d", "debug-output"}, QCoreApplication::translate("main", "Debug to file")}});
 
+    parser.addPositionalArgument("url", QCoreApplication::translate("main", "Optional cockatrice:// URL to open"),
+                                 "[url]");
+
     parser.process(app);
 
     if (parser.isSet("debug-output")) {
@@ -253,7 +260,64 @@ int main(int argc, char *argv[])
 
     qCInfo(MainLog) << "Starting main program";
 
+    // Determine if a cockatrice:// URL was passed as a positional argument
+    QString urlArg = UrlUtils::findUrlArgument(parser.positionalArguments(), QStringLiteral("cockatrice://"));
+
+#ifdef Q_OS_MAC
+    // On macOS the OS delivers a registered URL scheme via QFileOpenEvent,
+    // which is queued before main() and dispatched on the FIRST event-loop
+    // spin.  The single-instance handshake below runs a nested event loop, so
+    // the filter MUST be installed beforehand or the cold-start URL is lost.
+    // Until ui exists, buffer the URL into a local; we replay it after
+    // MainWindow construction.  Capture the connection handle so we can
+    // disconnect the buffer-lambda unambiguously once ui is ready.
+    UrlSchemeEventFilter cockatriceFilter(QStringLiteral("cockatrice://"));
+    QString cocoaDeliveredUrl;
+    const auto cocoaBufferConn =
+        QObject::connect(&cockatriceFilter, &UrlSchemeEventFilter::urlReceived,
+                         [&cocoaDeliveredUrl](const QString &url) { cocoaDeliveredUrl = url; });
+    app.installEventFilter(&cockatriceFilter);
+#endif
+
+    // Single-instance: only enforce when delivering a URL to a primary.  When
+    // no URL is involved, try to become primary if available, otherwise allow
+    // this instance to run alongside an existing one (multi-instance workflow).
+    SingleInstanceManager sim(SingleInstanceManager::perUserSocketName(QStringLiteral("CockatriceInstance")));
+    bool wasForwarded = false;
+    {
+        QEventLoop startupLoop;
+        QObject::connect(&sim, &SingleInstanceManager::roleResolved, [&](bool forwarded) {
+            wasForwarded = forwarded;
+            startupLoop.quit();
+        });
+        sim.resolveStartupRole(urlArg);
+        startupLoop.exec();
+    }
+    if (wasForwarded) {
+        qCInfo(MainLog) << "Another instance is already running; URL forwarded. Exiting.";
+        return 0;
+    }
+
     MainWindow ui;
+    if (!urlArg.isEmpty()) {
+        // Deliver the URL once the event loop is running (after ui.show())
+        QTimer::singleShot(0, &ui, [&ui, urlArg]() { ui.handleUrl(urlArg); });
+    }
+
+    // Connect future URLs forwarded from secondary instances (no-op if we are
+    // not the primary)
+    QObject::connect(&sim, &SingleInstanceManager::urlReceived, &ui, &MainWindow::handleUrl);
+
+#ifdef Q_OS_MAC
+    // Re-bind the filter from the buffer-lambda to ui->handleUrl now that ui
+    // exists, and replay any URL captured during the pre-ui startup window.
+    QObject::disconnect(cocoaBufferConn);
+    QObject::connect(&cockatriceFilter, &UrlSchemeEventFilter::urlReceived, &ui, &MainWindow::handleUrl);
+    if (!cocoaDeliveredUrl.isEmpty()) {
+        QTimer::singleShot(0, &ui, [&ui, url = cocoaDeliveredUrl]() { ui.handleUrl(url); });
+    }
+#endif
+
     if (parser.isSet("connect")) {
         ui.setConnectTo(parser.value("connect"));
     }