Phase 1 sub-commit 6: skeleton wiring — make dev runs end-to-end

Symfony app under framework/skeleton/symfony/: minimal bin/console,
public/index.php, MicroKernel-based src/Kernel.php, services.yaml,
framework/security/mercure config, and a demo App\Controller\PingController
that GETs /api/ping (returning JSON pong) and republishes the same
payload to the Mercure topic app://ping. composer.json uses a path
repository to symlink the bundle from ../../php so local edits are
picked up live.

QML app under framework/skeleton/qml/: top-level CMake that
add_subdirectory's framework/qml, a main.cpp that creates the Qt
process, runs SingleInstance.acquireOrForward before any QML loads,
exposes SingleInstance via context property, and loadFromModule's
Skeleton.Main. Main.qml uses BackendConnection / RestClient /
MercureClient from PhpQml.Bridge and renders status dots, a Ping
button, and an event log.

Caddyfile binds 127.0.0.1:8765, enables in-memory Mercure with a
256-bit dev JWT (matches symfony/.env, lcobucci/jwt requires this).
Makefile wraps build / dev / doctor / clean; scripts/dev.sh starts
FrankenPHP --watch and the Qt host together with explicit PID-based
teardown (process-group `kill 0` proved unreliable when frankenphp's
watch fork reparented).

Bug fixes uncovered in this sub-commit:
- SingleInstance.acquireOrForward: probe-first, then removeServer +
  retry-listen. The original loop-with-removeServer-after-failed-bind
  silently exited on stale sockets from prior runs.
- Main.qml: MercureClient does NOT inherit BackendConnection.token —
  Mercure subscribes anonymously in dev (Caddyfile), and forwarding
  the bridge bearer made it 401-loop.
- /api/ping was 500ing because the dev MERCURE_JWT_SECRET was 144 bits;
  bumped to 64-char (>=256 bit) to satisfy lcobucci/jwt.
- Linked the framework lib (php_qml_bridge) explicitly in addition to
  the QML plugin so SingleInstance.h resolves.
- Auto-generated config/reference.php gitignored.

Smoke verified offscreen: /healthz 200, /api/ping 200, 1 publish, 1
subscriber, zero 401s, clean shutdown with no zombies.

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

.gitignore

@@ -20,6 +20,8 @@ framework/php/composer.lock
 .env.local
 .env.*.local
 .env.local.php
+# Auto-generated Symfony config typings (regenerated on every install).
+**/config/reference.php
 
 # Qt / CMake intermediates
 CMakeCache.txt

framework/qml/src/SingleInstance.cpp

