Apply suggestions from code review

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

.github/copilot-instructions.md

@@ -25,7 +25,8 @@ yarn lint          # ESLint + Prettier + TypeScript + Lit
 yarn format        # Auto-fix ESLint + Prettier
 yarn lint:types    # TypeScript compiler (run WITHOUT file arguments)
 yarn test          # Vitest
-script/develop     # Development server
+yarn dev           # Dev server (app; --background/--status/--stop/--logs)
+yarn dev:serve     # Dev server with serve (-c core URL, -p port; --background/--status/--stop/--logs)
 ```
 
 > **WARNING:** Never run `tsc` or `yarn lint:types` with file arguments (e.g., `yarn lint:types src/file.ts`). When `tsc` receives file arguments, it ignores `tsconfig.json` and emits `.js` files into `src/`, polluting the codebase. Always run `yarn lint:types` without arguments. For individual file type checking, rely on IDE diagnostics. If `.js` files are accidentally generated, clean up with `git clean -fd src/`.
@@ -495,6 +496,26 @@ this.hass.localize("ui.panel.config.updates.update_available", {
 4. **Test**: `yarn test` - Add and run tests
 5. **Build**: `script/build_frontend` - Test production build
 
+### Dev servers
+
+`yarn dev` builds and watches the app, served by a running Home Assistant core (`development_repo` setting). `yarn dev:serve` also serves it locally (`-c` core URL, `-p` port, default 8124).
+
+These and the e2e dev servers below take `--background`, `--status`, `--stop`, and `--logs [--follow]`.
+
+### End-to-end (e2e) tests
+
+Each Playwright suite has a dev server on its own port. Playwright reuses a server already on the port (`reuseExistingServer` locally); otherwise it does a slow full build. The rspack watcher recompiles on save, so re-runs need no restart.
+
+Start the suite's dev server, then run the suite:
+
+- **App** (8095): `yarn test:e2e:app:dev`, then `yarn test:e2e:app`
+- **Demo** (8090): `yarn dev:demo`, then `yarn test:e2e:demo`
+- **Gallery** (8100): `yarn dev:gallery`, then `yarn test:e2e:gallery`
+
+Server reuse and `--stop` key off a `/__ha_dev_status` health check, so starting or stopping twice is harmless. The app suite uses a stripped-down harness built only for e2e; demo and gallery use their normal dev servers.
+
+Add `-g "<title>" --project=chromium` to narrow a run; `yarn test:e2e` runs all three. Run the suite directly, since piping through `tail`/`head` hides progress and truncates results.
+
 ### Gallery
 
 For Gallery-specific structure, page/demo naming, sidebar behavior, content standards, and commands, see [`gallery/AGENTS.md`](gallery/AGENTS.md).

build-scripts/dev-server.mjs

@@ -0,0 +1,678 @@
+// Manage a Home Assistant frontend dev server with an agent-friendly interface.
+//
+//   node build-scripts/dev-server.mjs --suite <suite> [mode] [extra args]
+//
+//   (no mode)          Run in the foreground.
+//   --background       Start detached, wait until it is ready, print the URL
+//                      (when it has one) and pid, then exit and leave it running.
+//   --status           Report whether the suite's dev server is running.
+//   --stop             Stop a running background dev server.
+//   --logs [--follow]  Print (or follow) the background dev server log.
+//
+// Extra args (for example -p or -c on app-serve) are forwarded to the underlying
+// script. Suites use one of two liveness models:
+//
+//   health   demo, gallery, e2e-app: a fixed port plus the /__ha_dev_status
+//            endpoint each dev server exposes (see runDevServer in
+//            build-scripts/gulp/rspack.js). The port is the source of truth and
+//            the pid is found from it; no state file.
+//   process  app (yarn dev) and app-serve (yarn dev:serve): the app watcher has
+//            no health endpoint, and plain yarn dev has no port at all, so these
+//            track a pidfile and treat the first "Build done" log line as ready.
+
+import { spawn, execFileSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const repoRoot = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  ".."
+);
+const gulpBin = path.join(repoRoot, "node_modules", ".bin", "gulp");
+const developAndServeScript = path.join(
+  repoRoot,
+  "script",
+  "develop_and_serve"
+);
+const logDir = path.join(repoRoot, "node_modules", ".cache", "ha-dev-server");
+
+// Each suite names its yarn alias (for hints), a liveness model, and how to
+// spawn it. health suites carry a fixed port; process suites carry the log line
+// that means "ready" and, for app-serve, forward extra args to the script.
+const SUITES = {
+  "e2e-app": {
+    alias: "test:e2e:app:dev",
+    liveness: "health",
+    port: 8095,
+    spawn: { cmd: gulpBin, args: ["develop-e2e-test-app"] },
+  },
+  demo: {
+    alias: "dev:demo",
+    liveness: "health",
+    port: 8090,
+    spawn: { cmd: gulpBin, args: ["develop-demo"] },
+  },
+  gallery: {
+    alias: "dev:gallery",
+    liveness: "health",
+    port: 8100,
+    spawn: { cmd: gulpBin, args: ["develop-gallery"] },
+  },
+  app: {
+    alias: "dev",
+    liveness: "process",
+    readyLog: /Build done @/,
+    spawn: { cmd: gulpBin, args: ["develop-app"] },
+  },
+  "app-serve": {
+    alias: "dev:serve",
+    liveness: "process",
+    acceptsArgs: true,
+    readyLog: /Build done @/,
+    spawn: { cmd: developAndServeScript, args: [] },
+  },
+};
+
+// Cover a cold build on a slow machine before the server starts listening.
+// Override with HA_DEV_SERVER_TIMEOUT (seconds).
+const READY_TIMEOUT_MS =
+  Number(process.env.HA_DEV_SERVER_TIMEOUT || "180") * 1000;
+
+// Detect a coding agent from a small set of environment markers set by common
+// agent CLIs (env-only; no process-ancestry detection).
+const detectAgent = () => {
+  const env = process.env;
+  const has = (name) => Boolean(env[name]);
+  const eq = (name, value) => env[name] === value;
+  const signals = {
+    opencode: () =>
+      [
+        "OPENCODE",
+        "OPENCODE_BIN_PATH",
+        "OPENCODE_SERVER",
+        "OPENCODE_APP_INFO",
+      ].some(has),
+    "claude-code": () => has("CLAUDECODE"),
+    cursor: () => has("CURSOR_TRACE_ID"),
+    "github-copilot": () =>
+      eq("TERM_PROGRAM", "vscode") && eq("GIT_PAGER", "cat"),
+    // Convention shared by several agents (Crush, Amp, ...).
+    generic: () => has("AGENT") || has("AI_AGENT"),
+  };
+  return Object.keys(signals).find((id) => signals[id]());
+};
+
+const usage = () => {
+  const suites = Object.keys(SUITES).join("|");
+  process.stderr.write(
+    `Usage: node build-scripts/dev-server.mjs --suite <${suites}> ` +
+      `[--background | --status | --stop | --logs [--follow]]\n`
+  );
+};
+
+const parseArgs = (argv) => {
+  const args = {
+    mode: "foreground",
+    follow: false,
+    suite: undefined,
+    passthrough: [],
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    switch (arg) {
+      case "--suite":
+        args.suite = argv[++i];
+        break;
+      case "--background":
+        args.mode = "background";
+        break;
+      case "--status":
+        args.mode = "status";
+        break;
+      case "--stop":
+        args.mode = "stop";
+        break;
+      case "--logs":
+        args.mode = "logs";
+        break;
+      case "--follow":
+        args.follow = true;
+        break;
+      default:
+        // Anything unrecognised is forwarded to the underlying script.
+        args.passthrough.push(arg);
+    }
+  }
+  return args;
+};
+
+const sleep = (ms) =>
+  new Promise((resolve) => {
+    setTimeout(resolve, ms);
+  });
+
+const logFileFor = (suite) => path.join(logDir, `${suite}.log`);
+const pidFileFor = (suite) => path.join(logDir, `${suite}.pid`);
+
+const hints = (suite) => {
+  const alias = `yarn ${SUITES[suite].alias}`;
+  return (
+    `  Stop:   ${alias} --stop\n` +
+    `  Status: ${alias} --status\n` +
+    `  Logs:   ${alias} --logs\n`
+  );
+};
+
+// --- shared spawning and lifecycle ------------------------------------------
+
+// Signal the whole process group (the background server is its group leader),
+// falling back to the bare pid if that is not permitted.
+const killProcessTree = (pid, sig) => {
+  try {
+    process.kill(-pid, sig);
+  } catch {
+    try {
+      process.kill(pid, sig);
+    } catch {
+      // Already gone.
+    }
+  }
+};
+
+const urlSuffix = (port) => (port ? ` at http://localhost:${port}` : "");
+
+// Run a server in the foreground, inheriting stdio; resolve with its exit code.
+const spawnInherit = (cmd, args) =>
+  new Promise((resolve) => {
+    const child = spawn(cmd, args, { cwd: repoRoot, stdio: "inherit" });
+    child.on("exit", (code) => resolve(code ?? 0));
+  });
+
+// Spawn a detached server that writes stdout and stderr to the suite's log file.
+const spawnDetachedToLog = (suite, cmd, args) => {
+  fs.mkdirSync(logDir, { recursive: true });
+  const logFile = logFileFor(suite);
+  const fd = fs.openSync(logFile, "w");
+  const child = spawn(cmd, args, {
+    cwd: repoRoot,
+    detached: true,
+    stdio: ["ignore", fd, fd],
+  });
+  fs.closeSync(fd);
+  child.unref();
+  return { child, logFile };
+};
+
+// Poll until the server is ready, the child exits, or we time out. Prints the
+// progress dots and outcome; returns 0 when ready, 1 otherwise. onExit runs if
+// the child dies before it is ready (used to clear a stale pidfile).
+const awaitReady = async ({ suite, child, logFile, port, isReady, onExit }) => {
+  let childExited = false;
+  child.on("exit", () => {
+    childExited = true;
+  });
+  const deadline = Date.now() + READY_TIMEOUT_MS;
+  process.stdout.write(`Starting ${suite} dev server`);
+  /* eslint-disable no-await-in-loop -- poll until the server is ready */
+  while (Date.now() < deadline) {
+    if (childExited) {
+      process.stdout.write("\n");
+      process.stderr.write(
+        `Dev server (${suite}) exited before it was ready. See ${logFile}\n`
+      );
+      onExit?.();
+      return 1;
+    }
+    if (await isReady()) {
+      process.stdout.write("\n");
+      process.stdout.write(
+        `Dev server (${suite}) running${urlSuffix(port)} ` +
+          `(pid ${child.pid})\n${hints(suite)}`
+      );
+      return 0;
+    }
+    process.stdout.write(".");
+    await sleep(1000);
+  }
+  /* eslint-enable no-await-in-loop */
+  process.stdout.write("\n");
+  process.stderr.write(
+    `Dev server (${suite}) did not become ready within ${
+      READY_TIMEOUT_MS / 1000
+    }s. See ${logFile}\n`
+  );
+  return 1;
+};
+
+// Stop a running background server: SIGTERM, wait for it to go, then SIGKILL.
+// isStopped reports when it is gone; onStopped runs on success (pidfile cleanup).
+const terminate = async (suite, pid, isStopped, onStopped) => {
+  killProcessTree(pid, "SIGTERM");
+  const deadline = Date.now() + 10_000;
+  /* eslint-disable no-await-in-loop -- poll until the server is gone */
+  while (Date.now() < deadline) {
+    await sleep(300);
+    if (await isStopped()) {
+      onStopped?.();
+      process.stdout.write(`Stopped dev server (${suite}) (pid ${pid}).\n`);
+      return 0;
+    }
+  }
+  /* eslint-enable no-await-in-loop */
+  // Escalate if it is still up.
+  killProcessTree(pid, "SIGKILL");
+  await sleep(300);
+  if (!(await isStopped())) {
+    process.stderr.write(
+      `Failed to stop dev server (${suite}) (pid ${pid}). Stop it manually.\n`
+    );
+    return 1;
+  }
+  onStopped?.();
+  process.stdout.write(`Stopped dev server (${suite}) (pid ${pid}).\n`);
+  return 0;
+};
+
+// --- health liveness (port + /__ha_dev_status) ------------------------------
+
+/**
+ * Probe the health endpoint. Dev servers bind IPv4 or IPv6 localhost depending
+ * on the OS, so try each; the port is "free" only if every address refuses.
+ * @returns {Promise<{state: "ours" | "foreign" | "free", suite?: string}>}
+ */
+const PROBE_HOSTS = ["localhost", "127.0.0.1", "[::1]"];
+
+const probe = async (port, timeoutMs = 1000) => {
+  let sawResponse = false;
+  /* eslint-disable no-await-in-loop -- probe localhost addresses in order, stopping at the first that answers */
+  for (const host of PROBE_HOSTS) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+      const res = await fetch(`http://${host}:${port}/__ha_dev_status`, {
+        signal: controller.signal,
+      });
+      sawResponse = true;
+      if (res.ok) {
+        const body = await res.json().catch(() => null);
+        if (body && body.server === "ha-frontend-dev") {
+          return { state: "ours", suite: body.suite };
+        }
+      }
+    } catch {
+      // Try the next address.
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+  /* eslint-enable no-await-in-loop */
+  return sawResponse ? { state: "foreign" } : { state: "free" };
+};
+
+// Find the pid listening on a port via the first available tool (no state file).
+const pidFromPort = (port) => {
+  const attempts = [
+    [
+      "lsof",
+      ["-ti", `tcp:${port}`, "-sTCP:LISTEN"],
+      (out) => out.trim().split("\n")[0],
+    ],
+    [
+      "ss",
+      ["-ltnpH", `sport = :${port}`],
+      (out) => out.match(/pid=(\d+)/)?.[1],
+    ],
+    ["fuser", [`${port}/tcp`], (out) => out.trim().split(/\s+/)[0]],
+  ];
+  for (const [cmd, cmdArgs, extract] of attempts) {
+    try {
+      const out = execFileSync(cmd, cmdArgs, {
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "ignore"],
+      });
+      const pid = Number(extract(out));
+      if (Number.isInteger(pid) && pid > 0) {
+        return pid;
+      }
+    } catch {
+      // Try the next tool.
+    }
+  }
+  return undefined;
+};
+
+const runForegroundHealth = async (suite, cfg) => {
+  const { port } = cfg;
+  const status = await probe(port);
+  if (status.state === "ours" && status.suite === suite) {
+    process.stdout.write(
+      `Dev server (${suite}) is already running at http://localhost:${port}\n`
+    );
+    return 0;
+  }
+  if (status.state === "foreign") {
+    process.stderr.write(
+      `Port ${port} is in use by another process; not the ${suite} dev server.\n`
+    );
+    return 1;
+  }
+  return spawnInherit(cfg.spawn.cmd, cfg.spawn.args);
+};
+
+const runBackgroundHealth = async (suite, cfg) => {
+  const { port } = cfg;
+  const preflight = await probe(port);
+  if (preflight.state === "ours" && preflight.suite === suite) {
+    const pid = pidFromPort(port);
+    process.stdout.write(
+      `Dev server (${suite}) already running at http://localhost:${port}` +
+        `${pid ? ` (pid ${pid})` : ""}\n${hints(suite)}`
+    );
+    return 0;
+  }
+  if (preflight.state === "foreign") {
+    process.stderr.write(
+      `Port ${port} is in use by another process; not the ${suite} dev server.\n`
+    );
+    return 1;
+  }
+
+  const { child, logFile } = spawnDetachedToLog(
+    suite,
+    cfg.spawn.cmd,
+    cfg.spawn.args
+  );
+  return awaitReady({
+    suite,
+    child,
+    logFile,
+    port,
+    isReady: async () => {
+      const status = await probe(port, 1000);
+      return status.state === "ours" && status.suite === suite;
+    },
+  });
+};
+
+const runStatusHealth = async (suite, cfg) => {
+  const { port } = cfg;
+  const status = await probe(port);
+  if (status.state === "ours" && status.suite === suite) {
+    const pid = pidFromPort(port);
+    process.stdout.write(
+      `Dev server (${suite}) running at http://localhost:${port}` +
+        `${pid ? ` (pid ${pid})` : ""}\n`
+    );
+  } else if (status.state === "ours") {
+    process.stdout.write(
+      `Port ${port} is serving a different Home Assistant frontend dev server (suite ${status.suite ?? "unknown"}); not ${suite}.\n`
+    );
+  } else if (status.state === "foreign") {
+    process.stdout.write(
+      `Port ${port} is in use by another process; not the ${suite} dev server.\n`
+    );
+  } else {
+    process.stdout.write(`Dev server (${suite}) not running.\n`);
+  }
+  return 0;
+};
+
+const runStopHealth = async (suite, cfg) => {
+  const { port } = cfg;
+  const status = await probe(port);
+  if (!(status.state === "ours" && status.suite === suite)) {
+    // Idempotent: stopping something that is not running is a success.
+    process.stdout.write(`Dev server (${suite}) not running.\n`);
+    return 0;
+  }
+  const pid = pidFromPort(port);
+  if (!pid) {
+    process.stderr.write(
+      `Dev server (${suite}) is running but its pid could not be found ` +
+        `(no lsof/ss/fuser?). Stop it manually.\n`
+    );
+    return 1;
+  }
+  return terminate(
+    suite,
+    pid,
+    async () => (await probe(port, 800)).state === "free"
+  );
+};
+
+// --- process liveness (pidfile + log-readiness) -----------------------------
+
+const isAlive = (pid) => {
+  if (!Number.isInteger(pid) || pid <= 0) {
+    return false;
+  }
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    // EPERM means the process exists but is owned by someone else.
+    return err.code === "EPERM";
+  }
+};
+
+const readPidFile = (suite) => {
+  try {
+    const data = JSON.parse(fs.readFileSync(pidFileFor(suite), "utf8"));
+    if (data && Number.isInteger(data.pid)) {
+      return data;
+    }
+  } catch {
+    // Missing or corrupt.
+  }
+  return undefined;
+};
+
+const writePidFile = (suite, data) => {
+  fs.mkdirSync(logDir, { recursive: true });
+  fs.writeFileSync(pidFileFor(suite), JSON.stringify(data));
+};
+
+const removePidFile = (suite) => {
+  try {
+    fs.rmSync(pidFileFor(suite));
+  } catch {
+    // Already gone.
+  }
+};
+
+const logIsReady = (logFile, readyLog) => {
+  try {
+    return readyLog.test(fs.readFileSync(logFile, "utf8"));
+  } catch {
+    return false;
+  }
+};
+
+// app-serve serves on 8124 by default (8123 in a devcontainer), or whatever -p
+// the caller passed. Used only to show a URL; liveness comes from the pidfile.
+const resolveServePort = (passthrough) => {
+  const i = passthrough.indexOf("-p");
+  if (i !== -1) {
+    const port = Number(passthrough[i + 1]);
+    if (Number.isInteger(port) && port > 0) {
+      return port;
+    }
+  }
+  return process.env.DEVCONTAINER ? 8123 : 8124;
+};
+
+const spawnArgs = (cfg, passthrough) => [
+  ...cfg.spawn.args,
+  ...(cfg.acceptsArgs ? passthrough : []),
+];
+
+const runForegroundProcess = async (suite, cfg, passthrough) => {
+  const existing = readPidFile(suite);
+  if (existing && isAlive(existing.pid)) {
+    process.stdout.write(
+      `Dev server (${suite}) already running in the background ` +
+        `(pid ${existing.pid}). Stop it with yarn ${cfg.alias} --stop.\n`
+    );
+    return 0;
+  }
+  if (existing) {
+    removePidFile(suite);
+  }
+  return spawnInherit(cfg.spawn.cmd, spawnArgs(cfg, passthrough));
+};
+
+const runBackgroundProcess = async (suite, cfg, passthrough) => {
+  const existing = readPidFile(suite);
+  if (existing && isAlive(existing.pid)) {
+    process.stdout.write(
+      `Dev server (${suite}) already running${urlSuffix(existing.port)} ` +
+        `(pid ${existing.pid})\n${hints(suite)}`
+    );
+    return 0;
+  }
+  if (existing) {
+    removePidFile(suite);
+  }
+
+  const { child, logFile } = spawnDetachedToLog(
+    suite,
+    cfg.spawn.cmd,
+    spawnArgs(cfg, passthrough)
+  );
+
+  const port = cfg.acceptsArgs ? resolveServePort(passthrough) : cfg.port;
+  writePidFile(suite, { pid: child.pid, port });
+
+  return awaitReady({
+    suite,
+    child,
+    logFile,
+    port,
+    isReady: () => logIsReady(logFile, cfg.readyLog),
+    onExit: () => removePidFile(suite),
+  });
+};
+
+const runStatusProcess = async (suite) => {
+  const existing = readPidFile(suite);
+  if (existing && isAlive(existing.pid)) {
+    process.stdout.write(
+      `Dev server (${suite}) running${urlSuffix(existing.port)} ` +
+        `(pid ${existing.pid})\n`
+    );
+  } else {
+    if (existing) {
+      removePidFile(suite);
+    }
+    process.stdout.write(`Dev server (${suite}) not running.\n`);
+  }
+  return 0;
+};
+
+const runStopProcess = async (suite) => {
+  const existing = readPidFile(suite);
+  if (!existing || !isAlive(existing.pid)) {
+    // Idempotent: stopping something that is not running is a success.
+    if (existing) {
+      removePidFile(suite);
+    }
+    process.stdout.write(`Dev server (${suite}) not running.\n`);
+    return 0;
+  }
+  const { pid } = existing;
+  return terminate(
+    suite,
+    pid,
+    () => !isAlive(pid),
+    () => removePidFile(suite)
+  );
+};
+
+// --- shared -----------------------------------------------------------------
+
+const runLogs = (suite, follow) => {
+  const logFile = logFileFor(suite);
+  if (!fs.existsSync(logFile)) {
+    process.stdout.write(
+      `No log for the ${suite} dev server yet (${logFile}).\n`
+    );
+    return Promise.resolve(0);
+  }
+  if (!follow) {
+    process.stdout.write(fs.readFileSync(logFile, "utf8"));
+    return Promise.resolve(0);
+  }
+  return new Promise((resolve) => {
+    const tail = spawn("tail", ["-f", logFile], { stdio: "inherit" });
+    tail.on("error", () => {
+      // No tail available; fall back to a one-shot dump.
+      process.stdout.write(fs.readFileSync(logFile, "utf8"));
+      resolve(0);
+    });
+    tail.on("exit", (code) => resolve(code ?? 0));
+  });
+};
+
+const main = async () => {
+  const args = parseArgs(process.argv.slice(2));
+  const cfg = SUITES[args.suite];
+  if (!cfg) {
+    usage();
+    return 1;
+  }
+  if (args.passthrough.length && !cfg.acceptsArgs) {
+    process.stderr.write(
+      `Ignoring unexpected arguments: ${args.passthrough.join(" ")}\n`
+    );
+  }
+
+  // A plain dev:<suite> under a coding agent backgrounds itself; explicit modes
+  // are untouched.
+  let { mode } = args;
+  if (
+    mode === "foreground" &&
+    !["0", "false"].includes(process.env.HA_DEV_BACKGROUND)
+  ) {
+    const agent = detectAgent();
+    if (agent) {
+      process.stdout.write(
+        `Detected coding agent (${agent}); starting in the background. ` +
+          `Set HA_DEV_BACKGROUND=0 to force foreground.\n`
+      );
+      mode = "background";
+    }
+  }
+
+  const health = cfg.liveness === "health";
+  switch (mode) {
+    case "background":
+      return health
+        ? runBackgroundHealth(args.suite, cfg)
+        : runBackgroundProcess(args.suite, cfg, args.passthrough);
+    case "status":
+      return health
+        ? runStatusHealth(args.suite, cfg)
+        : runStatusProcess(args.suite);
+    case "stop":
+      return health
+        ? runStopHealth(args.suite, cfg)
+        : runStopProcess(args.suite);
+    case "logs":
+      return runLogs(args.suite, args.follow);
+    default:
+      return health
+        ? runForegroundHealth(args.suite, cfg)
+        : runForegroundProcess(args.suite, cfg, args.passthrough);
+  }
+};
+
+main().then(
+  (code) => {
+    process.exitCode = code;
+  },
+  (err) => {
+    process.stderr.write(`${err?.stack || err}\n`);
+    process.exitCode = 1;
+  }
+);

