@triflare/fx 0.0.0-stage → 1.0.1

package/src/dev.js

@@ -0,0 +1,390 @@
+/**
+ * Development server for `fx dev`.
+ *
+ * The server builds through a caller-provided callback, compares the finished
+ * HTML with the previous result, and only tells connected browsers to reload
+ * when the bytes actually changed. Build errors keep the last good page and
+ * are reported over Server-Sent Events.
+ */
+import fs from "node:fs";
+import http from "node:http";
+import os from "node:os";
+import path from "node:path";
+
+const IGNORED_SEGMENTS = new Set([
+  "node_modules",
+  ".git",
+  "build",
+  "dist",
+  "coverage",
+  ".cache",
+  ".smoke",
+  ".vscode",
+  ".vscode-test",
+  ".vscode-test-web",
+  "vendor",
+  "reference",
+]);
+
+const DEV_EVENTS_PATH = "/__fx/events";
+const DEV_STATUS_PATH = "/__fx/status";
+
+function isWildcardHost(host) {
+  return host === "0.0.0.0" || host === "::" || host === "[::]";
+}
+
+function urlHost(host) {
+  if (host.includes(":") && !host.startsWith("[")) return `[${host}]`;
+  return host;
+}
+
+function ignoredFile(filename) {
+  if (!filename) return false;
+  return filename.split(/[\\/]/).some((segment) => {
+    if (!segment) return false;
+    if (IGNORED_SEGMENTS.has(segment)) return true;
+    return segment.startsWith(".") && segment !== ".";
+  });
+}
+
+function escapeHtml(text) {
+  return String(text)
+    .replaceAll("&", "&")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;");
+}
+
+/**
+ * @param {string} html
+ * @returns {string}
+ */
+export function injectDevClient(html) {
+  if (html.includes("data-fx-dev")) return html;
+  const script = `<script data-fx-dev>
+(() => {
+  if (window.__fxDevClient) return;
+  window.__fxDevClient = true;
+  let banner = null;
+  const showError = (message) => {
+    if (!banner) {
+      banner = document.createElement("pre");
+      banner.id = "__fx_dev_error";
+      banner.style.cssText = "position:fixed;left:0;right:0;bottom:0;max-height:45vh;overflow:auto;margin:0;padding:12px;background:#210b0b;color:#ffb4b4;border-top:1px solid #ff6b6b;font:12px/1.45 ui-monospace,monospace;white-space:pre-wrap;z-index:2147483647";
+      document.body.appendChild(banner);
+    }
+    banner.textContent = "Build failed\\n\\n" + message;
+  };
+  const source = new EventSource(${JSON.stringify(DEV_EVENTS_PATH)});
+  source.addEventListener("reload", () => location.reload());
+  source.addEventListener("build-error", (event) => showError(event.data));
+  source.addEventListener("connected", () => {
+    if (banner) banner.remove();
+    banner = null;
+  });
+})();
+</script>`;
+  if (/<\/body\s*>/i.test(html))
+    return html.replace(/<\/body\s*>/i, `${script}\n</body>`);
+  return `${html}${html.endsWith("\n") ? "" : "\n"}${script}`;
+}
+
+/**
+ * URLs to print for a listening dev server.
+ * @param {{host: string, port: number}} options
+ * @returns {{local: string[], network: string[]}}
+ */
+export function formatDevUrls({ host, port }) {
+  if (!isWildcardHost(host)) {
+    return {
+      local: [`http://${urlHost(host)}:${port}/`],
+      network: [],
+    };
+  }
+
+  const local = [`http://localhost:${port}/`];
+  const network = [];
+  for (const addresses of Object.values(os.networkInterfaces())) {
+    for (const address of addresses || []) {
+      if (address.internal || address.family !== "IPv4") continue;
+      network.push(`http://${address.address}:${port}/`);
+    }
+  }
+  return { local, network: [...new Set(network)] };
+}
+
+function normalizeHtml(result) {
+  if (typeof result === "string") return result;
+  if (Buffer.isBuffer(result) || result instanceof Uint8Array)
+    return Buffer.from(result).toString("utf8");
+  if (result && typeof result.html === "string") return result.html;
+  throw new Error("fx dev build callback must return HTML text");
+}
+
+function writeEvent(response, event, data) {
+  response.write(`event: ${event}\n`);
+  for (const line of String(data).split("\n"))
+    response.write(`data: ${line}\n`);
+  response.write("\n");
+}
+
+function errorPage(error) {
+  const message = error?.stack || error?.message || "Unknown build error";
+  return `<!doctype html>
+<html>
+<head><meta charset="utf-8"><title>Build failed</title></head>
+<body style="margin:0;padding:24px;background:#160d0d;color:#ffb4b4;font:14px/1.5 ui-monospace,monospace">
+<h1 style="font-size:18px">Build failed</h1>
+<pre style="white-space:pre-wrap">${escapeHtml(message)}</pre>
+</body>
+</html>`;
+}
+
+function loadingPage() {
+  return `<!doctype html>
+<html>
+<head><meta charset="utf-8"><title>Building…</title></head>
+<body style="margin:0;padding:24px;background:#0e0e12;color:#ddd;font:14px/1.5 ui-monospace,monospace">
+Building…
+</body>
+</html>`;
+}
+
+/**
+ * Start the dev server and watch a directory for changes.
+ *
+ * @param {object} options
+ * @param {string} options.watchDir Directory to watch recursively.
+ * @param {() => Promise<string|Buffer|{html: string}>} options.build Build callback.
+ * @param {string} [options.host="127.0.0.1"]
+ * @param {number} [options.port=3000] Port 0 asks the OS for a free port.
+ * @param {boolean} [options.strictPort=false]
+ * @param {number} [options.debounce=75]
+ * @param {object} [options.log] Logger with error/success/warn/info methods.
+ * @returns {Promise<object>}
+ */
+export async function startDevServer(options = {}) {
+  const watchDir = path.resolve(options.watchDir || process.cwd());
+  if (!fs.existsSync(watchDir))
+    throw new Error(`Watch directory does not exist: ${watchDir}`);
+  if (typeof options.build !== "function")
+    throw new Error("startDevServer requires a build callback");
+
+  const host =
+    options.host === true || options.host == null
+      ? "127.0.0.1"
+      : String(options.host);
+  const requestedPort = options.port == null ? 3000 : Number(options.port);
+  if (
+    !Number.isInteger(requestedPort) ||
+    requestedPort < 0 ||
+    requestedPort > 65535
+  )
+    throw new Error(`Invalid port: ${options.port}`);
+  const strictPort = Boolean(options.strictPort);
+  const debounce = options.debounce ?? 75;
+  const log = options.log || {};
+  const clients = new Set();
+
+  let currentHtml = null;
+  let currentError = null;
+  let previousHtml = null;
+  let hasBuilt = false;
+  let closed = false;
+  let building = false;
+  let queued = false;
+  let timer = null;
+  let watcher = null;
+
+  function broadcast(event, data) {
+    for (const client of clients) {
+      try {
+        writeEvent(client, event, data);
+      } catch {
+        clients.delete(client);
+      }
+    }
+  }
+
+  async function runBuild() {
+    if (closed) return;
+    if (building) {
+      queued = true;
+      return;
+    }
+    building = true;
+    const recovering = currentError != null;
+    try {
+      const html = normalizeHtml(await options.build());
+      const changed = html !== previousHtml;
+      previousHtml = html;
+      currentHtml = html;
+      if (currentError) currentError = null;
+      if (changed || recovering) {
+        broadcast("reload", String(Date.now()));
+        if (hasBuilt) log.success?.("Reloaded browser");
+        hasBuilt = true;
+      }
+    } catch (err) {
+      currentError = err instanceof Error ? err : new Error(String(err));
+      log.error?.(`Build failed: ${currentError.message}`);
+      broadcast("build-error", currentError.stack || currentError.message);
+    } finally {
+      building = false;
+      if (queued) {
+        queued = false;
+        schedule(0);
+      }
+    }
+  }
+
+  function schedule(delay = debounce) {
+    if (closed) return;
+    clearTimeout(timer);
+    timer = setTimeout(() => {
+      timer = null;
+      void runBuild();
+    }, delay);
+    timer.unref?.();
+  }
+
+  const server = http.createServer((request, response) => {
+    const url = new URL(request.url || "/", "http://localhost");
+
+    if (url.pathname === DEV_EVENTS_PATH) {
+      response.writeHead(200, {
+        "Content-Type": "text/event-stream; charset=utf-8",
+        "Cache-Control": "no-cache, no-transform",
+        Connection: "keep-alive",
+        "X-Accel-Buffering": "no",
+      });
+      response.write("retry: 500\n\n");
+      writeEvent(response, "connected", String(Date.now()));
+      clients.add(response);
+      response.on("close", () => clients.delete(response));
+      return;
+    }
+
+    if (url.pathname === DEV_STATUS_PATH) {
+      response.writeHead(200, {
+        "Content-Type": "application/json; charset=utf-8",
+        "Cache-Control": "no-store",
+      });
+      response.end(
+        `${JSON.stringify({
+          ok: !currentError,
+          error: currentError ? currentError.message : null,
+          html: currentHtml != null,
+        })}\n`,
+      );
+      return;
+    }
+
+    if (url.pathname !== "/" && url.pathname !== "/index.html") {
+      response.writeHead(404, { "Content-Type": "text/plain; charset=utf-8" });
+      response.end("Not found\n");
+      return;
+    }
+
+    const html =
+      currentHtml ?? (currentError ? errorPage(currentError) : loadingPage());
+    response.writeHead(200, {
+      "Content-Type": "text/html; charset=utf-8",
+      "Cache-Control": "no-store",
+    });
+    response.end(injectDevClient(html));
+  });
+
+  let port;
+  for (let attempt = 0; ; attempt += 1) {
+    try {
+      port = await new Promise((resolve, reject) => {
+        const onError = (error) => {
+          server.off("listening", onListening);
+          reject(error);
+        };
+        const onListening = () => {
+          server.off("error", onError);
+          resolve(server.address().port);
+        };
+        server.once("error", onError);
+        server.once("listening", onListening);
+        server.listen(requestedPort === 0 ? 0 : requestedPort + attempt, host);
+      });
+      break;
+    } catch (error) {
+      if (
+        error.code !== "EADDRINUSE" ||
+        strictPort ||
+        requestedPort === 0 ||
+        attempt >= 20
+      )
+        throw error;
+      log.warn?.(
+        `Port ${requestedPort + attempt} is in use, trying ${
+          requestedPort + attempt + 1
+        }…`,
+      );
+    }
+  }
+
+  try {
+    watcher = fs.watch(watchDir, { recursive: true }, (_event, filename) => {
+      if (!ignoredFile(filename)) schedule();
+    });
+  } catch (error) {
+    await new Promise((resolve) => server.close(resolve));
+    throw new Error(
+      `Could not watch ${watchDir}: ${error.message}. ` +
+        "Recursive file watching needs Node.js 22 or newer.",
+      { cause: error },
+    );
+  }
+
+  const keepAlive = setInterval(() => {
+    for (const client of clients) {
+      try {
+        client.write(": ping\n\n");
+      } catch {
+        clients.delete(client);
+      }
+    }
+  }, 25000);
+  keepAlive.unref();
+
+  const ready = runBuild();
+  const urls = formatDevUrls({ host, port });
+
+  return {
+    server,
+    host,
+    port,
+    url: urls.local[0],
+    localUrls: urls.local,
+    networkUrls: urls.network,
+    ready,
+    get html() {
+      return currentHtml;
+    },
+    get error() {
+      return currentError;
+    },
+    async close() {
+      if (closed) return;
+      closed = true;
+      clearTimeout(timer);
+      clearInterval(keepAlive);
+      watcher?.close();
+      for (const client of clients) {
+        try {
+          client.end();
+        } catch {
+          // already closed
+        }
+      }
+      clients.clear();
+      await new Promise((resolve) => server.close(resolve));
+      server.closeAllConnections?.();
+    },
+  };
+}