@@ -31,14 +31,10 @@ bool SingleInstance::acquireOrForward(const QStringList& launchArgs)
 {
     const QString name = endpointName();
 
-    for (int attempt = 0; attempt < kBindRetries; ++attempt) {
+    // Probe first: if a live instance answers, forward and exit.
-        if (m_server.listen(name)) {
+    // This avoids a race where eagerly calling removeServer() would break
-            return true;  // we are the live instance
+    // a running peer.
-        }
+    {
-
-        // Bind failed. Either a real instance is running (forward args), or
-        // a stale socket/pipe is left over from a crashed process (clean up
-        // and retry). Distinguish by trying to connect.
         QLocalSocket probe;
         probe.connectToServer(name);
         if (probe.waitForConnected(kForwardConnectTimeoutMs)) {
@@ -50,16 +46,24 @@ bool SingleInstance::acquireOrForward(const QStringList& launchArgs)
             probe.disconnectFromServer();
             return false;
         }
+    }
 
-        // No live peer responding — likely stale socket. Remove and retry
+    // No live peer answered. The endpoint may not exist, or a stale
-        // with a brief backoff (PLAN.md §3 *Edge cases — Single-instance
+    // file is left over from a crashed process — removeServer() handles
-        // launch race*).
+    // both cases safely.
-        QLocalServer::removeServer(name);
+    QLocalServer::removeServer(name);
+
+    for (int attempt = 0; attempt < kBindRetries; ++attempt) {
+        if (m_server.listen(name)) {
+            return true;
+        }
         QThread::msleep(kBindRetryDelayMs);
     }
 
-    // Exhausted retries without binding and without a live peer. Better to
+    // Exhausted retries — better to continue as a degraded "live" instance
-    // act as the live instance than to deadlock both processes into exiting.
+    // than to deadlock-exit (PLAN.md §3 *Edge cases — Single-instance
+    // launch race*). Subsequent invocations may not be forwarded, but
+    // this process will still run.
     return true;
 }
 

framework/skeleton/Caddyfile

@@ -1,3 +1,36 @@
-# Placeholder Caddyfile. Populated in Phase 1 sub-commit 6 alongside
+# php-qml framework skeleton — FrankenPHP / Caddy / Mercure config (dev mode).
-# the Symfony app at framework/skeleton/symfony/. See PLAN.md §13,
+#
-# Phase 1, "Skeleton wiring".
+# Run from the skeleton/symfony/ directory so relative `php_server` paths
+# resolve correctly: cd framework/skeleton/symfony && frankenphp run --watch
+# --config ../Caddyfile.
+{
+	auto_https off
+	admin off
+	frankenphp
+	order php_server before respond
+	order mercure after encode
+}
+
+http://127.0.0.1:8765 {
+	root * public/
+	encode gzip
+
+	mercure {
+		transport local
+		# Must match MERCURE_JWT_SECRET in symfony/.env. lcobucci/jwt
+		# requires >= 256 bits, hence the long dev value.
+		publisher_jwt dev_php_qml_bridge_jwt_secret_at_least_256_bits_long_for_lcobucci
+		subscriber_jwt dev_php_qml_bridge_jwt_secret_at_least_256_bits_long_for_lcobucci
+		anonymous
+		publish_origins *
+		cors_origins *
+	}
+
+	php_server
+
+	log {
+		output stderr
+		format console
+	}
+}
+}

framework/skeleton/Makefile

@@ -1,21 +1,40 @@
 # php-qml framework skeleton — Make targets.
-# Filled in across Phase 1 sub-commits 3, 6, and 7.
 
 .DEFAULT_GOAL := help
 
+SYMFONY_DIR  := symfony
+QML_SRC_DIR  := qml
+BUILD_DIR    := build/qml
+QT_BIN       := $(BUILD_DIR)/skeleton
+
 .PHONY: help
 help: ## Show available targets
 	@awk 'BEGIN {FS = ":.*?## "} /^[a-zA-Z_-]+:.*?## / {printf "  %-12s %s\n", $$1, $$2}' $(MAKEFILE_LIST)
 
+.PHONY: install
+install: ## Install Composer dependencies for the Symfony app
+	cd $(SYMFONY_DIR) && composer install
+
+.PHONY: build
+build: ## Build the Qt host
+	cmake -S $(QML_SRC_DIR) -B $(BUILD_DIR) -DCMAKE_BUILD_TYPE=Debug
+	cmake --build $(BUILD_DIR) --parallel
+
 .PHONY: dev
-dev: ## (TBD) Run the skeleton in dev mode (FrankenPHP --watch + Qt host)
+dev: build ## Run skeleton in dev mode (FrankenPHP --watch + Qt host)
-	@echo "dev: not yet implemented (Phase 1 sub-commit 6)"
+	./scripts/dev.sh
-	@exit 1
 
 .PHONY: doctor
-doctor: ## (TBD) Run bridge:doctor against the running backend
+doctor: ## Run bridge:doctor inside the Symfony app
-	@echo "doctor: not yet implemented (Phase 1 sub-commit 3)"
+	cd $(SYMFONY_DIR) && bin/console bridge:doctor
-	@exit 1
+
+.PHONY: doctor-connect
+doctor-connect: ## Run bridge:doctor with backend connectivity probe
+	cd $(SYMFONY_DIR) && bin/console bridge:doctor --connect
+
+.PHONY: clean
+clean: ## Remove build artefacts
+	rm -rf $(BUILD_DIR)
 
 .PHONY: quality
 quality: ## (TBD) Run PHPStan, php-cs-fixer (check), PHPUnit, qmllint

framework/skeleton/qml/CMakeLists.txt

