@appstrata/cli 0.1.0

package/README.md

@@ -0,0 +1,304 @@
+# @appstrata/cli
+
+Command-line interface for AppStrata Digital Signage SDK.
+
+## Installation
+
+> **Note:** This is a private npm package. Requires an npm access token — contact the AppStrata team to get one, then add it to your `~/.npmrc`:
+>
+> ```
+> //registry.npmjs.org/:_authToken=YOUR_TOKEN
+> ```
+
+```bash
+npm install -g @appstrata/cli
+# or
+pnpm add -g @appstrata/cli
+```
+
+Or use via `npx`:
+
+```bash
+npx @appstrata/cli dev
+```
+
+## Monorepo development
+
+When working inside the AppStrata monorepo, use `npm link` to install the CLI globally from local source without publishing:
+
+```bash
+cd packages/cli
+npm link        # creates a global symlink to this package
+npm -g list     # verify the link was created
+appstrata --help
+
+# to remove the link later
+npm unlink -g @appstrata/cli
+```
+
+To pick up code changes without relinking:
+
+```bash
+pnpm build
+# or watch mode (rebuilds automatically on change)
+pnpm --filter @appstrata/cli dev
+```
+
+## Commands
+
+### `appstrata dev`
+
+Start development player with App loaded in iframe.
+
+Loads the user's app in an iframe and provides a mock player environment. Optionally relays messages to a remote HTTP player instead of using a local mock host.
+
+```bash
+appstrata dev -u <app-url> [options]
+```
+
+**Options:**
+
+| Option | Required | Default | Description |
+|--------|----------|---------|-------------|
+| `-u, --url <url>` | ✓ | - | URL of app to load in player iframe |
+| `-p, --port <port>` | - | `5173` | Port to run dev server on |
+| `-c, --config <path>` | - | `appstrata.config.ts` | Path to config file |
+| `--host` | - | - | Expose server to network |
+| `-r, --relay <url>` | - | - | URL of remote HTTP player to relay to |
+| `-t, --transport <mode>` | - | `sse` | HTTP transport mode for relay (`sse` or `polling`) |
+
+**Examples:**
+
+```bash
+# Local mock player (app must already be running on port 5174)
+appstrata dev -u http://localhost:5174
+
+# Custom port, exposed to network
+appstrata dev -u http://localhost:5174 --port 3000 --host
+
+# Relay to a remote HTTP player
+# Terminal 1: start your app
+cd my-app && npm run dev -- --port 5174
+
+# Terminal 2: start the HTTP player host
+appstrata dev-http-player --port 5175
+
+# Terminal 3: start the dev player with relay
+appstrata dev -u http://localhost:5174 --relay http://localhost:5175
+
+# Use long-polling transport instead of SSE (both sides must match)
+appstrata dev-http-player --port 5175 --transport polling
+appstrata dev -u http://localhost:5174 --relay http://localhost:5175 --transport polling
+```
+
+**Architecture (relay mode):**
+```
+[App iframe] ◄─ postMessage ─► [RelayTransport] ◄─ HTTP ─► [Remote Player]
+```
+
+**Note**: Your app doesn't need special configuration - it just uses `getPlayer()` normally. In relay mode, the relay handles all HTTP communication transparently.
+
+### `appstrata dev-http-player`
+
+Start Node dev player with HTTP transport only.
+
+This command starts an HTTP server that implements the AppStrata protocol via HTTP POST (receive) and either Server-Sent Events or long polling (send). Use this for testing HTTP transport or as a backend for relay scenarios.
+
+```bash
+appstrata dev-http-player [options]
+```
+
+**Options:**
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `-p, --port <port>` | `5175` | Port for HTTP server |
+| `--host` | - | Expose server to network |
+| `-c, --config <path>` | - | Path to appstrata.config.ts |
+| `-t, --transport <mode>` | `sse` | HTTP transport mode (`sse` or `polling`) |
+| `--runtime <runtime>` | `node` | Player runtime (`node` or `python`) |
+| `-s, --session-id <id>` | - | Session ID (optional) |
+
+**Example:**
+
+```bash
+# Start on default port (SSE mode, Node runtime)
+appstrata dev-http-player
+
+# Use long-polling transport
+appstrata dev-http-player --transport polling
+
+# Custom port with config
+appstrata dev-http-player --port 3000 --config ./my-config.ts
+
+# Expose to network
+appstrata dev-http-player --host
+```
+
+#### Python runtime
+
+The dev HTTP player can also run on a Python runtime, which reimplements the same HTTP server using `aiohttp`. This requires Python 3.10+ on your system.
+
+```bash
+# Use the Python runtime
+appstrata dev-http-player --runtime python
+
+# With options
+appstrata dev-http-player --runtime python --port 5175 --transport sse
+```
+
+On first run, the CLI will automatically:
+1. Find Python 3.10+ on your system
+2. Create a virtual environment at `.appstrata/python-venv/`
+3. Install dependencies into the venv
+
+Subsequent runs reuse the existing venv. The CLI handles config loading from `appstrata.config.ts` and streams config updates to the Python process via stdin.
+
+**API Endpoints:**
+- `POST /api/send` - Client sends messages to the player (requires `X-Session-Id` header)
+- `GET /api/receive?sessionId={id}` - Player sends messages to the client (SSE or long-polling, depending on transport mode)
+
+**Status Page:**
+- `GET /` - View server status and active sessions
+
+### `appstrata package`
+
+Package an app into a zip bundle for CMS deployment (e.g., Yodeck).
+
+```bash
+appstrata package [options]
+```
+
+**Options:**
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `-c, --config <path>` | `appstrata.config.ts` | Path to config file |
+| `-o, --outDir <dir>` | `dist` | Build output directory |
+
+**Inputs** (convention-based, resolved from CWD):
+
+- `appstrata.config.ts` - app metadata and configuration inputs
+- `dist/` - pre-built app output (must contain `index.html`)
+- `.appstrata/package/` - marketplace assets (logo, screenshots, optional manual schema.json)
+
+**Output:**
+
+- `dist/<app-id>.zip` - self-contained bundle ready for CMS upload
+
+**Required directory structure:**
+
+```
+my-app/
+  .appstrata/
+    package/
+      logo.png              # REQUIRED: app logo
+      screenshots/           # REQUIRED: at least one screenshot
+        1.png
+        2.png
+      schema.json            # Optional: manual schema override
+  dist/                      # Pre-built app (run your build first)
+    index.html
+    assets/
+  appstrata.config.ts
+```
+
+**Example:**
+
+```bash
+# Build your app first
+npm run build
+
+# Package into a zip bundle
+appstrata package
+
+# Custom output directory
+appstrata package --outDir build
+```
+
+**Schema generation:** If `.appstrata/package/schema.json` exists, it is copied as-is. Otherwise, a Yodeck-compatible schema is auto-generated from `app.configuration.inputs` in your config.
+
+**Asset mapping to Yodeck:** The CLI maps assets to Yodeck's `{usage}` naming convention:
+- `logo.png` -> `_fileassets/<app-id>{logo}.png`
+- `screenshots/<name>.png` -> `_fileassets/<name>{slides}.png`
+
+## What It Does
+
+The `dev` command starts a Vite dev server with the AppStrata plugin, which:
+
+1. Injects a mock player into your app
+2. Serves mock context from `/__appstrata__/context`
+3. Fires lifecycle events (`onInit`, `onShow`, `onStart`)
+4. Provides mock storage and proxy APIs
+5. Supports HMR for config changes
+
+## Configuration
+
+The CLI supports two config formats. Choose the one that fits your project.
+
+### Option A: TypeScript config (recommended for projects with `package.json`)
+
+```bash
+npm install -D @appstrata/dev
+```
+
+```typescript
+// appstrata.config.ts
+import { defineConfig } from "@appstrata/dev";
+
+export default defineConfig({
+  app: {
+    id: "my-app",
+    name: "My Signage App",
+    version: "1.0.0",
+  },
+  dev: {
+    context: {
+      config: { title: "Hello World" },
+      viewportWidth: 1920,
+      viewportHeight: 1080,
+    },
+  },
+});
+```
+
+With `@appstrata/dev` installed, you get full IDE autocomplete and type checking. You can also import any other package from your project's `node_modules` in the config file.
+
+> **Note**: The TypeScript config also works without installing `@appstrata/dev` — the CLI resolves the `defineConfig` import automatically. However, your IDE won't provide autocomplete without the package installed locally.
+
+### Option B: JSON config (zero setup, no dependencies)
+
+```json
+// appstrata.config.json
+{
+  "app": {
+    "id": "my-app",
+    "name": "My Signage App",
+    "version": "1.0.0"
+  },
+  "dev": {
+    "context": {
+      "config": { "title": "Hello World" },
+      "viewportWidth": 1920,
+      "viewportHeight": 1080
+    }
+  }
+}
+```
+
+No `package.json`, no `node_modules`, no build tools required. Just create the JSON file and run `appstrata dev`.
+
+### Config file resolution
+
+The CLI looks for config files in this order:
+
+1. `appstrata.config.ts` (TypeScript)
+2. `appstrata.config.json` (JSON fallback)
+
+Use `-c` / `--config` to specify a custom path.
+
+See `@appstrata/dev` for full configuration reference.
+
+## License
+
+MIT

