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>

libcockatrice_utility/CMakeLists.txt

@@ -6,16 +6,19 @@ set(CMAKE_AUTOUIC ON)
 set(CMAKE_AUTORCC ON)
 
 set(UTILITY_SOURCES libcockatrice/utility/expression.cpp libcockatrice/utility/levenshtein.cpp
-                    libcockatrice/utility/passwordhasher.cpp
+                    libcockatrice/utility/passwordhasher.cpp libcockatrice/utility/single_instance_manager.cpp
 )
 
 set(UTILITY_HEADERS
     libcockatrice/utility/color.h
     libcockatrice/utility/expression.h
+    libcockatrice/utility/intent.h
     libcockatrice/utility/levenshtein.h
     libcockatrice/utility/macros.h
     libcockatrice/utility/passwordhasher.h
+    libcockatrice/utility/single_instance_manager.h
     libcockatrice/utility/trice_limits.h
+    libcockatrice/utility/url_utils.h
     libcockatrice/utility/zone_names.h
 )
 
@@ -23,7 +26,7 @@ add_library(libcockatrice_utility STATIC ${UTILITY_SOURCES} ${UTILITY_HEADERS})
 
 target_include_directories(libcockatrice_utility PUBLIC ${CMAKE_CURRENT_SOURCE_DIR})
 
-target_link_libraries(libcockatrice_utility PUBLIC libcockatrice_rng ${QT_CORE_MODULE})
+target_link_libraries(libcockatrice_utility PUBLIC libcockatrice_rng ${QT_CORE_MODULE} ${QT_NETWORK_MODULE})
 
 set(ORACLE_LIBS)
 

libcockatrice_utility/libcockatrice/utility/intent.h

@@ -0,0 +1,125 @@
+#ifndef LIBCOCKATRICE_INTENT_H
+#define LIBCOCKATRICE_INTENT_H
+
+#include <QObject>
+#include <QTimer>
+
+/**
+ * @brief Abstract base for chained, URL-driven intents.
+ *
+ * An Intent encapsulates a single async action (e.g. connecting to a server,
+ * joining a room).  Concrete subclasses implement @c doExecute() and call
+ * @c emitFinished(bool) when the action completes or fails unrecoverably.
+ *
+ * Typical usage:
+ * @code
+ *   auto *intent = new MyIntent(ctx, parent);
+ *   intent->execute();  // intent deletes itself via deleteLater when finished
+ * @endcode
+ *
+ * Guarantees:
+ *   - @c finished() is emitted at most once (subsequent emit attempts are no-ops).
+ *   - @c execute() is idempotent: repeated calls do nothing after the first.
+ *   - Self-deletes via @c deleteLater after @c finished() fires (success or failure).
+ */
+class Intent : public QObject
+{
+    Q_OBJECT
+
+public:
+    /** Default deadline for intents that wait on async signals.  Used by the
+     *  default @c timeoutMs() implementation so the chain can't hang
+     *  indefinitely. */
+    static constexpr int DefaultTimeoutMs = 30000;
+
+    explicit Intent(QObject *parent = nullptr) : QObject(parent)
+    {
+        // Self-delete after finished() fires, regardless of whether the
+        // emission came from doExecute() (success/failure) or abort()
+        // (external).
+        connect(this, &Intent::finished, this, &QObject::deleteLater);
+    }
+    ~Intent() override = default;
+
+    /**
+     * @brief Deadline for this intent's timeout safety net, in milliseconds.
+     *
+     * Subclasses override when their work is not bounded by network/server
+     * timing — e.g. an intent that opens a modal dialog should return a
+     * non-positive value to indicate "no auto-timeout, the user paces this
+     * step".  Consumed by @c startTimeoutSafetyNet().
+     *
+     * @return positive deadline in ms, or <= 0 for "no timeout".
+     */
+    [[nodiscard]] virtual int timeoutMs() const
+    {
+        return DefaultTimeoutMs;
+    }
+
+    /** Start executing the intent.  Idempotent — repeated calls are no-ops. */
+    void execute()
+    {
+        if (m_started)
+            return;
+        m_started = true;
+        doExecute();
+    }
+
+    /**
+     * @brief Abort the intent externally, emitting finished(false).
+     *
+     * Used by chain orchestrators (e.g. UrlParser) to propagate a failure
+     * from an upstream intent through the rest of the chain without giving
+     * outside callers direct access to the protected finished() signal.
+     */
+    void abort()
+    {
+        emitFinished(false);
+    }
+
+protected:
+    virtual void doExecute() = 0;
+
+    /**
+     * @brief Single source of truth for emitting @c finished().
+     *
+     * Gated by an internal flag so subsequent calls are no-ops.  Concrete
+     * intents call this instead of @c emit finished(...) directly, which
+     * removes the risk of double-emission when multiple completion signals
+     * race (success + cleanup disconnect, timeout + late response, etc.).
+     */
+    void emitFinished(bool success)
+    {
+        if (m_finished)
+            return;
+        m_finished = true;
+        emit finished(success);
+    }
+
+    /**
+     * @brief Arm the chain-level deadline; aborts on expiry.
+     *
+     * Subclasses call this once from @c doExecute() to install the timeout
+     * safety net described by @c timeoutMs().  No-op when @c timeoutMs() is
+     * non-positive (user-paced intents opt out).
+     */
+    void startTimeoutSafetyNet()
+    {
+        if (const int deadline = timeoutMs(); deadline > 0) {
+            QTimer::singleShot(deadline, this, [this]() { emitFinished(false); });
+        }
+    }
+
+signals:
+    /**
+     * @brief Emitted exactly once when the intent finishes.
+     * @param success @c true on success, @c false on failure.
+     */
+    void finished(bool success);
+
+private:
+    bool m_started{false};
+    bool m_finished{false};
+};
+
+#endif // LIBCOCKATRICE_INTENT_H

