@p10i/create-nestbox 0.1.0

package/docker/php-fpm/Dockerfile

@@ -0,0 +1,43 @@
+# syntax=docker/dockerfile:1.7
+
+# ---- Stage 1: install PHP dependencies with Composer ----
+FROM composer:latest AS vendor
+
+WORKDIR /build
+COPY ./home/configs/php/composer.json ./composer.json
+COPY ./home/configs/php/composer.lock ./composer.lock
+RUN composer install --no-interaction --prefer-dist --optimize-autoloader --no-dev
+
+# ---- Stage 2: runtime ----
+FROM php:fpm-alpine
+
+ARG APP_UID=1000
+ARG APP_GID=1000
+
+# Required system + PHP extensions.
+RUN apk add --no-cache --virtual .build-deps $PHPIZE_DEPS libzip-dev && \
+    apk add --no-cache libzip && \
+    docker-php-ext-install zip && \
+    apk del .build-deps
+
+# PHP config.
+COPY ./home/configs/php/php.ini /usr/local/etc/php/conf.d/custom.ini
+
+# Vendor dir from stage 1.
+COPY --from=vendor /build/vendor /vendor
+COPY ./home/configs/php/composer.json /composer.json
+COPY ./home/configs/php/composer.lock /composer.lock
+
+# Application source.
+COPY ./home/configs/php /sources/php
+COPY ./home/code /home/code
+
+# Run as a non-root, non-default user. UID/GID are passed as build args so
+# they can match the host user when bind-mounting in development, avoiding
+# the classic "files owned by root after compose down" annoyance on Linux.
+RUN addgroup -g "${APP_GID}" -S nestbox && \
+    adduser  -u "${APP_UID}" -G nestbox -S -H nestbox && \
+    sed -i "s/^user = .*/user = nestbox/; s/^group = .*/group = nestbox/" /usr/local/etc/php-fpm.d/www.conf && \
+    chown -R nestbox:nestbox /home/code /sources/php /vendor
+
+USER nestbox

package/docker/rollup/Dockerfile

@@ -0,0 +1,16 @@
+FROM node:alpine
+
+ARG APP_UID=1000
+ARG APP_GID=1000
+
+RUN apk add --no-cache shadow && \
+    if [ "$(id -u node)" != "$APP_UID" ]; then usermod -u "$APP_UID" node; fi && \
+    if [ "$(id -g node)" != "$APP_GID" ]; then groupmod -g "$APP_GID" node; fi
+
+COPY ./home/code /home/code
+COPY ./home/configs/rollup /sources/rollup
+
+WORKDIR /sources/rollup
+RUN npm ci --no-audit --no-fund && chown -R node:node /home/code /sources/rollup
+
+USER node

package/docker-compose.yaml