@@ -0,0 +1,32 @@
+cmake_minimum_required(VERSION 3.21)
+project(php_qml_skeleton LANGUAGES CXX)
+
+set(CMAKE_CXX_STANDARD 20)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+set(CMAKE_AUTOMOC ON)
+
+find_package(Qt6 6.5 REQUIRED COMPONENTS Core Gui Quick QuickControls2 Network Qml)
+qt_standard_project_setup(REQUIRES 6.5)
+
+# Pull in the framework's QML module (PhpQml.Bridge) as a static library +
+# QML plugin. The plugin auto-imports its types into any QQmlEngine.
+add_subdirectory(${CMAKE_CURRENT_SOURCE_DIR}/../../qml ${CMAKE_BINARY_DIR}/php_qml_bridge)
+
+qt_add_executable(skeleton main.cpp)
+
+qt_add_qml_module(skeleton
+    URI Skeleton
+    VERSION 1.0
+    QML_FILES Main.qml
+)
+
+target_link_libraries(skeleton PRIVATE
+    Qt6::Core
+    Qt6::Gui
+    Qt6::Quick
+    Qt6::QuickControls2
+    Qt6::Network
+    Qt6::Qml
+    php_qml_bridge
+    php_qml_bridgeplugin
+)

framework/skeleton/qml/Main.qml

@@ -0,0 +1,132 @@
+import QtQuick
+import QtQuick.Controls
+import QtQuick.Layouts
+import QtQuick.Window
+
+import PhpQml.Bridge
+
+ApplicationWindow {
+    id: window
+    width: 760
+    height: 540
+    visible: true
+    title: "php-qml — skeleton"
+
+    RestClient {
+        id: rest
+        baseUrl: BackendConnection.url
+        token: BackendConnection.token
+    }
+
+    MercureClient {
+        id: mercure
+        hubUrl: BackendConnection.url + "/.well-known/mercure"
+        topic: "app://ping"
+        // No token in Phase 1 dev mode — Caddyfile enables `anonymous`
+        // for Mercure subscribers. Phase 4 swaps in a Mercure-issued JWT
+        // when the bundled mode tightens auth.
+        onUpdate: function(data, id) {
+            log.append("← mercure " + (id ? id.split(":").pop() : "") + "  " + data)
+        }
+        onError: function(detail) {
+            log.append("× mercure error: " + detail)
+        }
+    }
+
+    Connections {
+        target: BackendConnection
+        function onConnectionStateChanged() {
+            if (BackendConnection.connectionState === BackendConnection.Online) {
+                if (!mercure.active) mercure.start()
+            } else {
+                if (mercure.active) mercure.stop()
+            }
+        }
+    }
+
+    Connections {
+        target: SingleInstance
+        function onLaunchArgsReceived(args) {
+            window.requestActivate()
+            log.append("· launch args from peer: " + args.join(" "))
+        }
+    }
+
+    ColumnLayout {
+        anchors.fill: parent
+        anchors.margins: 16
+        spacing: 12
+
+        RowLayout {
+            spacing: 10
+            Layout.fillWidth: true
+
+            Rectangle {
+                width: 12; height: 12; radius: 6
+                color: BackendConnection.connectionState === BackendConnection.Online
+                       ? "#3ab36c"
+                       : (BackendConnection.connectionState === BackendConnection.Error ? "#d8503c" : "#d89614")
+            }
+            Label { text: "Backend: " + window._stateName(BackendConnection.connectionState) }
+
+            Item { width: 12 }
+
+            Rectangle {
+                width: 12; height: 12; radius: 6
+                color: mercure.active ? "#3ab36c" : "#666"
+            }
+            Label { text: "Mercure: " + (mercure.active ? "subscribed" : "off") }
+
+            Item { Layout.fillWidth: true }
+
+            Button {
+                text: "Ping"
+                enabled: BackendConnection.connectionState === BackendConnection.Online
+                onClicked: {
+                    const t0 = Date.now()
+                    rest.get("/api/ping").then(function(r) {
+                        const dt = Date.now() - t0
+                        log.append("→ ping " + dt + "ms  " + JSON.stringify(r.body))
+                    }).catch(function(e) {
+                        log.append("× ping " + e.status + "  " + JSON.stringify(e.problem || e.raw))
+                    })
+                }
+            }
+        }
+
+        Label {
+            text: "URL: " + BackendConnection.url
+                  + (BackendConnection.error ? "    error: " + BackendConnection.error : "")
+            color: BackendConnection.error ? "#d8503c" : "#888"
+            font.pixelSize: 12
+            elide: Text.ElideRight
+            Layout.fillWidth: true
+        }
+
+        Frame {
+            Layout.fillWidth: true
+            Layout.fillHeight: true
+            padding: 0
+            ScrollView {
+                anchors.fill: parent
+                TextArea {
+                    id: log
+                    readOnly: true
+                    wrapMode: TextArea.Wrap
+                    font.family: "monospace"
+                    font.pixelSize: 12
+                    placeholderText: "events will appear here…"
+                }
+            }
+        }
+    }
+
+    function _stateName(s) {
+        switch (s) {
+            case BackendConnection.Connecting: return "connecting"
+            case BackendConnection.Online:     return "online"
+            case BackendConnection.Error:      return "error"
+        }
+        return "?"
+    }
+}