libcockatrice_utility/libcockatrice/utility/single_instance_manager.cpp

@@ -0,0 +1,145 @@
+#include "single_instance_manager.h"
+
+#include <QDataStream>
+#include <QLoggingCategory>
+#include <QTimer>
+#include <memory>
+
+Q_LOGGING_CATEGORY(SingleInstanceLog, "single_instance")
+
+SingleInstanceManager::SingleInstanceManager(const QString &socketName, QObject *parent)
+    : QObject(parent), socketName(socketName)
+{
+}
+
+SingleInstanceManager::~SingleInstanceManager() = default;
+
+QString SingleInstanceManager::perUserSocketName(const QString &base)
+{
+#ifdef Q_OS_WIN
+    const QByteArray user = qgetenv("USERNAME");
+#else
+    const QByteArray user = qgetenv("USER");
+#endif
+    if (user.isEmpty())
+        return base;
+    return base + QStringLiteral("-") + QString::fromLocal8Bit(user);
+}
+
+void SingleInstanceManager::becomePrimary()
+{
+    if (server)
+        return; // already listening — idempotent
+    QLocalServer::removeServer(socketName);
+    server = new QLocalServer(this);
+    if (!server->listen(socketName)) {
+        qCWarning(SingleInstanceLog) << "Failed to start local server:" << server->errorString();
+        return;
+    }
+    connect(server, &QLocalServer::newConnection, this, &SingleInstanceManager::onNewConnection);
+}
+
+void SingleInstanceManager::resolveStartupRole(const QString &maybeUrl)
+{
+    if (maybeUrl.isEmpty()) {
+        // No URL to forward — just try to become primary.  Defer the signal
+        // via a queued emission so the contract ("emits roleResolved exactly
+        // once, asynchronously") holds uniformly across both branches.
+        becomePrimary();
+        QMetaObject::invokeMethod(this, [this] { emit roleResolved(false); }, Qt::QueuedConnection);
+        return;
+    }
+
+    // Probe an existing primary.  Lifetime: probe and timer are owned by
+    // *this*; the terminal slot deleteLater()s them.  A shared "resolved"
+    // flag prevents double emission if multiple signals race (errorOccurred
+    // can fire after readyRead, etc.).  shared_ptr so the flag outlives
+    // whichever lambda fires last.
+    auto *probe = new QLocalSocket(this);
+    auto *timer = new QTimer(this);
+    auto resolved = std::make_shared<bool>(false);
+
+    auto finish = [this, probe, timer, resolved](bool forwarded) {
+        if (*resolved)
+            return;
+        *resolved = true;
+        timer->stop();
+        probe->deleteLater();
+        timer->deleteLater();
+        if (!forwarded)
+            becomePrimary();
+        emit roleResolved(forwarded);
+    };
+
+    connect(probe, &QLocalSocket::connected, this, [probe, maybeUrl] {
+        QDataStream stream(probe);
+        stream.setVersion(QDataStream::Qt_5_0);
+        stream << maybeUrl;
+        probe->flush();
+    });
+
+    connect(probe, &QLocalSocket::readyRead, this, [probe, finish] {
+        QDataStream in(probe);
+        in.setVersion(QDataStream::Qt_5_0);
+        in.startTransaction();
+        QString ack;
+        in >> ack;
+        if (!in.commitTransaction())
+            return; // partial ACK — wait for readyRead to fire again with the rest.
+        finish(true);
+    });
+
+    connect(probe, &QLocalSocket::errorOccurred, this, [finish](QLocalSocket::LocalSocketError) {
+        // No primary at this socket — become primary ourselves.
+        finish(false);
+    });
+
+    timer->setSingleShot(true);
+    connect(timer, &QTimer::timeout, this, [finish] {
+        // Primary unresponsive (e.g. stale socket from a dead old primary).
+        // Become primary and hope for the best.
+        qCWarning(SingleInstanceLog) << "Timed out forwarding URL; becoming primary";
+        finish(false);
+    });
+    timer->start(ForwardTimeoutMs);
+
+    probe->connectToServer(socketName);
+}
+
+void SingleInstanceManager::onNewConnection()
+{
+    while (server->hasPendingConnections()) {
+        QLocalSocket *socket = server->nextPendingConnection();
+        connect(socket, &QLocalSocket::readyRead, this, [this, socket]() { processConnection(socket); });
+        connect(socket, &QLocalSocket::disconnected, socket, &QLocalSocket::deleteLater);
+
+        // The secondary may have written its URL and the bytes may have
+        // arrived before we got here.  readyRead has already fired once for
+        // them with no slot connected — drain pre-buffered bytes now so the
+        // payload doesn't sit unread forever.
+        if (socket->bytesAvailable() > 0)
+            processConnection(socket);
+    }
+}
+
+void SingleInstanceManager::processConnection(QLocalSocket *socket)
+{
+    QDataStream in(socket);
+    in.setVersion(QDataStream::Qt_5_0);
+    in.startTransaction();
+    QString url;
+    in >> url;
+    if (!in.commitTransaction())
+        return; // partial payload — readyRead will fire again
+
+    if (!url.isEmpty()) {
+        qCDebug(SingleInstanceLog) << "Received URL from secondary instance:" << url;
+        emit urlReceived(url);
+    }
+
+    // Acknowledge so the secondary can finish cleanly.
+    QDataStream out(socket);
+    out.setVersion(QDataStream::Qt_5_0);
+    out << QStringLiteral("ACK");
+    socket->flush();
+}

