cwresdev 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,42 @@
+
+Add a script to the consuming project's `package.json`:
+
+Project shape:
+
+```text
+your-project/
+  package.json
+  virtual_env/
+    index.html
+    hello.php
+```
+
+Start the server:
+
+```powershell
+npm run dev
+```
+
+## This Package
+
+This repository is the package source. Before publishing, vendor the Windows PHP runtime into the main package:
+
+```powershell
+npm install
+npm run bundle:php
+npm test
+npm run pack:check
+```
+
+Stop any running `cwrespro` server before publishing. On Windows, a live PHP process can leave the bundled runtime partially locked, and `npm run pack:check` is meant to catch that before release.
+
+Then publish:
+
+```powershell
+npm login
+npm publish --access public
+```
+
+```powershell
+npm test
+```

package/bin/cwrespro.js

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+
+const { spawn } = require("node:child_process");
+const { formatHelp, loadConfig, parseArgv, resolveLaunchUrl, startDevServer } = require("../src");
+
+function openBrowser(url) {
+  const child = spawn("cmd", ["/c", "start", "", url], {
+    detached: true,
+    stdio: "ignore",
+    windowsHide: true,
+  });
+
+  child.unref();
+}
+
+async function main() {
+  if (process.platform !== "win32") {
+    throw new Error("cwrespro currently supports Windows only.");
+  }
+
+  const argv = parseArgv(process.argv.slice(2));
+
+  if (argv.help) {
+    process.stdout.write(formatHelp("cwrespro"));
+    return;
+  }
+
+  const config = loadConfig({ cwd: process.cwd(), argv });
+  const server = await startDevServer(config);
+  const launchUrl = resolveLaunchUrl(server.url, config.startPath);
+
+  process.stdout.write(`[cwrespro] Development Server (${launchUrl}) started\n`);
+
+  if (config.openBrowser) {
+    openBrowser(launchUrl);
+  }
+
+  let closing = false;
+
+  const shutdown = async (signal) => {
+    if (closing) {
+      return;
+    }
+
+    closing = true;
+    process.stdout.write(`[cwrespro] Shutting down (${signal})...\n`);
+    await server.close();
+    process.exit(0);
+  };
+
+  ["SIGINT", "SIGTERM"].forEach((signal) => {
+    process.on(signal, () => {
+      shutdown(signal).catch((error) => {
+        process.stderr.write(`[cwrespro] ${error.message}\n`);
+        process.exit(1);
+      });
+    });
+  });
+}
+
+main().catch((error) => {
+  process.stderr.write(`[cwrespro] ${error.message}\n`);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "cwresdev",
+  "version": "0.1.0",
+  "description": "",
+  "license": "MIT",
+  "private": false,
+  "type": "commonjs",
+  "main": "./src/index.js",
+  "bin": {
+    "cwrespro": "bin/cwrespro.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "vendor/php/windows",
+    "README.md",
+    "LICENSE",
+    "THIRD_PARTY_NOTICES.md"
+  ],
+  "os": [
+    "win32"
+  ],
+  "engines": {
+    "node": ">=20.11"
+  },
+  "scripts": {
+    "start": "node ./bin/cwrespro.js",
+    "dev": "node ./bin/cwrespro.js",
+    "test": "node --test",
+    "bundle:php": "node ./scripts/vendor-php.mjs",
+    "pack:check": "node ./scripts/verify-publish.mjs",
+    "pack:dry-run": "npm pack --dry-run",
+    "prepublishOnly": "npm test && npm run pack:check"
+  },
+  "keywords": [
+    "live-server",
+    "php",
+    "courseware",
+    "proxy",
+    "windows"
+  ],
+  "dependencies": {
+    "chokidar": "^4.0.3",
+    "express": "^4.21.2",
+    "ws": "^8.18.2"
+  }
+}

package/src/client/reload-client.js

@@ -0,0 +1,40 @@
+(function cwresproReloadClient() {
+  const socketPath = "/__cwrespro/ws";
+  let reconnectDelay = 500;
+  let reconnectTimer = null;
+
+  function connect() {
+    const protocol = window.location.protocol === "https:" ? "wss:" : "ws:";
+    const socket = new WebSocket(`${protocol}//${window.location.host}${socketPath}`);
+
+    socket.addEventListener("open", function handleOpen() {
+      reconnectDelay = 500;
+    });
+
+    socket.addEventListener("message", function handleMessage(event) {
+      if (event.data === "reload") {
+        window.location.reload();
+      }
+    });
+
+    socket.addEventListener("close", function handleClose() {
+      reconnectTimer = window.setTimeout(connect, reconnectDelay);
+      reconnectDelay = Math.min(reconnectDelay * 2, 5000);
+    });
+
+    socket.addEventListener("error", function handleError() {
+      socket.close();
+    });
+  }
+
+  if (!window.__cwresproReloadClientLoaded) {
+    window.__cwresproReloadClientLoaded = true;
+    connect();
+  }
+
+  window.addEventListener("beforeunload", function cleanup() {
+    if (reconnectTimer !== null) {
+      window.clearTimeout(reconnectTimer);
+    }
+  });
+})();

package/src/config.js

@@ -0,0 +1,211 @@
+const fs = require("node:fs");
+const path = require("node:path");
+
+const DEFAULT_CONFIG_FILE = "cwrespro.config.json";
+const DEFAULT_PROXY_ORIGIN = "https:" + "//cour" + "sewareob" + "jects.else" + "vier.c" + "om";
+const DEFAULT_START_PATH = "index.html";
+
+function parseArgv(argv) {
+  const parsed = {
+    help: false,
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+
+    if (token === "--help" || token === "-h") {
+      parsed.help = true;
+      continue;
+    }
+
+    if (token === "--open" || token === "-o") {
+      parsed.openBrowser = true;
+      continue;
+    }
+
+    if (token === "--no-open") {
+      parsed.openBrowser = false;
+      continue;
+    }
+
+    if (token === "--quiet") {
+      parsed.quiet = true;
+      continue;
+    }
+
+    if (["--port", "-p", "--host", "--doc-root", "--proxy-origin", "--config", "--php-binary", "--start-path"].includes(token)) {
+      const value = argv[index + 1];
+
+      if (typeof value === "undefined") {
+        throw new Error(`Missing value for ${token}`);
+      }
+
+      index += 1;
+
+      if (token === "--port" || token === "-p") {
+        parsed.port = Number(value);
+      } else if (token === "--host") {
+        parsed.host = value;
+      } else if (token === "--doc-root") {
+        parsed.docRoot = value;
+      } else if (token === "--proxy-origin") {
+        parsed.proxyOrigin = value;
+      } else if (token === "--config") {
+        parsed.configPath = value;
+      } else if (token === "--php-binary") {
+        parsed.phpBinary = value;
+      } else if (token === "--start-path") {
+        parsed.startPath = value;
+      }
+
+      continue;
+    }
+
+    throw new Error(`Unknown argument: ${token}`);
+  }
+
+  return parsed;
+}
+
+function readConfigFile(configPath) {
+  if (!fs.existsSync(configPath)) {
+    return {};
+  }
+
+  const fileText = fs.readFileSync(configPath, "utf8");
+  return JSON.parse(fileText);
+}
+
+function readProjectPackageConfig(cwd) {
+  const packageJsonPath = path.resolve(cwd, "package.json");
+
+  if (!fs.existsSync(packageJsonPath)) {
+    return {};
+  }
+
+  const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, "utf8"));
+
+  if (!packageJson.cwrespro || typeof packageJson.cwrespro !== "object" || Array.isArray(packageJson.cwrespro)) {
+    return {};
+  }
+
+  return packageJson.cwrespro;
+}
+
+function normalizeStartPath(startPath) {
+  if (typeof startPath !== "string") {
+    return DEFAULT_START_PATH;
+  }
+
+  const trimmed = startPath.trim();
+
+  if (!trimmed) {
+    return DEFAULT_START_PATH;
+  }
+
+  return trimmed.replace(/^\.\//, "");
+}
+
+function resolveLaunchUrl(baseUrl, startPath) {
+  const normalizedPath = normalizeStartPath(startPath);
+  return new URL(normalizedPath, baseUrl).toString();
+}
+
+function validatePort(port) {
+  if (!Number.isInteger(port) || port < 0 || port > 65535) {
+    throw new Error(`Invalid port: ${port}`);
+  }
+}
+
+function validateConfig(config) {
+  validatePort(config.port);
+
+  if (!config.host || typeof config.host !== "string") {
+    throw new Error("host must be a non-empty string.");
+  }
+
+  if (!config.docRoot || typeof config.docRoot !== "string") {
+    throw new Error("docRoot must be a non-empty string.");
+  }
+
+  if (!config.startPath || typeof config.startPath !== "string") {
+    throw new Error("startPath must be a non-empty string.");
+  }
+
+  try {
+    new URL(config.proxyOrigin);
+  } catch (error) {
+    throw new Error(`Invalid proxy origin: ${config.proxyOrigin}`);
+  }
+}
+
+function loadConfig({ cwd, argv }) {
+  const configPath = argv.configPath ? path.resolve(cwd, argv.configPath) : null;
+  const fileConfig = configPath ? readConfigFile(configPath) : {};
+  const packageConfig = readProjectPackageConfig(cwd);
+
+  const config = {
+    cwd,
+    host: argv.host || fileConfig.host || packageConfig.host || "127.0.0.1",
+    port: typeof argv.port === "number" && !Number.isNaN(argv.port)
+      ? argv.port
+      : typeof fileConfig.port === "number"
+        ? fileConfig.port
+        : typeof packageConfig.port === "number"
+          ? packageConfig.port
+          : 3000,
+    docRoot: path.resolve(cwd, argv.docRoot || fileConfig.docRoot || packageConfig.docRoot || "virtual_env"),
+    proxyOrigin: argv.proxyOrigin || fileConfig.proxyOrigin || packageConfig.proxyOrigin || DEFAULT_PROXY_ORIGIN,
+    openBrowser: typeof argv.openBrowser === "boolean"
+      ? argv.openBrowser
+      : typeof fileConfig.openBrowser === "boolean"
+        ? fileConfig.openBrowser
+        : typeof packageConfig.openBrowser === "boolean"
+          ? packageConfig.openBrowser
+          : true,
+    phpBinary: argv.phpBinary || fileConfig.phpBinary || packageConfig.phpBinary || null,
+    quiet: Boolean(argv.quiet || fileConfig.quiet || packageConfig.quiet),
+    startPath: normalizeStartPath(argv.startPath || fileConfig.startPath || packageConfig.startPath || DEFAULT_START_PATH),
+    watchIgnored: Array.isArray(fileConfig.watchIgnored)
+      ? fileConfig.watchIgnored
+      : Array.isArray(packageConfig.watchIgnored)
+        ? packageConfig.watchIgnored
+        : [],
+  };
+
+  validateConfig(config);
+
+  return config;
+}
+
+function formatHelp(binName) {
+  return [
+    `${binName} [options]`,
+    "",
+    "Options:",
+    "  -h, --help              Show this help message",
+    "  -p, --port <port>       HTTP port to bind. Use 0 for a random port.",
+    "      --host <host>       Host to bind. Default: 127.0.0.1",
+    "      --doc-root <path>   Project doc root. Default: ./virtual_env",
+    "      --proxy-origin <u>  Upstream origin for /objects/* proxying",
+    "      --start-path <p>    Initial page path. Default: index.html",
+    "      --config <path>     Optional explicit config JSON path",
+    "      --php-binary <p>    Override the bundled php.exe path",
+    "  -o, --open              Open the browser after startup",
+    "      --no-open           Do not open the browser",
+    "      --quiet             Reduce console logging",
+    "",
+    `Built-in defaults are used unless --config points to ${DEFAULT_CONFIG_FILE}.`,
+    "",
+  ].join("\n");
+}
+
+module.exports = {
+  DEFAULT_CONFIG_FILE,
+  DEFAULT_PROXY_ORIGIN,
+  DEFAULT_START_PATH,
+  formatHelp,
+  loadConfig,
+  parseArgv,
+  resolveLaunchUrl,
+};

package/src/index.js

@@ -0,0 +1,19 @@
+const {
+  DEFAULT_CONFIG_FILE,
+  DEFAULT_START_PATH,
+  formatHelp,
+  loadConfig,
+  parseArgv,
+  resolveLaunchUrl,
+} = require("./config");
+const { startDevServer } = require("./server");
+
+module.exports = {
+  DEFAULT_CONFIG_FILE,
+  DEFAULT_START_PATH,
+  formatHelp,
+  loadConfig,
+  parseArgv,
+  resolveLaunchUrl,
+  startDevServer,
+};

package/src/injector.js

@@ -0,0 +1,32 @@
+const fs = require("node:fs");
+const path = require("node:path");
+
+const CLIENT_SCRIPT_ROUTE = "/__cwrespro/client.js";
+const CLIENT_SCRIPT_TAG = `<script src="${CLIENT_SCRIPT_ROUTE}" data-cwrespro="true"></script>`;
+
+function injectLiveReload(html) {
+  if (html.includes(CLIENT_SCRIPT_ROUTE)) {
+    return html;
+  }
+
+  if (/<\/body>/i.test(html)) {
+    return html.replace(/<\/body>/i, `${CLIENT_SCRIPT_TAG}</body>`);
+  }
+
+  if (/<\/head>/i.test(html)) {
+    return html.replace(/<\/head>/i, `${CLIENT_SCRIPT_TAG}</head>`);
+  }
+
+  return `${html}${CLIENT_SCRIPT_TAG}`;
+}
+
+function getClientScriptSource() {
+  const clientScriptPath = path.resolve(__dirname, "client", "reload-client.js");
+  return fs.readFileSync(clientScriptPath, "utf8");
+}
+
+module.exports = {
+  CLIENT_SCRIPT_ROUTE,
+  getClientScriptSource,
+  injectLiveReload,
+};

package/src/php.js

@@ -0,0 +1,114 @@
+const fs = require("node:fs");
+const net = require("node:net");
+const path = require("node:path");
+const { spawn } = require("node:child_process");
+
+const BUNDLED_PHP_RELATIVE_PATH = path.join("vendor", "php", "windows", "php.exe");
+
+function resolvePhpBinary({ packageRoot, phpBinary }) {
+  const binaryPath = phpBinary
+    ? path.resolve(phpBinary)
+    : path.resolve(packageRoot, BUNDLED_PHP_RELATIVE_PATH);
+
+  if (!fs.existsSync(binaryPath)) {
+    throw new Error(
+      [
+        `Bundled PHP runtime not found at ${binaryPath}.`,
+        "Run `npm run bundle:php` before publishing or override the binary path with --php-binary.",
+      ].join(" ")
+    );
+  }
+
+  return binaryPath;
+}
+
+function findAvailablePort(host) {
+  return new Promise((resolve, reject) => {
+    const server = net.createServer();
+    server.unref();
+
+    server.on("error", reject);
+    server.listen(0, host, () => {
+      const address = server.address();
+      server.close(() => resolve(address.port));
+    });
+  });
+}
+
+async function waitForPhpServer(baseUrl, timeoutMs) {
+  const startedAt = Date.now();
+  const probeUrl = `${baseUrl}/__cwrespro_ready_probe__`;
+
+  while (Date.now() - startedAt < timeoutMs) {
+    try {
+      await fetch(probeUrl, { method: "GET" });
+      return;
+    } catch (error) {
+      await new Promise((resolve) => setTimeout(resolve, 150));
+    }
+  }
+
+  throw new Error(`Timed out waiting for PHP server at ${baseUrl}`);
+}
+
+async function startPhpServer({ packageRoot, docRoot, host, logger, phpBinary }) {
+  const binaryPath = resolvePhpBinary({ packageRoot, phpBinary });
+  const runtimeDir = path.dirname(binaryPath);
+  const phpIniPath = path.join(runtimeDir, "php.ini");
+  const port = await findAvailablePort(host);
+  const baseUrl = `http://${host}:${port}`;
+  const args = [];
+
+  if (fs.existsSync(phpIniPath)) {
+    args.push("-c", runtimeDir);
+  }
+
+  const stubsDir = path.join(packageRoot, "stubs");
+  const routerFile = path.join(stubsDir, "router.php");
+
+  args.push("-d", "include_path=" + docRoot + path.delimiter + stubsDir + path.delimiter + ".");
+  args.push("-S", `${host}:${port}`, "-t", docRoot);
+
+  if (fs.existsSync(routerFile)) {
+    args.push(routerFile);
+  }
+
+  const child = spawn(binaryPath, args, {
+    cwd: docRoot,
+    stdio: ["ignore", "pipe", "pipe"],
+    windowsHide: true,
+  });
+
+  const exitedEarly = new Promise((_, reject) => {
+    child.once("exit", (code, signal) => {
+      reject(new Error(`Bundled PHP exited before startup completed (code=${code}, signal=${signal || "none"}).`));
+    });
+  });
+
+  await Promise.race([waitForPhpServer(baseUrl, 10000), exitedEarly]);
+
+  return {
+    baseUrl,
+    binaryPath,
+    child,
+    port,
+  };
+}
+
+async function stopPhpServer(phpServer) {
+  if (!phpServer || !phpServer.child || phpServer.child.exitCode !== null) {
+    return;
+  }
+
+  await new Promise((resolve) => {
+    phpServer.child.once("exit", resolve);
+    phpServer.child.kill();
+  });
+}
+
+module.exports = {
+  BUNDLED_PHP_RELATIVE_PATH,
+  resolvePhpBinary,
+  startPhpServer,
+  stopPhpServer,
+};

package/src/proxy.js

@@ -0,0 +1,91 @@
+const { Readable } = require("node:stream");
+const { injectLiveReload } = require("./injector");
+
+function stripHopByHopHeaders(headers) {
+  const nextHeaders = { ...headers };
+  delete nextHeaders.host;
+  delete nextHeaders.connection;
+  delete nextHeaders["content-length"];
+  delete nextHeaders["transfer-encoding"];
+  return nextHeaders;
+}
+
+function buildTargetUrl(baseUrl, req) {
+  return new URL(req.originalUrl || req.url, baseUrl).toString();
+}
+
+function isHtmlResponse(contentType) {
+  return typeof contentType === "string" && contentType.toLowerCase().includes("text/html");
+}
+
+function applyResponseHeaders(upstreamHeaders, res, omitHeaders) {
+  upstreamHeaders.forEach((value, key) => {
+    if (omitHeaders.has(key.toLowerCase())) {
+      return;
+    }
+
+    res.setHeader(key, value);
+  });
+}
+
+async function readRequestBody(req) {
+  if (req.method === "GET" || req.method === "HEAD") {
+    return null;
+  }
+
+  const chunks = [];
+
+  for await (const chunk of req) {
+    chunks.push(chunk);
+  }
+
+  if (chunks.length === 0) {
+    return null;
+  }
+
+  return Buffer.concat(chunks);
+}
+
+async function proxyRequest({ req, res, target, injectHtml = false }) {
+  const body = await readRequestBody(req);
+  const upstream = await fetch(target, {
+    method: req.method,
+    headers: stripHopByHopHeaders(req.headers),
+    body,
+    redirect: "manual",
+  });
+
+  res.status(upstream.status);
+
+  const omittedHeaders = new Set([
+    "content-encoding",
+    "content-length",
+    "transfer-encoding",
+  ]);
+
+  applyResponseHeaders(upstream.headers, res, omittedHeaders);
+
+  if (req.method === "HEAD" || upstream.status === 204 || upstream.status === 304) {
+    res.end();
+    return;
+  }
+
+  if (injectHtml && isHtmlResponse(upstream.headers.get("content-type"))) {
+    const html = await upstream.text();
+    res.type("html");
+    res.end(injectLiveReload(html));
+    return;
+  }
+
+  if (!upstream.body) {
+    res.end();
+    return;
+  }
+
+  Readable.fromWeb(upstream.body).pipe(res);
+}
+
+module.exports = {
+  buildTargetUrl,
+  proxyRequest,
+};