package/dist/commands/dev-http-player.d.ts

@@ -0,0 +1,23 @@
+/**
+ * `appstrata dev-http-player` — Start a dev player with HTTP transport.
+ *
+ * Exposes endpoints based on the selected transport mode:
+ *
+ * **SSE mode (default):**
+ *   POST /api/send    — client sends messages to the player
+ *   GET  /api/receive — player sends messages to the client (SSE)
+ *
+ * **Polling mode:**
+ *   POST /api/send    — client sends messages to the player
+ *   GET  /api/receive — player sends messages to the client (long-polling)
+ */
+interface DevHttpPlayerOptions {
+    port: string;
+    host?: boolean;
+    config: string;
+    transport?: "sse" | "polling";
+    runtime?: string;
+}
+export declare function devHttpPlayerCommand(options: DevHttpPlayerOptions): Promise<void>;
+export {};
+//# sourceMappingURL=dev-http-player.d.ts.map

package/dist/commands/dev-http-player.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dev-http-player.d.ts","sourceRoot":"","sources":["../../src/commands/dev-http-player.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAkDH,UAAU,oBAAoB;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,KAAK,GAAG,SAAS,CAAC;IAC9B,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAmFD,wBAAsB,oBAAoB,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC,CAmSvF"}

package/dist/commands/dev-http-player.js