libcockatrice_utility/libcockatrice/utility/single_instance_manager.h

@@ -0,0 +1,97 @@
+#ifndef LIBCOCKATRICE_SINGLE_INSTANCE_MANAGER_H
+#define LIBCOCKATRICE_SINGLE_INSTANCE_MANAGER_H
+
+#include <QLocalServer>
+#include <QLocalSocket>
+#include <QObject>
+#include <QString>
+
+/**
+ * @brief Local-socket-based single-instance guard with URL forwarding.
+ *
+ * Asynchronously resolves whether this process is the primary instance or a
+ * secondary that should forward a URL and exit.  All transitions are
+ * driven by Qt signals (QLocalSocket::connected / readyRead /
+ * errorOccurred) plus a single timeout — no synchronous waitFor* calls
+ * anywhere, so platform-specific event-pump quirks don't race.
+ *
+ * Usage at startup (typically in main(), before QApplication::exec()):
+ *
+ * @code
+ *   SingleInstanceManager sim(SingleInstanceManager::perUserSocketName("MyApp"));
+ *   QEventLoop startupLoop;
+ *   bool wasForwarded = false;
+ *   QObject::connect(&sim, &SingleInstanceManager::roleResolved,
+ *                    [&](bool forwarded) {
+ *       wasForwarded = forwarded;
+ *       startupLoop.quit();
+ *   });
+ *   sim.resolveStartupRole(urlFromArgv);  // may be empty
+ *   startupLoop.exec();
+ *   if (wasForwarded) return 0;
+ *   // ...continue as primary (or as a non-primary secondary if no URL)...
+ *   QObject::connect(&sim, &SingleInstanceManager::urlReceived,
+ *                    &mainWindow, &MainWindow::handleUrl);
+ * @endcode
+ */
+class SingleInstanceManager : public QObject
+{
+    Q_OBJECT
+
+public:
+    /** Deadline for the probe-and-forward handshake.  After this, we assume
+     *  no primary is listening (or the old primary is dead) and become
+     *  primary ourselves. */
+    static constexpr int ForwardTimeoutMs = 2000;
+
+    explicit SingleInstanceManager(const QString &socketName, QObject *parent = nullptr);
+    ~SingleInstanceManager() override;
+
+    /**
+     * @brief Build a per-user socket name to prevent cross-user squatting.
+     *
+     * Appends the current user's name from $USER (Unix) or $USERNAME (Windows)
+     * to @p base, separated by a dash.  Falls back to @p base unchanged when
+     * the env var is empty.
+     */
+    static QString perUserSocketName(const QString &base);
+
+    /**
+     * @brief Asynchronously resolve our startup role.
+     *
+     * - If @p maybeUrl is non-empty AND a primary instance is already
+     *   running, forward the URL to it and emit @c roleResolved(true).
+     * - Otherwise (no URL, OR no primary, OR primary unresponsive within
+     *   @c ForwardTimeoutMs), become the primary instance and emit
+     *   @c roleResolved(false).
+     *
+     * Emits @c roleResolved exactly once.  Intended to be called at most
+     * once at process startup, before @c QApplication::exec().
+     */
+    void resolveStartupRole(const QString &maybeUrl);
+
+signals:
+    /** Emitted exactly once after resolveStartupRole completes.
+     *  @param forwarded true if a primary existed and we sent the URL to it
+     *                   (caller should exit); false if we are now primary. */
+    void roleResolved(bool forwarded);
+
+    /** Emitted on the primary instance whenever another instance sends a URL. */
+    void urlReceived(const QString &url);
+
+private slots:
+    void onNewConnection();
+
+private:
+    QString socketName;
+    QLocalServer *server{nullptr};
+
+    /** Listen on @c socketName.  Idempotent — safe to call once we've been
+     *  resolved as the primary. */
+    void becomePrimary();
+
+    /** Read the URL from @p socket and emit @c urlReceived, then ACK. */
+    void processConnection(QLocalSocket *socket);
+};
+
+#endif // LIBCOCKATRICE_SINGLE_INSTANCE_MANAGER_H