@@ -0,0 +1,139 @@
+# Complete local Nestbox runtime. The installer configures paths, ownership,
+# credentials, and the shared browser port through .env.
+services:
+  # Single browser gateway. The ordinary host serves Nestbox, while agent.*
+  # virtual hosts proxy the internal OpenCode server.
+  nginx:
+    build:
+      context: .
+      dockerfile: ./docker/nginx/Dockerfile
+    depends_on:
+      - php-fpm
+      - opencode
+    ports:
+      # Nestbox and OpenCode share one confirmed host port.
+      - "${BIND_ADDRESS:-127.0.0.1}:${WEB_PORT:-4180}:80"
+    expose:
+      # Internal Nchan publisher only; never publish this port on the host.
+      - "8080"
+    volumes:
+      # Nginx only reads pages and generated browser assets.
+      - type: bind
+        source: ${NESTBOX_PAGE_PATH:-./home/code}
+        target: /var/www/html
+        read_only: true
+        bind:
+          create_host_path: false
+      - ./home/configs/nginx/nginx.conf:/etc/nginx/nginx.conf:ro
+    healthcheck:
+      # The endpoint passes through PHP, checking both Nginx and PHP-FPM.
+      test: ["CMD", "wget", "-q", "--spider", "http://127.0.0.1/_nestbox/health"]
+      interval: 10s
+      timeout: 3s
+      retries: 5
+      start_period: 10s
+    restart: unless-stopped
+
+  # Executes super-document HTTP and CLI directions. Trusted pages may update
+  # page state and intentionally operate on the mounted workspace.
+  php-fpm:
+    build:
+      context: .
+      dockerfile: ./docker/php-fpm/Dockerfile
+      args:
+        APP_UID: ${APP_UID:-1000}
+        APP_GID: ${APP_GID:-1000}
+    volumes:
+      # Routers and PHP configuration are source, not writable state.
+      - ./home/configs/php:/sources/php:ro
+      - type: bind
+        source: ${NESTBOX_PAGE_PATH:-./home/code}
+        target: /home/code
+        bind:
+          create_host_path: false
+      - type: bind
+        source: ${WORKSPACE_PATH:-.}
+        target: /workspace
+        bind:
+          create_host_path: false
+    environment:
+      # Event publication and OpenCode automation stay inside Compose.
+      - NESTBOX_BUS_PUBLISH_URL=http://nginx:8080/_nestbox/publish
+      - NESTBOX_URL_PREFIX=${NESTBOX_URL_PREFIX:-}
+      - NESTBOX_OPENCODE_URL=http://opencode:4096
+      - NESTBOX_OPENCODE_PUBLIC_URL=${NESTBOX_OPENCODE_PUBLIC_URL:-}
+      - OPENCODE_SERVER_USERNAME=${OPENCODE_SERVER_USERNAME:-opencode}
+      - OPENCODE_SERVER_PASSWORD=${OPENCODE_SERVER_PASSWORD:-}
+    restart: unless-stopped
+
+  # Watches shared browser source and refreshes tracked bundle baselines.
+  # Dependencies are installed in the image, so startup does not need npm ci.
+  rollup:
+    build:
+      context: .
+      dockerfile: ./docker/rollup/Dockerfile
+      args:
+        APP_UID: ${APP_UID:-1000}
+        APP_GID: ${APP_GID:-1000}
+    user: "${APP_UID:-1000}:${APP_GID:-1000}"
+    working_dir: /sources/rollup
+    command: npm run rollup -- --watch
+    volumes:
+      # Configuration changes are valid agent work but require an image rebuild.
+      - ./home/configs/rollup:/sources/rollup
+      - type: bind
+        source: ${NESTBOX_PAGE_PATH:-./home/code}
+        target: /home/code
+        bind:
+          create_host_path: false
+      # Keep dependencies out of the host page tree.
+      - rollup-node-modules:/sources/rollup/node_modules
+    restart: unless-stopped
+
+  # Internal implementation agent. It can edit Nestbox and the workspace but
+  # deliberately receives no Docker socket or direct host control.
+  opencode:
+    build:
+      context: .
+      dockerfile: ./docker/opencode/Dockerfile
+      args:
+        APP_UID: ${APP_UID:-1000}
+        APP_GID: ${APP_GID:-1000}
+    env_file:
+      # Provider and OpenCode credentials are supplied to this service.
+      - .env
+    volumes:
+      # Agent and PHP tooling configuration remain read-only at runtime.
+      - ./home/configs/opencode:/etc/opencode:ro
+      - ./home/configs/php:/sources/php:ro
+      # Read-only page view used by PHP tooling inside the agent container.
+      - type: bind
+        source: ${NESTBOX_PAGE_PATH:-./home/code}
+        target: /home/code
+        read_only: true
+        bind:
+          create_host_path: false
+      # Writable installation and stable page-authoring paths.
+      - .:/nestbox
+      - type: bind
+        source: ${NESTBOX_PAGE_PATH:-./home/code}
+        target: /nestbox/home/code
+        bind:
+          create_host_path: false
+      - type: bind
+        source: ${WORKSPACE_PATH:-.}
+        target: /workspace
+        bind:
+          create_host_path: false
+      # The entrypoint fixes this volume's ownership before dropping privileges.
+      - opencode-data:/home/nestbox/.local/share/opencode
+    working_dir: /workspace
+    environment:
+      - NESTBOX_BUS_PUBLISH_URL=http://nginx:8080/_nestbox/publish
+    restart: unless-stopped
+
+volumes:
+  # Disposable dependency cache reconstructed from package-lock.json.
+  rollup-node-modules:
+  # OpenCode sessions retained across container recreation.
+  opencode-data:

package/home/code/.user.ini

@@ -0,0 +1 @@
+auto_prepend_file = /sources/php/init.php

package/home/code/404.php

@@ -0,0 +1,104 @@
+<?php
+declare(strict_types=1);
+
+// HTTP direction: preserve and validate the unresolved URI across the form POST.
+$method = strtoupper((string) ($_SERVER['REQUEST_METHOD'] ?? 'GET'));
+$rawRequestedUri = $method === 'POST'
+    ? (string) ($_POST['requested_uri'] ?? '')
+    : (string) ($_SERVER['NESTBOX_ORIGINAL_URI'] ?? $_SERVER['REQUEST_URI'] ?? '/');
+$pageContext = nestbox_page_context($rawRequestedUri);
+$requestedUri = $pageContext['requestedUri'] ?? '';
+$requestedPath = $pageContext['requestedPath'] ?? '';
+$agentDirectory = $pageContext['agentDirectory'] ?? '';
+
+if (PHP_SAPI === 'cli') {
+    echo "Implementation sessions are managed by OpenCode.\n";
+    exit;
+}
+
+$error = '';
+$submittedPrompt = '';
+
+if ($method === 'POST') {
+    if ($pageContext === null) {
+        http_response_code(422);
+        $error = 'This URI cannot map to a Nestbox super-document.';
+    } elseif (($_POST['action'] ?? '') !== 'start') {
+        http_response_code(400);
+        $error = 'Unknown form action.';
+    } else {
+        $submittedPrompt = trim((string) ($_POST['prompt'] ?? ''));
+        $singleLinePrompt = preg_replace('/\s+/u', ' ', $submittedPrompt);
+        $submittedPrompt = is_string($singleLinePrompt) ? $singleLinePrompt : '';
+
+        if (!is_string($singleLinePrompt)
+            || $singleLinePrompt === ''
+            || strlen($singleLinePrompt) > 4000
+            || preg_match('//u', $singleLinePrompt) !== 1
+        ) {
+            http_response_code(422);
+            $error = 'Enter a valid one-line UTF-8 request between 1 and 4,000 bytes.';
+        } else {
+            try {
+                // OpenCode scopes the new session to the directory where the
+                // requested super-document will live.
+                $localDirectory = '/home/code' . substr($agentDirectory, strlen('/nestbox/home/code'));
+                if (!is_dir($localDirectory) && !mkdir($localDirectory, 0775, true) && !is_dir($localDirectory)) {
+                    throw new RuntimeException('Nestbox could not create the super-document directory.');
+                }
+
+                $title = preg_match('/^.{0,72}/us', $singleLinePrompt, $titleMatch) === 1
+                    ? $titleMatch[0]
+                    : 'New page';
+                $session = nestbox_opencode_create_session('Nestbox ' . $requestedPath . ': ' . $title, $agentDirectory);
+                if (isset($session['directory'])
+                    && (!is_string($session['directory']) || $session['directory'] !== $agentDirectory)
+                ) {
+                    throw new RuntimeException('OpenCode created the session in an unexpected directory.');
+                }
+
+                $sessionId = (string) $session['id'];
+                $agentPrompt = 'Requested Nestbox page URI: ' . $requestedUri
+                    . '. Implement this route as a cohesive super-document under /nestbox/home/code, following /nestbox/home/configs/opencode/instructions.md. Do not modify unrelated projects under /workspace. Request: '
+                    . $singleLinePrompt;
+                nestbox_opencode_prompt_async($sessionId, $agentPrompt, '', $agentDirectory);
+
+                header('Location: ' . nestbox_opencode_session_url($sessionId, $agentDirectory), true, 303);
+                exit;
+            } catch (Throwable $exception) {
+                http_response_code(502);
+                $error = $exception->getMessage();
+            }
+        }
+    }
+} else {
+    http_response_code(404);
+}
+
+$formAction = nestbox_url_path('404');
+?>
+---
+title: Page not found
+---
+
+# Page not found
+
+Nestbox could not resolve `<?= nestbox_escape($requestedUri); ?>`.
+
+<?php if ($error !== ''): ?>
+<div class="alert alert-danger" role="alert"><?= nestbox_escape($error); ?></div>
+<?php endif; ?>
+
+<?php if ($pageContext !== null): ?>
+<form class="card card-body" method="post" action="<?= nestbox_escape($formAction); ?>" target="nestbox-opencode">
+  <input type="hidden" name="action" value="start">
+  <input type="hidden" name="requested_uri" value="<?= nestbox_escape($requestedUri); ?>">
+  <label class="form-label" for="prompt">Ask OpenCode to implement this page</label>
+  <input class="form-control" id="prompt" name="prompt" type="text" maxlength="4000" value="<?= nestbox_escape($submittedPrompt); ?>" required>
+  <div class="mt-3">
+    <button class="btn btn-primary" type="submit">Create and open session</button>
+  </div>
+</form>
+<?php else: ?>
+<div class="alert alert-secondary" role="status">This URI cannot map to a Nestbox super-document.</div>
+<?php endif; ?>

