@appstrata/cli 0.1.0

package/dist/commands/dev.d.ts

@@ -0,0 +1,21 @@
+/**
+ * `appstrata dev` command - Start development player with 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.
+ */
+interface DevOptions {
+    url: string;
+    port: string;
+    config: string;
+    host?: boolean;
+    relay?: string;
+    transport?: "sse" | "polling";
+}
+/**
+ * Start the development player.
+ */
+export declare function devCommand(options: DevOptions): Promise<void>;
+export {};
+//# sourceMappingURL=dev.d.ts.map

package/dist/commands/dev.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dev.d.ts","sourceRoot":"","sources":["../../src/commands/dev.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAOH,UAAU,UAAU;IAClB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,KAAK,GAAG,SAAS,CAAC;CAC/B;AAED;;GAEG;AACH,wBAAsB,UAAU,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAiHnE"}

package/dist/commands/dev.js

@@ -0,0 +1,114 @@
+/**
+ * `appstrata dev` command - Start development player with 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.
+ */
+import { createServer } from "vite";
+import { appstrata, loadConfig } from "@appstrata/dev";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+/**
+ * Start the development player.
+ */
+export async function devCommand(options) {
+    const appUrl = options.url;
+    const isRelay = !!options.relay;
+    // Resolve the config to find the actual file for
+    // the banner. The plugin will load it again in configureServer.
+    const result = await loadConfig(options.config);
+    const configPath = result?.filePath ?? path.resolve(process.cwd(), options.config);
+    const configName = path.basename(configPath);
+    console.log("\n  Starting AppStrata Dev Player...\n");
+    console.log(`  App URL:     ${appUrl}`);
+    console.log(`  Config file: ${configName}`);
+    console.log(`  Port:        ${options.port}`);
+    console.log(`  Host:        ${options.host ? "true" : "false"}`);
+    if (isRelay) {
+        console.log(`  Relay to:    ${options.relay}`);
+        console.log(`  Transport:   ${options.transport ?? "sse"}`);
+    }
+    console.log("\n  Make sure your app dev server is running!\n");
+    try {
+        // Resolve path to player page from @appstrata/dev
+        // When running from CLI, we need to find the player directory in @appstrata/dev
+        const devPackagePath = path.dirname(fileURLToPath(import.meta.resolve("@appstrata/dev")));
+        // Check if we're in development (workspace) or production (npm installed)
+        // In dev: devPackagePath = .../packages/dev/dist
+        // In prod: devPackagePath = .../node_modules/@appstrata/dev/dist
+        const isWorkspace = devPackagePath.includes("packages") && !devPackagePath.includes("node_modules");
+        // Use source directory in workspace, dist in production
+        const playerRoot = isWorkspace
+            ? path.join(devPackagePath, "..", "src", "player") // dev: use src
+            : path.join(devPackagePath, "player"); // prod: use dist
+        console.log(`[Debug] Player root: ${playerRoot}`);
+        console.log(`[Debug] Workspace mode: ${isWorkspace}`);
+        console.log(`[Debug] Config path (resolved): ${configPath}`);
+        // Build plugin options, including relay config if provided
+        const pluginOptions = {
+            configFile: configPath,
+            player: "standalone",
+        };
+        if (options.relay) {
+            pluginOptions.relay = {
+                playerUrl: options.relay,
+                transport: options.transport ?? "sse",
+            };
+        }
+        const server = await createServer({
+            root: playerRoot,
+            plugins: [
+                appstrata(pluginOptions),
+            ],
+            server: {
+                port: parseInt(options.port, 10),
+                host: options.host,
+            },
+        });
+        await server.listen();
+        const address = server.httpServer?.address();
+        const port = typeof address === "object" && address ? address.port : options.port;
+        const hostOrigin = `http://localhost:${port}`;
+        // Open browser with dynamic hostOrigin
+        const appUrlWithHost = `${appUrl}?hostOrigin=${encodeURIComponent(hostOrigin)}`;
+        const playerUrl = `/?appUrl=${encodeURIComponent(appUrlWithHost)}`;
+        const fullUrl = `http://localhost:${port}${playerUrl}`;
+        console.log("  AppStrata Dev Player running\n");
+        console.log(`  ➜  Local:   ${fullUrl}`);
+        if (options.host) {
+            // Get network addresses
+            const { networkInterfaces } = await import("node:os");
+            const nets = networkInterfaces();
+            for (const name of Object.keys(nets)) {
+                for (const net of nets[name] || []) {
+                    if (net.family === "IPv4" && !net.internal) {
+                        console.log(`  ➜  Network: http://${net.address}:${port}/?appUrl=${encodeURIComponent(appUrl)}`);
+                    }
+                }
+            }
+        }
+        if (isRelay) {
+            console.log("\n  Relay features:");
+            console.log("  • PostMessage transport to app (iframe)");
+            console.log(`  • HTTP transport to remote player (${options.transport ?? "sse"})`);
+            console.log("  • Real-time message statistics");
+            console.log("  • HMR for player UI settings");
+            console.log(`\n  Edit ${configName} to change player UI (HMR supported).`);
+            console.log("  App context is managed by the remote player.\n");
+        }
+        else {
+            console.log("\n  Player features:");
+            console.log("  • Message protocol (like production web players)");
+            console.log("  • Lifecycle events (onInit, onShow, onStart)");
+            console.log("  • Mock capability APIs");
+            console.log("  • HMR for config changes");
+            console.log(`\n  Edit ${configName} to change mock context & player UI (HMR supported)\n`);
+        }
+    }
+    catch (error) {
+        console.error("\n  Failed to start player:\n");
+        console.error(error);
+        process.exit(1);
+    }
+}