framework/skeleton/qml/main.cpp

@@ -0,0 +1,29 @@
+#include <QGuiApplication>
+#include <QQmlApplicationEngine>
+#include <QQmlContext>
+#include <QStringList>
+
+#include "SingleInstance.h"
+
+int main(int argc, char *argv[])
+{
+    QGuiApplication app(argc, argv);
+    QGuiApplication::setOrganizationName(QStringLiteral("php-qml"));
+    QGuiApplication::setApplicationName(QStringLiteral("skeleton"));
+
+    PhpQml::Bridge::SingleInstance singleInstance(QStringLiteral("skeleton"));
+    if (!singleInstance.acquireOrForward(app.arguments())) {
+        // Forwarded args to the running instance; nothing to do here.
+        return 0;
+    }
+
+    QQmlApplicationEngine engine;
+    engine.rootContext()->setContextProperty(QStringLiteral("SingleInstance"), &singleInstance);
+    engine.loadFromModule("Skeleton", "Main");
+
+    if (engine.rootObjects().isEmpty()) {
+        return 1;
+    }
+
+    return app.exec();
+}

framework/skeleton/scripts/dev.sh

@@ -0,0 +1,64 @@
+#!/usr/bin/env bash
+# Start the dev backend (FrankenPHP --watch) and the Qt host together,
+# tearing both down on Ctrl-C / exit / SIGTERM via process-group kill.
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+SKELETON_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
+SYMFONY_DIR="$SKELETON_DIR/symfony"
+QT_BIN="$SKELETON_DIR/build/qml/skeleton"
+
+: "${FRANKENPHP:=frankenphp}"
+: "${BRIDGE_URL:=http://127.0.0.1:8765}"
+: "${BRIDGE_TOKEN:=devtoken}"
+
+if [ ! -x "$QT_BIN" ]; then
+    echo "Qt host not built. Run 'make build' first." >&2
+    exit 1
+fi
+if ! command -v "$FRANKENPHP" >/dev/null 2>&1; then
+    echo "frankenphp not on PATH. Set FRANKENPHP=/path/to/frankenphp or install it." >&2
+    exit 1
+fi
+
+# Explicit PID-based teardown: SIGTERM the children, give them 2s,
+# then SIGKILL anything still alive. process-group `kill 0` proved
+# unreliable when FrankenPHP's --watch fork was reparented.
+FRANKEN_PID=""
+QT_PID=""
+cleanup() {
+    trap - EXIT INT TERM
+    for pid in "$QT_PID" "$FRANKEN_PID"; do
+        [ -n "$pid" ] || continue
+        kill -0 "$pid" 2>/dev/null || continue
+        kill -TERM "$pid" 2>/dev/null || true
+        for _ in 1 2 3 4 5 6 7 8 9 10; do
+            kill -0 "$pid" 2>/dev/null || break
+            sleep 0.2
+        done
+        kill -KILL "$pid" 2>/dev/null || true
+    done
+}
+trap cleanup EXIT INT TERM
+
+(cd "$SYMFONY_DIR" && exec "$FRANKENPHP" run --watch --config ../Caddyfile) &
+FRANKEN_PID=$!
+echo "frankenphp PID=$FRANKEN_PID"
+
+# Wait for the backend to come up. Bail if FrankenPHP dies early.
+for _ in $(seq 1 50); do
+    if curl -fsS -m 1 "$BRIDGE_URL/healthz" >/dev/null 2>&1; then
+        break
+    fi
+    if ! kill -0 "$FRANKEN_PID" 2>/dev/null; then
+        echo "frankenphp died before becoming ready" >&2
+        exit 1
+    fi
+    sleep 0.2
+done
+
+BRIDGE_URL="$BRIDGE_URL" BRIDGE_TOKEN="$BRIDGE_TOKEN" "$QT_BIN" &
+QT_PID=$!
+
+wait "$QT_PID"