package/home/code/__data/.gitignore

@@ -0,0 +1,2 @@
+*
+!.gitignore

package/home/code/__includes/footer.php

@@ -0,0 +1,3 @@
+        </article>
+    </body>
+</html>

package/home/code/__includes/functions.php

@@ -0,0 +1,325 @@
+<?php
+declare(strict_types=1);
+
+/** Escape a value for HTML text or attribute output. */
+function nestbox_escape(mixed $value): string
+{
+    return htmlspecialchars((string) $value, ENT_QUOTES, 'UTF-8');
+}
+
+/** Encode a PHP value as a JSON literal that cannot terminate an inline script. */
+function nestbox_script_json(mixed $value): string
+{
+    return json_encode(
+        $value,
+        JSON_THROW_ON_ERROR | JSON_HEX_TAG | JSON_HEX_AMP | JSON_HEX_APOS | JSON_HEX_QUOT,
+    );
+}
+
+/** Return the configured normalized public URL prefix. */
+function nestbox_url_prefix(): string
+{
+    $value = getenv('NESTBOX_URL_PREFIX') ?: '';
+    $prefix = '/' . trim((string) $value, '/');
+
+    if ($prefix === '/') {
+        return '';
+    }
+    if (!preg_match('#^/(?:[A-Za-z0-9._~-]+(?:/[A-Za-z0-9._~-]+)*)$#', $prefix)) {
+        throw new UnexpectedValueException('NESTBOX_URL_PREFIX must contain only URL-safe path segments.');
+    }
+
+    return $prefix;
+}
+
+/** Build a prefix-aware URL path by encoding each path segment independently. */
+function nestbox_url_path(string ...$segments): string
+{
+    $path = implode('/', array_map('rawurlencode', $segments));
+    return nestbox_url_prefix() . '/' . $path;
+}
+
+/** Map a public URI to its page data and agent directory. */
+function nestbox_page_context(string $requestUri): ?array
+{
+    if ($requestUri === '' || preg_match('/[\r\n]/', $requestUri)) {
+        return null;
+    }
+    $path = parse_url($requestUri, PHP_URL_PATH);
+    $query = parse_url($requestUri, PHP_URL_QUERY);
+    $path = is_string($path) ? preg_replace('#/+#', '/', $path) : null;
+    if (!is_string($path) || !str_starts_with($path, '/') || str_starts_with($path, '//')) {
+        return null;
+    }
+
+    $route = trim($path, '/');
+    if ($route === '') {
+        $route = 'index';
+    }
+    $markdownDirection = str_ends_with(strtolower($route), '.md');
+    if ($markdownDirection) {
+        $route = substr($route, 0, -3);
+    }
+    if (!preg_match('#^[A-Za-z0-9/_-]+$#', $route)) {
+        return null;
+    }
+    foreach (explode('/', $route) as $segment) {
+        if (str_starts_with($segment, '__')) {
+            return null;
+        }
+    }
+
+    $routeDirectory = dirname($route);
+    $relativeDirectory = $routeDirectory === '.' ? '' : '/' . $routeDirectory;
+    return [
+        'requestedUri' => $path . (is_string($query) ? '?' . $query : ''),
+        'requestedPath' => $path,
+        'route' => $route,
+        'statePath' => '/home/code' . $relativeDirectory . '/__data/' . basename($route) . '.json',
+        'agentDirectory' => '/nestbox/home/code' . $relativeDirectory,
+    ];
+}
+
+/** Return the public OpenCode origin that corresponds to the current Nestbox host. */
+function nestbox_opencode_origin(): string
+{
+    $configuredOrigin = rtrim((string) getenv('NESTBOX_OPENCODE_PUBLIC_URL'), '/');
+    if ($configuredOrigin !== '') {
+        $parts = parse_url($configuredOrigin);
+        if (!is_array($parts)
+            || !isset($parts['scheme'], $parts['host'])
+            || !in_array(strtolower((string) $parts['scheme']), ['http', 'https'], true)
+            || isset($parts['user'])
+            || isset($parts['pass'])
+            || isset($parts['query'])
+            || isset($parts['fragment'])
+            || (isset($parts['path']) && $parts['path'] !== '')
+        ) {
+            throw new UnexpectedValueException('NESTBOX_OPENCODE_PUBLIC_URL must be an HTTP origin without credentials or a path.');
+        }
+
+        return $configuredOrigin;
+    }
+
+    $scheme = strtolower((string) ($_SERVER['REQUEST_SCHEME'] ?? 'http'));
+    if (!in_array($scheme, ['http', 'https'], true)) {
+        throw new UnexpectedValueException('The request scheme is not valid for an OpenCode URL.');
+    }
+
+    $host = trim((string) ($_SERVER['HTTP_HOST'] ?? 'localhost'));
+    if (!preg_match('#^([A-Za-z0-9.-]+)(:\d{1,5})?$#', $host, $matches)) {
+        throw new UnexpectedValueException('The request host is not valid for an OpenCode URL.');
+    }
+
+    $hostname = strtolower($matches[1]);
+    $port = $matches[2] ?? '';
+    if (in_array($hostname, ['localhost', '127.0.0.1'], true)) {
+        $hostname = 'agent.localhost';
+    } elseif (!str_starts_with($hostname, 'agent.')) {
+        $hostname = 'agent.' . $hostname;
+    }
+
+    return "$scheme://$hostname$port";
+}
+
+/** Build the current OpenCode web UI's server-scoped session deep link. */
+function nestbox_opencode_session_url(string $sessionId, string $directory): string
+{
+    if (!preg_match('#^[A-Za-z0-9_-]{1,128}$#', $sessionId)) {
+        throw new InvalidArgumentException('Invalid OpenCode session ID.');
+    }
+    if (!str_starts_with($directory, '/') || str_contains($directory, "\0")) {
+        throw new InvalidArgumentException('OpenCode session directories must be absolute paths.');
+    }
+
+    $origin = nestbox_opencode_origin();
+    $serverKey = rtrim(strtr(base64_encode($origin), '+/', '-_'), '=');
+    return $origin . '/server/' . $serverKey . '/session/' . rawurlencode($sessionId);
+}
+
+/** Send a JSON request to the internal OpenCode server for one mounted directory. */
+function nestbox_opencode_request(string $method, string $path, array $body, string $directory): mixed
+{
+    $baseUrl = rtrim((string) getenv('NESTBOX_OPENCODE_URL'), '/');
+    if ($baseUrl === '') {
+        throw new RuntimeException('NESTBOX_OPENCODE_URL is not configured.');
+    }
+    if (!str_starts_with($path, '/')
+        || !str_starts_with($directory, '/')
+        || preg_match('/[\0\r\n]/', $path . $directory)
+    ) {
+        throw new InvalidArgumentException('Invalid OpenCode request path or directory.');
+    }
+
+    // OpenCode scopes every non-global API operation with the documented
+    // directory query parameter. Older custom headers are ignored by the SDK.
+    $requestUrl = $baseUrl . $path
+        . (str_contains($path, '?') ? '&' : '?')
+        . 'directory=' . rawurlencode($directory);
+    $payload = json_encode($body, JSON_THROW_ON_ERROR | JSON_UNESCAPED_SLASHES);
+    $headers = [
+        'Accept: application/json',
+        'Content-Type: application/json',
+        'Content-Length: ' . strlen($payload),
+    ];
+    $password = (string) getenv('OPENCODE_SERVER_PASSWORD');
+    if ($password !== '') {
+        $username = (string) (getenv('OPENCODE_SERVER_USERNAME') ?: 'opencode');
+        $headers[] = 'Authorization: Basic ' . base64_encode("$username:$password");
+    }
+
+    $context = stream_context_create([
+        'http' => [
+            'method' => strtoupper($method),
+            'header' => implode("\r\n", $headers),
+            'content' => $payload,
+            'ignore_errors' => true,
+            'timeout' => 10,
+        ],
+    ]);
+    $response = @file_get_contents($requestUrl, false, $context);
+    $statusLine = $http_response_header[0] ?? '';
+    preg_match('#^HTTP/\S+\s+(\d{3})#', $statusLine, $matches);
+    $status = isset($matches[1]) ? (int) $matches[1] : 0;
+
+    if ($response === false || $status < 200 || $status >= 300) {
+        throw new RuntimeException("OpenCode request failed with HTTP status $status.");
+    }
+    if ($response === '' || $status === 204) {
+        return null;
+    }
+
+    return json_decode($response, true, flags: JSON_THROW_ON_ERROR);
+}
+
+/** Create an OpenCode session synchronously so its ID is available immediately. */
+function nestbox_opencode_create_session(string $title, string $directory = '/workspace'): array
+{
+    $session = nestbox_opencode_request('POST', '/session', ['title' => $title], $directory);
+    if (!is_array($session)
+        || !isset($session['id'])
+        || !is_string($session['id'])
+        || !preg_match('#^[A-Za-z0-9_-]{1,128}$#', $session['id'])
+    ) {
+        throw new RuntimeException('OpenCode did not return a session ID.');
+    }
+
+    return $session;
+}
+
+/** Queue a prompt, with optional system context, without waiting for the response. */
+function nestbox_opencode_prompt_async(
+    string $sessionId,
+    string $prompt,
+    string $system,
+    string $directory = '/workspace',
+): void {
+    if (!preg_match('#^[A-Za-z0-9_-]{1,128}$#', $sessionId)) {
+        throw new InvalidArgumentException('Invalid OpenCode session ID.');
+    }
+
+    $payload = [
+        'parts' => [[
+            'type' => 'text',
+            'text' => $prompt,
+        ]],
+    ];
+    if ($system !== '') {
+        $payload['system'] = $system;
+    }
+
+    nestbox_opencode_request('POST', '/session/' . rawurlencode($sessionId) . '/prompt_async', $payload, $directory);
+}
+
+/** Validate and normalize an exact or suffix-wildcard event topic. */
+function nestbox_bus_topic(string $topic, bool $allowWildcard = true): string
+{
+    $topic = trim($topic);
+    $segment = '[A-Za-z0-9][A-Za-z0-9._/-]{0,63}';
+    $pattern = $allowWildcard
+        ? "#^(?:$segment)(?::$segment)*(?::\\*)?$#"
+        : "#^(?:$segment)(?::$segment)*$#";
+
+    if (strlen($topic) > 128 || !preg_match($pattern, $topic)) {
+        throw new InvalidArgumentException("Invalid Nestbox event topic: $topic");
+    }
+
+    return $topic;
+}
+
+/** Build a same-origin, prefix-aware EventSource URL for one or more topics. */
+function nestbox_bus_url(string ...$topics): string
+{
+    if ($topics === []) {
+        throw new InvalidArgumentException('At least one Nestbox event topic is required.');
+    }
+
+    $topics = array_values(array_unique(array_map(
+        static fn (string $topic): string => nestbox_bus_topic($topic),
+        $topics,
+    )));
+    if (count($topics) > 16) {
+        throw new LengthException('A Nestbox EventSource can subscribe to at most 16 topics.');
+    }
+
+    return nestbox_url_path('_nestbox', 'events') . '?topics=' . implode(',', $topics);
+}
+
+/** Best-effort publication to an exact topic and its suffix wildcard. */
+function nestbox_bus_publish(string $topic, string $event = 'changed', array $data = []): bool
+{
+    $topic = nestbox_bus_topic($topic, false);
+    if (!preg_match('#^[A-Za-z][A-Za-z0-9_.-]{0,63}$#', $event)) {
+        throw new InvalidArgumentException("Invalid Nestbox event name: $event");
+    }
+
+    $topics = [$topic];
+    $separator = strrpos($topic, ':');
+    if ($separator !== false) {
+        $topics[] = substr($topic, 0, $separator + 1) . '*';
+    }
+
+    $payload = json_encode([
+        'topic' => $topic,
+        'event' => $event,
+        'data' => $data,
+    ], JSON_THROW_ON_ERROR | JSON_UNESCAPED_SLASHES);
+
+    if (strlen($payload) > 64 * 1024) {
+        throw new LengthException('Nestbox event payloads cannot exceed 64 KiB.');
+    }
+
+    $publisher = getenv('NESTBOX_BUS_PUBLISH_URL');
+    if (!$publisher) {
+        error_log('Nestbox event publication skipped: NESTBOX_BUS_PUBLISH_URL is not configured.');
+        return false;
+    }
+
+    $url = $publisher . (str_contains($publisher, '?') ? '&' : '?')
+        . 'topics=' . implode(',', $topics);
+    $context = stream_context_create([
+        'http' => [
+            'method' => 'POST',
+            'header' => implode("\r\n", [
+                'Content-Type: application/json',
+                'X-EventSource-Event: ' . $event,
+                'Content-Length: ' . strlen($payload),
+            ]),
+            'content' => $payload,
+            'ignore_errors' => true,
+            'timeout' => 2,
+        ],
+    ]);
+
+    $response = @file_get_contents($url, false, $context);
+    $statusLine = $http_response_header[0] ?? '';
+    preg_match('#^HTTP/\S+\s+(\d{3})#', $statusLine, $matches);
+    $status = isset($matches[1]) ? (int) $matches[1] : 0;
+
+    if ($response === false || !in_array($status, [201, 202], true)) {
+        error_log("Nestbox event publication failed with HTTP status $status.");
+        return false;
+    }
+
+    return true;
+}