build-scripts/gulp/rspack.js

@@ -37,6 +37,7 @@ const isWsl =
  *   listenHost?: string,
  *   open?: boolean,
  *   logUrlAfterFirstBuild?: boolean,
+ *   suite?: string,
  * }}
  */
 const runDevServer = async ({
@@ -47,6 +48,7 @@ const runDevServer = async ({
   open = true,
   logUrlAfterFirstBuild = false,
   proxy = undefined,
+  suite = undefined,
 }) => {
   if (listenHost === undefined) {
     // For dev container, we need to listen on all hosts
@@ -81,6 +83,19 @@ const runDevServer = async ({
             !error?.message?.includes("ResizeObserver loop"),
         },
       },
+      setupMiddlewares: (middlewares) => {
+        // Status endpoint so the dev-server manager can confirm this is our
+        // server for the expected suite. Unshifted to beat the static handler.
+        middlewares.unshift({
+          name: "ha-dev-status",
+          path: "/__ha_dev_status",
+          middleware: (_req, res) => {
+            res.setHeader("Content-Type", "application/json");
+            res.end(JSON.stringify({ server: "ha-frontend-dev", suite, port }));
+          },
+        });
+        return middlewares;
+      },
       proxy,
     },
     compiler
@@ -152,6 +167,8 @@ gulp.task("rspack-dev-server-demo", () =>
     ),
     contentBase: paths.demo_output_root,
     port: 8090,
+    open: false,
+    suite: "demo",
   })
 );
 