libcockatrice_utility/libcockatrice/utility/url_utils.h

@@ -0,0 +1,136 @@
+#ifndef LIBCOCKATRICE_URL_UTILS_H
+#define LIBCOCKATRICE_URL_UTILS_H
+
+#include <QStringList>
+#include <QUrl>
+#include <QUrlQuery>
+#include <optional>
+
+namespace UrlUtils
+{
+
+/**
+ * @brief Scans @p args and returns the first entry that starts with
+ *        @p schemePrefix (case-insensitive, per RFC 3986), or an empty string
+ *        if none is found.  Only the first match is returned; subsequent
+ *        matching args are ignored.
+ *
+ * Use this to extract a custom-scheme URL from QCommandLineParser positional
+ * arguments or raw argv arrays.
+ */
+inline QString findUrlArgument(const QStringList &args, const QString &schemePrefix)
+{
+    for (const QString &arg : args) {
+        if (arg.startsWith(schemePrefix, Qt::CaseInsensitive))
+            return arg;
+    }
+    return {};
+}
+
+/**
+ * @brief Parsed shape of a cockatrice-oracle:// URL.
+ *
+ * Currently only @c update is recognised; other hosts are ignored.
+ */
+struct OracleUrlAction
+{
+    bool isUpdate{false};
+    bool spoilersOnly{false};
+};
+
+/**
+ * @brief Parse a cockatrice-oracle:// URL into an OracleUrlAction.
+ *
+ * Recognised forms:
+ *   cockatrice-oracle://update
+ *   cockatrice-oracle://update?spoilers=1
+ *
+ * Returns a default-constructed action (@c isUpdate == false) for any URL
+ * whose host is not @c update.  Host matching is case-insensitive.
+ */
+inline OracleUrlAction parseOracleUrl(const QString &url)
+{
+    OracleUrlAction action;
+    const QUrl parsed(url);
+    if (parsed.host().toLower() != QStringLiteral("update"))
+        return action;
+    action.isUpdate = true;
+    action.spoilersOnly = QUrlQuery(parsed.query()).queryItemValue(QStringLiteral("spoilers")) == QStringLiteral("1");
+    return action;
+}
+
+/**
+ * @brief Parsed parameters from a cockatrice://joingame URL.
+ */
+struct JoinGameUrlParams
+{
+    QString hostname;
+    quint16 port;
+    int roomId;
+    int gameId;
+    bool spectator;
+};
+
+/**
+ * @brief Parse a cockatrice://joingame URL into its parameters.
+ *
+ * Recognised forms:
+ *   cockatrice://joingame?hostname=H&port=P&roomid=R&gameid=G
+ *   cockatrice://joingame?hostname=H&port=P&roomid=R&gameid=G&spectate=1
+ *
+ * Validation:
+ *   - scheme must be "cockatrice" (case-insensitive)
+ *   - host must be "joingame" (case-insensitive)
+ *   - hostname query param required
+ *   - port required, 1..65535
+ *   - roomid required, >= 0
+ *   - gameid required, >= 0
+ *   - spectate=1 sets spectator true; any other value (including absence) is false
+ *
+ * Credentials in the query (username/password) are intentionally ignored.
+ *
+ * @return std::nullopt for unrecognised or malformed URLs.
+ */
+inline std::optional<JoinGameUrlParams> parseJoinGameUrl(const QString &url)
+{
+    const QUrl parsed(url);
+    if (!parsed.isValid())
+        return std::nullopt;
+    if (parsed.scheme().toLower() != QStringLiteral("cockatrice"))
+        return std::nullopt;
+    if (parsed.host().toLower() != QStringLiteral("joingame"))
+        return std::nullopt;
+
+    const QUrlQuery query(parsed.query());
+
+    const QString hostname = query.queryItemValue(QStringLiteral("hostname"));
+    if (hostname.isEmpty())
+        return std::nullopt;
+
+    bool portOk = false;
+    const uint portVal = query.queryItemValue(QStringLiteral("port")).toUInt(&portOk);
+    if (!portOk || portVal == 0 || portVal > 65535)
+        return std::nullopt;
+
+    bool roomOk = false;
+    const int roomId = query.queryItemValue(QStringLiteral("roomid")).toInt(&roomOk);
+    if (!roomOk || roomId < 0)
+        return std::nullopt;
+
+    bool gameOk = false;
+    const int gameId = query.queryItemValue(QStringLiteral("gameid")).toInt(&gameOk);
+    if (!gameOk || gameId < 0)
+        return std::nullopt;
+
+    JoinGameUrlParams params;
+    params.hostname = hostname;
+    params.port = static_cast<quint16>(portVal);
+    params.roomId = roomId;
+    params.gameId = gameId;
+    params.spectator = query.queryItemValue(QStringLiteral("spectate")) == QStringLiteral("1");
+    return params;
+}
+
+} // namespace UrlUtils
+
+#endif // LIBCOCKATRICE_URL_UTILS_H