@@ -0,0 +1,360 @@
+/**
+ * `appstrata dev-http-player` — Start a dev player with HTTP transport.
+ *
+ * Exposes endpoints based on the selected transport mode:
+ *
+ * **SSE mode (default):**
+ *   POST /api/send    — client sends messages to the player
+ *   GET  /api/receive — player sends messages to the client (SSE)
+ *
+ * **Polling mode:**
+ *   POST /api/send    — client sends messages to the player
+ *   GET  /api/receive — player sends messages to the client (long-polling)
+ */
+import * as http from "node:http";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { createAppHost } from "@appstrata/player-lib";
+import { createHttpHostTransportManager, createHttpSseHostTransport, createHttpPollingHostTransport, } from "@appstrata/protocol";
+import { buildAppContext, resolveCapabilities, buildCapabilityServices, DEFAULT_CONTEXT, DEFAULT_LIFECYCLE, } from "@appstrata/dev";
+import { loadConfig } from "@appstrata/dev";
+import { renderStatusPage } from "../status-page.js";
+import { getRuntime } from "../runtimes/index.js";
+// ── Transport handlers ───────────────────────────────────────────────────
+function createSseHandler(deps) {
+    const { manager, destroySession } = deps;
+    const sseConnections = [];
+    return {
+        handleReceiveRequest(req, res, sessionId) {
+            console.log(`[AppStrata Dev HTTP Player] [${sessionId}] SSE connection opened`);
+            res.writeHead(200, {
+                "Content-Type": "text/event-stream",
+                "Cache-Control": "no-cache",
+                "Connection": "keep-alive",
+            });
+            res.write(": connected\n\n");
+            const transport = manager.getTransport(sessionId);
+            const cleanup = transport.setSseWriter((data) => res.write(data));
+            sseConnections.push({ res, cleanup });
+            req.on("close", () => {
+                console.log(`[AppStrata Dev HTTP Player] [${sessionId}] SSE connection closed — destroying session`);
+                cleanup();
+                const idx = sseConnections.findIndex((c) => c.res === res);
+                if (idx >= 0)
+                    sseConnections.splice(idx, 1);
+                destroySession(sessionId);
+            });
+        },
+        cleanup() {
+            for (const conn of sseConnections) {
+                conn.cleanup();
+                conn.res.end();
+            }
+        },
+    };
+}
+function createPollingHandler(deps) {
+    const { manager, destroySession } = deps;
+    const pollIdleTimers = new Map();
+    const POLL_IDLE_TIMEOUT = 60000; // 1 minute without a poll = session dead
+    function resetPollIdleTimer(sessionId) {
+        const existing = pollIdleTimers.get(sessionId);
+        if (existing)
+            clearTimeout(existing);
+        pollIdleTimers.set(sessionId, setTimeout(() => {
+            console.log(`[AppStrata Dev HTTP Player] [${sessionId}] No poll received in ${POLL_IDLE_TIMEOUT / 1000}s — destroying session`);
+            pollIdleTimers.delete(sessionId);
+            destroySession(sessionId);
+        }, POLL_IDLE_TIMEOUT));
+    }
+    return {
+        handleReceiveRequest(_req, res, sessionId) {
+            resetPollIdleTimer(sessionId);
+            const transport = manager.getTransport(sessionId);
+            transport.handlePollRequest(30000).then((messages) => {
+                if (messages === null) {
+                    res.writeHead(409, { "Content-Type": "application/json" });
+                    res.end(JSON.stringify({ error: "Poll already active for this session" }));
+                }
+                else {
+                    res.writeHead(200, { "Content-Type": "application/json" });
+                    res.end(JSON.stringify({ messages }));
+                }
+            });
+        },
+        cleanup() {
+            for (const timer of pollIdleTimers.values())
+                clearTimeout(timer);
+            pollIdleTimers.clear();
+        },
+    };
+}
+export async function devHttpPlayerCommand(options) {
+    const port = parseInt(options.port, 10);
+    const transportMode = options.transport ?? "sse";
+    const runtimeName = options.runtime ?? "node";
+    // ── External runtime delegation ──────────────────────────────────────
+    // When a non-Node runtime is selected, delegate to it entirely.
+    // The Node process becomes a thin wrapper: it loads the .ts config,
+    // watches for changes, and streams JSON updates to the runtime's stdin.
+    if (runtimeName !== "node") {
+        const runtime = getRuntime(runtimeName);
+        const projectRoot = process.cwd();
+        console.log(`\n  Runtime: ${runtime.name}`);
+        await runtime.ensureReady(projectRoot);
+        const result = await loadConfig(options.config);
+        let config = result?.config ?? null;
+        const configPath = result?.filePath ?? null;
+        if (configPath) {
+            console.log(`  Loaded config from ${configPath}`);
+        }
+        else {
+            console.log(`  No config file found, using defaults`);
+        }
+        // Spawn the external runtime process
+        const proc = runtime.spawn({
+            port,
+            host: !!options.host,
+            transport: transportMode,
+        });
+        // Send initial config via stdin
+        const devConfig = config?.dev ?? {};
+        proc.sendConfig(devConfig);
+        // Watch config for hot reload and stream updates
+        let debounceTimer = null;
+        const watcher = configPath ? fs.watch(configPath, () => {
+            if (debounceTimer)
+                clearTimeout(debounceTimer);
+            debounceTimer = setTimeout(async () => {
+                console.log(`[AppStrata Dev HTTP Player] Config changed, reloading...`);
+                const reloaded = await loadConfig(configPath);
+                if (reloaded) {
+                    config = reloaded.config;
+                    proc.sendConfig(config?.dev ?? {});
+                }
+                else {
+                    console.warn(`  Could not reload config from ${configPath}`);
+                }
+            }, 100);
+        }) : null;
+        // Forward SIGINT to the runtime process
+        process.once("SIGINT", () => {
+            console.log(`\n[AppStrata Dev HTTP Player] Shutting down ${runtime.name} runtime...`);
+            watcher?.close();
+            if (debounceTimer)
+                clearTimeout(debounceTimer);
+            proc.kill();
+        });
+        // Wait for the process to exit
+        const exitCode = await proc.exited;
+        console.log(`[AppStrata Dev HTTP Player] ${runtime.name} process exited (code: ${exitCode})`);
+        return;
+    }
+    // ── Node runtime (original implementation) ───────────────────────────
+    const result = await loadConfig(options.config);
+    let config = result?.config ?? null;
+    const configPath = result?.filePath ?? null;
+    if (configPath) {
+        console.log(`  Loaded config from ${configPath}`);
+    }
+    else {
+        console.log(`  No config file found, using defaults`);
+    }
+    // Create transport manager with the appropriate factory for the selected mode
+    const transportFactory = transportMode === "sse"
+        ? (sessionId) => createHttpSseHostTransport({ sessionId })
+        : (sessionId) => createHttpPollingHostTransport({ sessionId });
+    const manager = createHttpHostTransportManager(transportFactory);
+    const sessions = new Map();
+    /** Create an AppHost on first contact with a session. */
+    function ensureSession(sessionId) {
+        if (sessions.has(sessionId))
+            return;
+        console.log(`[${sessionId}] New session`);
+        const transport = manager.getTransport(sessionId);
+        const capabilities = resolveCapabilities(config?.dev?.capabilities);
+        const context = buildAppContext(config?.dev?.context ?? DEFAULT_CONTEXT, capabilities);
+        const services = buildCapabilityServices(capabilities);
+        const lifecycle = config?.dev?.lifecycle ?? DEFAULT_LIFECYCLE;
+        const initDelay = lifecycle.initDelay ?? 0;
+        const showDelay = lifecycle.showDelay ?? 50;
+        const startDelay = lifecycle.startDelay ?? 50;
+        const hideDelay = lifecycle.hideDelay ?? 100;
+        const stopDelay = lifecycle.stopDelay ?? 50;
+        const appHost = createAppHost({
+            services,
+            target: {},
+            transport,
+            retryInterval: 500,
+            notifyComplete: () => {
+                console.log(`[AppStrata Dev HTTP Player] [${sessionId}] App called notifyComplete()`);
+                setTimeout(() => {
+                    console.log(`[AppStrata Dev HTTP Player] [${sessionId}] fireHide`);
+                    appHost.fireHide();
+                }, hideDelay);
+                setTimeout(() => {
+                    console.log(`[AppStrata Dev HTTP Player] [${sessionId}] fireStop`);
+                    appHost.fireStop();
+                }, hideDelay + stopDelay);
+            },
+            notifyEstimatedEnd: (expectedFinishTime) => {
+                const secsUntil = Math.round((expectedFinishTime - Date.now()) / 1000);
+                console.log(`[AppStrata Dev HTTP Player] [${sessionId}] App called notifyEstimatedEnd() — finishes in ~${secsUntil}s (${new Date(expectedFinishTime).toISOString()})`);
+            },
+            notifyNoContent: (options) => {
+                const parts = [`[AppStrata Dev HTTP Player] [${sessionId}] App called notifyNoContent()`];
+                if (options?.reason)
+                    parts.push(`reason="${options.reason}"`);
+                if (options?.retryNotBefore) {
+                    const secsUntil = Math.round((options.retryNotBefore - Date.now()) / 1000);
+                    parts.push(`retry in ~${secsUntil}s`);
+                }
+                console.log(parts.join(" — "));
+                setTimeout(() => {
+                    console.log(`[AppStrata Dev HTTP Player] [${sessionId}] fireHide`);
+                    appHost.fireHide();
+                }, hideDelay);
+                setTimeout(() => {
+                    console.log(`[AppStrata Dev HTTP Player] [${sessionId}] fireStop`);
+                    appHost.fireStop();
+                }, hideDelay + stopDelay);
+            },
+            log: (level, message, data) => {
+                console.log(`[AppStrata Dev HTTP Player] [${sessionId}] [${level}] ${message}`, data || "");
+            },
+        });
+        setTimeout(() => {
+            console.log(`[AppStrata Dev HTTP Player] [${sessionId}] fireInit`);
+            appHost.fireInit(context);
+        }, initDelay);
+        setTimeout(() => {
+            console.log(`[AppStrata Dev HTTP Player] [${sessionId}] fireShow`);
+            appHost.fireShow();
+        }, initDelay + showDelay);
+        setTimeout(() => {
+            console.log(`[AppStrata Dev HTTP Player] [${sessionId}] fireStart`);
+            appHost.fireStart();
+        }, initDelay + showDelay + startDelay);
+        sessions.set(sessionId, appHost);
+    }
+    /** Destroy an AppHost and close the transport for a session. */
+    function destroySession(sessionId) {
+        const appHost = sessions.get(sessionId);
+        if (appHost) {
+            appHost.destroy();
+            sessions.delete(sessionId);
+        }
+        manager.closeSession(sessionId);
+    }
+    // Create transport handler for the selected mode
+    const handler = transportMode === "sse"
+        ? createSseHandler({ manager, destroySession })
+        : createPollingHandler({ manager, destroySession });
+    manager.onMessage((sessionId, msg) => {
+        console.log(`[AppStrata Dev HTTP Player] [${sessionId}] <- ${msg.type}`);
+    });
+    // --- HTTP server ---
+    const server = http.createServer((req, res) => {
+        const url = new URL(req.url || "/", `http://localhost`);
+        // CORS
+        res.setHeader("Access-Control-Allow-Origin", "*");
+        res.setHeader("Access-Control-Allow-Methods", "GET, POST, OPTIONS");
+        res.setHeader("Access-Control-Allow-Headers", "Content-Type, X-Session-Id");
+        if (req.method === "OPTIONS") {
+            res.writeHead(204);
+            res.end();
+            return;
+        }
+        // POST /api/send (client -> server)
+        if (req.method === "POST" && url.pathname === "/api/send") {
+            let body = "";
+            req.on("data", (chunk) => { body += chunk; });
+            req.on("end", () => {
+                try {
+                    const message = JSON.parse(body);
+                    const sessionId = req.headers["x-session-id"];
+                    if (!sessionId) {
+                        res.writeHead(400, { "Content-Type": "application/json" });
+                        res.end(JSON.stringify({ ok: false, error: "Missing X-Session-Id header" }));
+                        return;
+                    }
+                    ensureSession(sessionId);
+                    manager.getTransport(sessionId).handleIncomingMessage(message);
+                    res.writeHead(200, { "Content-Type": "application/json" });
+                    res.end(JSON.stringify({ ok: true }));
+                }
+                catch {
+                    res.writeHead(400, { "Content-Type": "application/json" });
+                    res.end(JSON.stringify({ ok: false, error: "Invalid JSON" }));
+                }
+            });
+            return;
+        }
+        // GET /api/receive (server -> client)
+        if (req.method === "GET" && url.pathname === "/api/receive") {
+            const sessionId = url.searchParams.get("sessionId");
+            if (!sessionId) {
+                res.writeHead(400);
+                res.end("Missing sessionId");
+                return;
+            }
+            ensureSession(sessionId);
+            handler.handleReceiveRequest(req, res, sessionId);
+            return;
+        }
+        // GET / — status page
+        if (req.method === "GET" && url.pathname === "/") {
+            res.writeHead(200, { "Content-Type": "text/html" });
+            res.end(renderStatusPage(port, Array.from(sessions.keys())));
+            return;
+        }
+        res.writeHead(404);
+        res.end("Not Found");
+    });
+    // --- Start ---
+    await new Promise((resolve) => {
+        server.listen(port, options.host ? "0.0.0.0" : "127.0.0.1", resolve);
+    });
+    console.log(`\n[AppStrata Dev HTTP Player] HTTP Dev Player running on http://localhost:${port}/`);
+    console.log(`  Transport mode: ${transportMode}`);
+    console.log(`  Config file: ${configPath ?? options.config}`);
+    console.log(`  POST http://localhost:${port}/api/send`);
+    console.log(`  GET  http://localhost:${port}/api/receive`);
+    console.log(`\n  Edit ${configPath ? path.basename(configPath) : "appstrata.config.ts"} to change mock context (hot reload supported)\n`);
+    // Watch config file for hot reload
+    let debounceTimer = null;
+    const watcher = configPath ? fs.watch(configPath, () => {
+        if (debounceTimer)
+            clearTimeout(debounceTimer);
+        debounceTimer = setTimeout(async () => {
+            console.log("[AppStrata Dev HTTP Player]  Config changed, reloading...");
+            const reloaded = await loadConfig(configPath);
+            if (!reloaded) {
+                console.warn(`  Could not reload config from ${configPath}`);
+                return;
+            }
+            config = reloaded.config;
+            const capabilities = resolveCapabilities(config?.dev?.capabilities);
+            const newServices = buildCapabilityServices(capabilities);
+            const newContext = buildAppContext(config?.dev?.context ?? DEFAULT_CONTEXT, capabilities);
+            for (const [sessionId, appHost] of sessions) {
+                console.log(`[AppStrata Dev HTTP Player] [${sessionId}] Updating context`);
+                appHost.updateServices(newServices);
+                appHost.updateContext(newContext);
+            }
+        }, 100);
+    }) : null;
+    process.once("SIGINT", () => {
+        console.log("\n[AppStrata Dev HTTP Player] Shutting down...");
+        watcher?.close();
+        if (debounceTimer)
+            clearTimeout(debounceTimer);
+        handler.cleanup();
+        manager.closeAll();
+        server.close(() => { console.log("[AppStrata Dev HTTP Player] Server closed\n"); });
+        setTimeout(() => {
+            console.log("[AppStrata Dev HTTP Player] Exiting...");
+            process.exit(0);
+        }, 2000);
+    });
+}