package/home/code/__includes/header.php

@@ -0,0 +1,20 @@
+<!DOCTYPE html>
+<html lang="en">
+    <head>
+        <meta charset="utf-8">
+        <meta name="viewport" content="width=device-width, initial-scale=1.0">
+        <title><?= htmlspecialchars($title ?? 'Nestbox', ENT_QUOTES, 'UTF-8'); ?></title>
+        <!-- Pre-built bundle of every shared dependency (Bootstrap, GitHub Markdown CSS, …): -->
+        <link rel="stylesheet" href="<?= nestbox_escape(nestbox_url_path('scripts-bundle.css')); ?>">
+        <script defer src="<?= nestbox_escape(nestbox_url_path('scripts-bundle.js')); ?>"></script>
+        <!-- Site-wide overrides: -->
+        <link rel="stylesheet" href="<?= nestbox_escape(nestbox_url_path('styles.css')); ?>">
+    </head>
+    <body>
+        <header class="nestbox-toolbar navbar fixed-top bg-body-tertiary border-bottom px-3" aria-label="Page tools">
+            <a class="navbar-brand fs-6 fw-semibold mb-0" href="<?= nestbox_escape(nestbox_url_path()); ?>">Nestbox</a>
+            <div class="d-flex align-items-center gap-2 ms-auto">
+                <a class="btn btn-sm btn-secondary" href="<?= nestbox_escape(nestbox_opencode_origin()); ?>" target="nestbox-opencode">Open Chat</a>
+            </div>
+        </header>
+        <article class="markdown-body">