package/dist/commands/package.d.ts

@@ -0,0 +1,18 @@
+/**
+ * `appstrata package` command - Package app into a zip bundle for CMS deployment.
+ *
+ * Inputs (convention-based, resolved from CWD):
+ *   - appstrata.config.ts  (flag: -c)
+ *   - dist/                (flag: -o)
+ *   - .appstrata/package/  (convention, no flag)
+ *
+ * Output:
+ *   - dist/<app-id>.zip
+ */
+interface PackageOptions {
+    config: string;
+    outDir: string;
+}
+export declare function packageCommand(options: PackageOptions): Promise<void>;
+export {};
+//# sourceMappingURL=package.d.ts.map

package/dist/commands/package.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"package.d.ts","sourceRoot":"","sources":["../../src/commands/package.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAQH,UAAU,cAAc;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB;AA4JD,wBAAsB,cAAc,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAoD3E"}

package/dist/commands/package.js

@@ -0,0 +1,161 @@
+/**
+ * `appstrata package` command - Package app into a zip bundle for CMS deployment.
+ *
+ * Inputs (convention-based, resolved from CWD):
+ *   - appstrata.config.ts  (flag: -c)
+ *   - dist/                (flag: -o)
+ *   - .appstrata/package/  (convention, no flag)
+ *
+ * Output:
+ *   - dist/<app-id>.zip
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import archiver from "archiver";
+import { loadConfig } from "@appstrata/dev";
+import { generateYodeckSchema } from "../schema-generator.js";
+const PACKAGE_DIR = ".appstrata/package";
+function validateBuildOutput(distDir) {
+    if (!fs.existsSync(distDir)) {
+        throw new Error(`Build output directory not found: ${distDir}\n` +
+            `  Run your build command first (e.g., "npm run build").`);
+    }
+    const indexPath = path.join(distDir, "index.html");
+    if (!fs.existsSync(indexPath)) {
+        throw new Error(`index.html not found in ${distDir}\n` +
+            `  The build output must contain an index.html at the root.`);
+    }
+}
+function validateAndCollectAssets(packageDir) {
+    if (!fs.existsSync(packageDir)) {
+        throw new Error(`.appstrata/package/ directory not found.\n` +
+            `  Create it with at least a logo file and one screenshot:\n` +
+            `    .appstrata/package/logo.png\n` +
+            `    .appstrata/package/screenshots/1.png`);
+    }
+    const logoFiles = fs.readdirSync(packageDir).filter((f) => {
+        const name = path.parse(f).name.toLowerCase();
+        return name === "logo" && fs.statSync(path.join(packageDir, f)).isFile();
+    });
+    if (logoFiles.length === 0) {
+        throw new Error(`No logo file found in .appstrata/package/.\n` +
+            `  Add a logo file (e.g., logo.png, logo.svg).`);
+    }
+    if (logoFiles.length > 1) {
+        throw new Error(`Multiple logo files found in .appstrata/package/: ${logoFiles.join(", ")}\n` +
+            `  Keep exactly one logo file.`);
+    }
+    const logoFile = logoFiles[0];
+    const logoExt = path.extname(logoFile);
+    const screenshotsDir = path.join(packageDir, "screenshots");
+    if (!fs.existsSync(screenshotsDir) || !fs.statSync(screenshotsDir).isDirectory()) {
+        throw new Error(`screenshots/ directory not found in .appstrata/package/.\n` +
+            `  Create it with at least one screenshot:\n` +
+            `    .appstrata/package/screenshots/1.png`);
+    }
+    const screenshotFiles = fs.readdirSync(screenshotsDir)
+        .filter((f) => fs.statSync(path.join(screenshotsDir, f)).isFile())
+        .map((f) => ({
+        name: path.parse(f).name,
+        ext: path.extname(f),
+        fullPath: path.join(screenshotsDir, f),
+    }));
+    if (screenshotFiles.length === 0) {
+        throw new Error(`No screenshots found in .appstrata/package/screenshots/.\n` +
+            `  Add at least one screenshot image.`);
+    }
+    const expectedEntries = new Set(["logo" + logoExt.toLowerCase(), "screenshots", "schema.json"]);
+    const entries = fs.readdirSync(packageDir);
+    for (const entry of entries) {
+        if (!expectedEntries.has(entry.toLowerCase())) {
+            console.warn(`  Warning: unexpected file in .appstrata/package/: ${entry} (skipping)`);
+        }
+    }
+    return { logoFile, logoExt, screenshotFiles };
+}
+function handleSchema(packageDir, distDir, config) {
+    const manualSchemaPath = path.join(packageDir, "schema.json");
+    if (fs.existsSync(manualSchemaPath)) {
+        fs.copyFileSync(manualSchemaPath, path.join(distDir, "schema.json"));
+        return "manual";
+    }
+    const schema = generateYodeckSchema(config.app);
+    fs.writeFileSync(path.join(distDir, "schema.json"), JSON.stringify(schema, null, "\t"), "utf-8");
+    return "generated";
+}
+function copyAssets(packageDir, distDir, appId, assets) {
+    const fileassetsDir = path.join(distDir, "_fileassets");
+    fs.mkdirSync(fileassetsDir, { recursive: true });
+    const logoSrc = path.join(packageDir, assets.logoFile);
+    const logoDest = path.join(fileassetsDir, `${appId}{logo}${assets.logoExt}`);
+    fs.copyFileSync(logoSrc, logoDest);
+    for (const screenshot of assets.screenshotFiles) {
+        const dest = path.join(fileassetsDir, `${screenshot.name}{slides}${screenshot.ext}`);
+        fs.copyFileSync(screenshot.fullPath, dest);
+    }
+}
+async function createZip(distDir, zipPath) {
+    return new Promise((resolve, reject) => {
+        const output = fs.createWriteStream(zipPath);
+        const archive = archiver("zip", { zlib: { level: 9 } });
+        output.on("close", () => resolve(archive.pointer()));
+        archive.on("error", (err) => reject(err));
+        archive.pipe(output);
+        archive.glob("**/*", {
+            cwd: distDir,
+            ignore: ["*.zip"],
+        });
+        archive.finalize();
+    });
+}
+function formatSize(bytes) {
+    if (bytes < 1024)
+        return `${bytes} B`;
+    if (bytes < 1024 * 1024)
+        return `${(bytes / 1024).toFixed(1)} KB`;
+    return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+export async function packageCommand(options) {
+    try {
+        const result = await loadConfig(options.config);
+        if (!result) {
+            throw new Error(`Failed to load config file: ${options.config}`);
+        }
+        const config = result.config;
+        const appId = config.app.id;
+        const appName = config.app.name;
+        const appVersion = config.app.version;
+        console.log(`\n  Packaging ${appName} v${appVersion}...\n`);
+        const distDir = path.resolve(process.cwd(), options.outDir);
+        const isCloudApp = !!config.app.url;
+        if (isCloudApp) {
+            if (!fs.existsSync(distDir)) {
+                fs.mkdirSync(distDir, { recursive: true });
+            }
+            console.log(`  App URL:       ${config.app.url}`);
+        }
+        else {
+            validateBuildOutput(distDir);
+            console.log(`  Build output:  ${options.outDir}/`);
+        }
+        const packageDir = path.resolve(process.cwd(), PACKAGE_DIR);
+        const assets = validateAndCollectAssets(packageDir);
+        const schemaMode = handleSchema(packageDir, distDir, config);
+        console.log(`  Schema:        ${schemaMode === "manual" ? "copied from .appstrata/package/schema.json" : "generated from app.configuration.inputs"}`);
+        copyAssets(packageDir, distDir, appId, assets);
+        console.log(`  Logo:          .appstrata/package/${assets.logoFile} -> _fileassets/${appId}{logo}${assets.logoExt}`);
+        console.log(`  Screenshots:   ${assets.screenshotFiles.length} file(s) -> _fileassets/*{slides}.*`);
+        const zipFileName = `${appId}.zip`;
+        const zipPath = path.join(distDir, zipFileName);
+        if (fs.existsSync(zipPath)) {
+            fs.unlinkSync(zipPath);
+        }
+        const size = await createZip(distDir, zipPath);
+        console.log(`\n  Created: ${options.outDir}/${zipFileName} (${formatSize(size)})\n`);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(`\n  Error: ${message}\n`);
+        process.exit(1);
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+/**
+ * @appstrata/cli - CLI for AppStrata Development Tools
+ *
+ * @packageDocumentation
+ */
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;;GAIG"}

package/dist/index.js

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+/**
+ * @appstrata/cli - CLI for AppStrata Development Tools
+ *
+ * @packageDocumentation
+ */
+import { Command } from "commander";
+import { devCommand } from "./commands/dev.js";
+import { devHttpPlayerCommand } from "./commands/dev-http-player.js";
+import { packageCommand } from "./commands/package.js";
+const program = new Command();
+program
+    .name("appstrata")
+    .description("AppStrata Development Tools CLI")
+    .version("1.0.0");
+program
+    .command("dev")
+    .description("Start development player with iframe")
+    .requiredOption("-u, --url <url>", "URL of app to load in player iframe")
+    .option("-p, --port <port>", "Port to run dev server on", "5173")
+    .option("-c, --config <path>", "Path to appstrata.config.ts", "appstrata.config.ts")
+    .option("--host", "Expose server to network")
+    .option("-r, --relay <url>", "URL of remote HTTP player to relay to")
+    .option("-t, --transport <mode>", "HTTP transport mode for relay (sse or polling)", "sse")
+    .action(devCommand);
+program
+    .command("dev-http-player")
+    .description("Start dev player with HTTP transport only")
+    .option("-p, --port <port>", "Port for HTTP server", "5175")
+    .option("--host", "Expose server to network")
+    .option("-c, --config <path>", "Path to appstrata.config.ts", "appstrata.config.ts")
+    .option("-t, --transport <mode>", "HTTP transport mode (sse or polling)", "sse")
+    .option("--runtime <runtime>", "Player runtime (node, python)", "node")
+    .action(devHttpPlayerCommand);
+program
+    .command("package")
+    .description("Package app into a zip bundle for CMS deployment")
+    .option("-c, --config <path>", "Path to appstrata.config.ts", "appstrata.config.ts")
+    .option("-o, --outDir <dir>", "Build output directory", "dist")
+    .action(packageCommand);
+program.parse();

package/dist/runtimes/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * External runtime registry.
+ *
+ * Maps runtime names to their implementations.
+ * To add a new runtime, import it here and register it in the map.
+ */
+import type { ExternalRuntime } from "./types.js";
+/**
+ * Get an external runtime by name.
+ *
+ * @throws If the runtime is not registered.
+ */
+export declare function getRuntime(name: string): ExternalRuntime;
+/**
+ * List all registered external runtime names.
+ */
+export declare function listRuntimes(): string[];
+export type { ExternalRuntime, RuntimeProcess, RuntimeSpawnOptions } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/runtimes/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/runtimes/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAOlD;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,CASxD;AAED;;GAEG;AACH,wBAAgB,YAAY,IAAI,MAAM,EAAE,CAEvC;AAED,YAAY,EAAE,eAAe,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC"}

package/dist/runtimes/index.js

@@ -0,0 +1,29 @@
+/**
+ * External runtime registry.
+ *
+ * Maps runtime names to their implementations.
+ * To add a new runtime, import it here and register it in the map.
+ */
+import { pythonRuntime } from "./python.js";
+const runtimes = {
+    python: pythonRuntime,
+};
+/**
+ * Get an external runtime by name.
+ *
+ * @throws If the runtime is not registered.
+ */
+export function getRuntime(name) {
+    const runtime = runtimes[name];
+    if (!runtime) {
+        const available = Object.keys(runtimes).join(", ");
+        throw new Error(`Unknown runtime "${name}". Available external runtimes: ${available}`);
+    }
+    return runtime;
+}
+/**
+ * List all registered external runtime names.
+ */
+export function listRuntimes() {
+    return Object.keys(runtimes);
+}

package/dist/runtimes/python.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Python runtime implementation.
+ *
+ * Manages a Python virtual environment and spawns the Python player process.
+ *
+ * - Venv is created at `{projectRoot}/.appstrata/python-venv/`
+ * - Dependencies are installed from `player-lib-python/requirements.txt`
+ * - The Python player library is at `packages/player-lib-python/appstrata_player/`
+ * - The dev-player entry point is at `packages/cli/python/appstrata_dev_player/`
+ */
+import type { ExternalRuntime } from "./types.js";
+export declare const pythonRuntime: ExternalRuntime;
+//# sourceMappingURL=python.d.ts.map

package/dist/runtimes/python.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"python.d.ts","sourceRoot":"","sources":["../../src/runtimes/python.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAMH,OAAO,KAAK,EAAE,eAAe,EAAuC,MAAM,YAAY,CAAC;AAsCvF,eAAO,MAAM,aAAa,EAAE,eA6F3B,CAAC"}

package/dist/runtimes/python.js

@@ -0,0 +1,120 @@
+/**
+ * Python runtime implementation.
+ *
+ * Manages a Python virtual environment and spawns the Python player process.
+ *
+ * - Venv is created at `{projectRoot}/.appstrata/python-venv/`
+ * - Dependencies are installed from `player-lib-python/requirements.txt`
+ * - The Python player library is at `packages/player-lib-python/appstrata_player/`
+ * - The dev-player entry point is at `packages/cli/python/appstrata_dev_player/`
+ */
+import { execSync, spawn } from "node:child_process";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+/** Path to the Python player-lib package directory (library). */
+const PYTHON_LIB_DIR = path.resolve(__dirname, "../../../player-lib-python");
+/** Path to the Python dev-player module (CLI entry point). */
+const DEV_PLAYER_DIR = path.resolve(__dirname, "../../python");
+/**
+ * Find a working system Python (>= 3.10).
+ * Tries python3, then python.
+ */
+function findSystemPython() {
+    for (const candidate of ["python3", "python"]) {
+        try {
+            const version = execSync(`${candidate} --version 2>&1`, { encoding: "utf-8" }).trim();
+            // Ensure it's at least 3.10
+            const match = version.match(/Python (\d+)\.(\d+)/);
+            if (match) {
+                const major = parseInt(match[1], 10);
+                const minor = parseInt(match[2], 10);
+                if (major === 3 && minor >= 10) {
+                    return candidate;
+                }
+            }
+        }
+        catch {
+            // Not found, try next
+        }
+    }
+    throw new Error("Python 3.10+ is required but not found on PATH. " +
+        "Install Python and ensure 'python3' or 'python' is available.");
+}
+export const pythonRuntime = {
+    name: "python",
+    async ensureReady(projectRoot) {
+        const venvDir = path.join(projectRoot, ".appstrata", "python-venv");
+        const venvPython = path.join(venvDir, "bin", "python");
+        if (fs.existsSync(venvPython)) {
+            // Venv already exists — check if deps are installed
+            try {
+                execSync(`${venvPython} -c "import aiohttp"`, { stdio: "ignore" });
+                console.log("  Python venv ready at", venvDir);
+                return;
+            }
+            catch {
+                // aiohttp not installed, reinstall below
+            }
+        }
+        console.log("  Setting up Python environment...");
+        const systemPython = findSystemPython();
+        console.log(`  Found ${systemPython}`);
+        // Create venv
+        if (!fs.existsSync(venvDir)) {
+            fs.mkdirSync(venvDir, { recursive: true });
+            console.log("  Creating venv...");
+            execSync(`${systemPython} -m venv "${venvDir}"`, { stdio: "inherit" });
+        }
+        // Install dependencies
+        const requirementsPath = path.join(PYTHON_LIB_DIR, "requirements.txt");
+        console.log("  Installing Python dependencies...");
+        execSync(`"${venvPython}" -m pip install -q -r "${requirementsPath}"`, {
+            stdio: "inherit",
+        });
+        console.log("  Python environment ready");
+    },
+    spawn(options) {
+        const venvPython = path.join(process.cwd(), ".appstrata", "python-venv", "bin", "python");
+        const args = [
+            "-m",
+            "appstrata_dev_player",
+            "--port",
+            String(options.port),
+            "--transport",
+            options.transport,
+        ];
+        if (options.host) {
+            args.push("--host");
+        }
+        const child = spawn(venvPython, args, {
+            env: {
+                ...process.env,
+                PYTHONPATH: [PYTHON_LIB_DIR, DEV_PLAYER_DIR].join(path.delimiter),
+                PYTHONUNBUFFERED: "1",
+            },
+            stdio: ["pipe", "inherit", "inherit"],
+        });
+        // Promise that resolves when the process exits
+        const exited = new Promise((resolve) => {
+            child.on("exit", (code) => resolve(code));
+            child.on("error", () => resolve(null));
+        });
+        return {
+            child,
+            sendConfig(config) {
+                if (child.stdin && !child.stdin.destroyed) {
+                    child.stdin.write(JSON.stringify(config) + "\n");
+                }
+            },
+            kill() {
+                if (!child.killed) {
+                    child.kill("SIGTERM");
+                }
+            },
+            exited,
+        };
+    },
+};

package/dist/runtimes/types.d.ts

@@ -0,0 +1,74 @@
+/**
+ * External runtime abstraction.
+ *
+ * Defines the interface that all external player runtimes (Python, Go, etc.)
+ * must implement. This keeps `dev-http-player.ts` free of runtime-specific
+ * logic — adding a new runtime is just a new file in this directory.
+ */
+import type { ChildProcess } from "node:child_process";
+/**
+ * Options passed to the runtime when spawning.
+ */
+export interface RuntimeSpawnOptions {
+    port: number;
+    host: boolean;
+    transport: "sse" | "polling";
+}
+/**
+ * Handle to a running external runtime process.
+ */
+export interface RuntimeProcess {
+    /** The underlying child process. */
+    child: ChildProcess;
+    /**
+     * Send a config object to the runtime process.
+     * Serialized as a single JSON line written to stdin.
+     */
+    sendConfig(config: object): void;
+    /**
+     * Kill the runtime process.
+     */
+    kill(): void;
+    /**
+     * Promise that resolves with the exit code when the process exits.
+     */
+    exited: Promise<number | null>;
+}
+/**
+ * External runtime interface.
+ *
+ * Each runtime (Python, Go, etc.) implements this interface.
+ * The `dev-http-player` command uses it to delegate execution.
+ *
+ * @example Adding a new runtime:
+ * ```ts
+ * // runtimes/go.ts
+ * export const goRuntime: ExternalRuntime = {
+ *   name: "go",
+ *   async ensureReady(projectRoot) { ... },
+ *   spawn(options) { ... },
+ * };
+ * ```
+ */
+export interface ExternalRuntime {
+    /** Display name of the runtime (e.g., "python", "go"). */
+    readonly name: string;
+    /**
+     * Ensure the runtime environment is ready.
+     *
+     * For Python: creates a venv and installs aiohttp.
+     * For Go: might compile the binary, etc.
+     *
+     * @param projectRoot - Absolute path to the project root.
+     * @throws If the runtime cannot be set up (e.g., Python not installed).
+     */
+    ensureReady(projectRoot: string): Promise<void>;
+    /**
+     * Spawn the runtime process.
+     *
+     * @param options - Port, host, transport mode.
+     * @returns Handle to the running process.
+     */
+    spawn(options: RuntimeSpawnOptions): RuntimeProcess;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/runtimes/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/runtimes/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEvD;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,OAAO,CAAC;IACd,SAAS,EAAE,KAAK,GAAG,SAAS,CAAC;CAC9B;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,oCAAoC;IACpC,KAAK,EAAE,YAAY,CAAC;IAEpB;;;OAGG;IACH,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAEjC;;OAEG;IACH,IAAI,IAAI,IAAI,CAAC;IAEb;;OAEG;IACH,MAAM,EAAE,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;CAChC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,eAAe;IAC9B,0DAA0D;IAC1D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB;;;;;;;;OAQG;IACH,WAAW,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEhD;;;;;OAKG;IACH,KAAK,CAAC,OAAO,EAAE,mBAAmB,GAAG,cAAc,CAAC;CACrD"}

package/dist/runtimes/types.js

@@ -0,0 +1,8 @@
+/**
+ * External runtime abstraction.
+ *
+ * Defines the interface that all external player runtimes (Python, Go, etc.)
+ * must implement. This keeps `dev-http-player.ts` free of runtime-specific
+ * logic — adding a new runtime is just a new file in this directory.
+ */
+export {};