package/src/errors.js

@@ -0,0 +1,56 @@
+/**
+ * Shared error types and a small diagnostic formatter for Triflare Fx.
+ */
+
+export class FxError extends Error {
+  /**
+   * @param {string} message
+   * @param {{line?: number, column?: number, file?: string, source?: string}} [info]
+   */
+  constructor(message, info = {}) {
+    super(message);
+    this.name = "FxError";
+    this.line = info.line;
+    this.column = info.column;
+    this.file = info.file;
+    this.source = info.source;
+  }
+
+  /** Human readable, single/multi-line diagnostic with a source caret. */
+  format() {
+    const where = this.file ? `${this.file}` : "<input>";
+    const loc =
+      this.line != null ? `${where}:${this.line}:${this.column ?? 0}` : where;
+    const head = `${this.name}: ${this.message}\n  --> ${loc}`;
+    if (this.source && this.line != null) {
+      const lines = this.source.split(/\r?\n/);
+      const text = lines[this.line - 1];
+      if (text != null) {
+        const caret = " ".repeat(Math.max(0, (this.column ?? 1) - 1)) + "^";
+        return `${head}\n${this.line} | ${text}\n${" ".repeat(String(this.line).length)} | ${caret}`;
+      }
+    }
+    return head;
+  }
+}
+
+export class LexError extends FxError {
+  constructor(message, info) {
+    super(message, info);
+    this.name = "LexError";
+  }
+}
+
+export class ParseError extends FxError {
+  constructor(message, info) {
+    super(message, info);
+    this.name = "ParseError";
+  }
+}
+
+export class CompileError extends FxError {
+  constructor(message, info) {
+    super(message, info);
+    this.name = "CompileError";
+  }
+}