@@ -173,6 +190,7 @@ gulp.task("rspack-dev-server-cast", () =>
     port: 8080,
     // Accessible from the network, because that's how Cast hits it.
     listenHost: "0.0.0.0",
+    suite: "cast",
   })
 );
 
@@ -194,6 +212,7 @@ gulp.task("rspack-dev-server-gallery", () =>
     listenHost: "0.0.0.0",
     open: false,
     logUrlAfterFirstBuild: true,
+    suite: "gallery",
   })
 );
 
@@ -241,6 +260,7 @@ gulp.task("rspack-dev-server-e2e-test-app", () =>
     contentBase: paths.e2eTestApp_output_root,
     port: 8095,
     open: false,
+    suite: "e2e-app",
   })
 );
 

demo/script/develop_demo

@@ -1,9 +1,10 @@
 #!/bin/sh
-# Develop the demo
+# Develop the demo. Pass --background/--status/--stop/--logs to manage a
+# detached instance (see build-scripts/dev-server.mjs).
 
 # Stop on errors
 set -e
 
 cd "$(dirname "$0")/../.."
 
-./node_modules/.bin/gulp develop-demo
+exec node build-scripts/dev-server.mjs --suite demo "$@"

gallery/script/develop_gallery

@@ -1,9 +1,10 @@
 #!/bin/sh