framework/skeleton/symfony/.env

@@ -0,0 +1,17 @@
+APP_ENV=dev
+APP_DEBUG=1
+APP_SECRET=dev-secret-not-for-production-use
+
+# Mercure hub (FrankenPHP-built-in). Both URLs are typically the same in
+# dev mode where the hub and the app are colocated.
+MERCURE_URL=http://127.0.0.1:8765/.well-known/mercure
+MERCURE_PUBLIC_URL=http://127.0.0.1:8765/.well-known/mercure
+# Used by mercure-bundle to mint publisher JWTs. Must match the
+# publisher_jwt secret in ../Caddyfile. lcobucci/jwt requires HMAC
+# secrets to be at least 256 bits, so the dev value here is 64 chars.
+MERCURE_JWT_SECRET=dev_php_qml_bridge_jwt_secret_at_least_256_bits_long_for_lcobucci
+MERCURE_PUBLISHER_JWT_KEY=dev_php_qml_bridge_jwt_secret_at_least_256_bits_long_for_lcobucci
+MERCURE_SUBSCRIBER_JWT_KEY=dev_php_qml_bridge_jwt_secret_at_least_256_bits_long_for_lcobucci
+
+# Bearer token the Qt host sends on /api/* requests.
+BRIDGE_TOKEN=devtoken

framework/skeleton/symfony/bin/console

@@ -0,0 +1,17 @@
+#!/usr/bin/env php
+<?php
+
+use App\Kernel;
+use Symfony\Bundle\FrameworkBundle\Console\Application;
+
+if (!is_file(dirname(__DIR__).'/vendor/autoload_runtime.php')) {
+    fwrite(STDERR, "Vendor autoload missing. Run `composer install` in the skeleton/symfony dir first.\n");
+    exit(1);
+}
+
+require_once dirname(__DIR__).'/vendor/autoload_runtime.php';
+
+return function (array $context): Application {
+    $kernel = new Kernel($context['APP_ENV'], (bool) $context['APP_DEBUG']);
+    return new Application($kernel);
+};

framework/skeleton/symfony/composer.json

@@ -0,0 +1,39 @@
+{
+    "type": "project",
+    "license": "proprietary",
+    "minimum-stability": "stable",
+    "require": {
+        "php": "^8.3",
+        "symfony/framework-bundle": "^8.0",
+        "symfony/runtime": "^8.0",
+        "symfony/dotenv": "^8.0",
+        "symfony/yaml": "^8.0",
+        "symfony/security-bundle": "^8.0",
+        "symfony/mercure-bundle": "^0.4",
+        "php-qml/bridge": "@dev"
+    },
+    "autoload": {
+        "psr-4": {
+            "App\\": "src/"
+        }
+    },
+    "config": {
+        "allow-plugins": {
+            "symfony/runtime": true
+        }
+    },
+    "extra": {
+        "runtime": {
+            "class": "Symfony\\Component\\Runtime\\SymfonyRuntime"
+        }
+    },
+    "repositories": [
+        {
+            "type": "path",
+            "url": "../../php",
+            "options": {
+                "symlink": true
+            }
+        }
+    ]
+}

framework/skeleton/symfony/config/bundles.php