-# Run the gallery
+# Run the gallery. Pass --background/--status/--stop/--logs to manage a
+# detached instance (see build-scripts/dev-server.mjs).
 
 # Stop on errors
 set -e
 
 cd "$(dirname "$0")/../.."
 
-./node_modules/.bin/gulp develop-gallery
+exec node build-scripts/dev-server.mjs --suite gallery "$@"

package.json

@@ -24,6 +24,10 @@
     "test:bench": "vitest bench --run --config test/vitest.bench.config.ts",
     "test:coverage": "vitest run --config test/vitest.config.ts --coverage",
     "check-bundlesize": "node build-scripts/check-bundle-size.cjs",
+    "dev": "node build-scripts/dev-server.mjs --suite app",
+    "dev:serve": "node build-scripts/dev-server.mjs --suite app-serve",
+    "dev:demo": "demo/script/develop_demo",
+    "dev:gallery": "gallery/script/develop_gallery",
     "test:e2e": "node test/e2e/run-suites.mjs demo app gallery",
     "test:e2e:show-report": "yarn playwright show-report test/e2e/reports/combined",
     "test:e2e:demo": "playwright test --config test/e2e/playwright.demo.config.ts",

test/e2e/app/script/develop_app

@@ -1,9 +1,10 @@
 #!/bin/sh
-# Develop the e2e test app
+# Develop the e2e test app. Pass --background/--status/--stop/--logs to manage a
+# detached instance (see build-scripts/dev-server.mjs).
 
 # Stop on errors
 set -e
 
 cd "$(dirname "$0")/../../../.."
 
-./node_modules/.bin/gulp develop-e2e-test-app
+exec node build-scripts/dev-server.mjs --suite e2e-app "$@"