@@ -0,0 +1,8 @@
+<?php
+
+return [
+    Symfony\Bundle\FrameworkBundle\FrameworkBundle::class => ['all' => true],
+    Symfony\Bundle\SecurityBundle\SecurityBundle::class => ['all' => true],
+    Symfony\Bundle\MercureBundle\MercureBundle::class => ['all' => true],
+    PhpQml\Bridge\BridgeBundle::class => ['all' => true],
+];

framework/skeleton/symfony/config/packages/framework.yaml

@@ -0,0 +1,9 @@
+framework:
+    secret: '%env(APP_SECRET)%'
+    http_method_override: false
+    handle_all_throwables: true
+    php_errors:
+        log: true
+    router:
+        utf8: true
+    test: false

framework/skeleton/symfony/config/packages/mercure.yaml

@@ -0,0 +1,9 @@
+mercure:
+    hubs:
+        default:
+            url: '%env(MERCURE_URL)%'
+            public_url: '%env(MERCURE_PUBLIC_URL)%'
+            jwt:
+                secret: '%env(MERCURE_JWT_SECRET)%'
+                publish: ['*']
+                subscribe: ['*']

framework/skeleton/symfony/config/packages/security.yaml

@@ -0,0 +1,18 @@
+security:
+    providers:
+        bridge_provider:
+            memory:
+                users:
+                    bridge: { roles: ['ROLE_BRIDGE'] }
+    firewalls:
+        unauth:
+            pattern: ^/(healthz|\.well-known/mercure)
+            security: false
+        api:
+            pattern: ^/api
+            stateless: true
+            provider: bridge_provider
+            custom_authenticators:
+                - PhpQml\Bridge\SessionAuthenticator
+    access_control:
+        - { path: ^/api, roles: ROLE_BRIDGE }

framework/skeleton/symfony/config/routes.yaml

@@ -0,0 +1,11 @@
+php_qml_bridge:
+    resource:
+        path: ../vendor/php-qml/bridge/src/Controller/
+        namespace: PhpQml\Bridge\Controller
+    type: attribute
+
+app_controllers:
+    resource:
+        path: ../src/Controller/
+        namespace: App\Controller
+    type: attribute

framework/skeleton/symfony/config/services.yaml

@@ -0,0 +1,11 @@
+parameters:
+
+services:
+    _defaults:
+        autowire: true
+        autoconfigure: true
+
+    App\:
+        resource: '../src/'
+        exclude:
+            - '../src/Kernel.php'

framework/skeleton/symfony/public/index.php

@@ -0,0 +1,9 @@
+<?php
+
+use App\Kernel;
+
+require_once dirname(__DIR__).'/vendor/autoload_runtime.php';
+
+return function (array $context): Kernel {
+    return new Kernel($context['APP_ENV'], (bool) $context['APP_DEBUG']);
+};

framework/skeleton/symfony/src/Controller/PingController.php

@@ -0,0 +1,32 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Controller;
+
+use PhpQml\Bridge\Publisher;
+use Symfony\Component\HttpFoundation\JsonResponse;
+use Symfony\Component\Routing\Attribute\Route;
+
+/**
+ * Demo endpoint: returns a JSON pong AND republishes it on the Mercure
+ * topic `app://ping`. Lets the skeleton's QML window prove both
+ * transport channels (HTTP + SSE) round-trip end-to-end.
+ *
+ * Removed once Phase 2's reactive models supersede the demo.
+ */
+final class PingController
+{
+    public function __construct(
+        private readonly Publisher $publisher,
+    ) {
+    }
+
+    #[Route('/api/ping', name: 'app_ping', methods: ['GET'])]
+    public function __invoke(): JsonResponse
+    {
+        $payload = ['pong' => true, 'now' => date('c')];
+        $this->publisher->publish('app://ping', $payload);
+        return new JsonResponse($payload);
+    }
+}

framework/skeleton/symfony/src/Kernel.php

@@ -0,0 +1,13 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App;
+
+use Symfony\Bundle\FrameworkBundle\Kernel\MicroKernelTrait;
+use Symfony\Component\HttpKernel\Kernel as BaseKernel;
+
+final class Kernel extends BaseKernel
+{
+    use MicroKernelTrait;
+}