@goldenlustre/agent-studio 1.0.1

package/bin/agent-studio-options.js

@@ -0,0 +1,89 @@
+"use strict";
+
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const { parseArgs } = require("util");
+
+const TRUE_VALUES = new Set(["1", "true", "yes", "on"]);
+
+const CLI_OPTIONS = {
+  port: { type: "string", short: "p" },
+  hostname: { type: "string", short: "H" },
+  "no-open": { type: "boolean" },
+  help: { type: "boolean", short: "h" },
+};
+
+function isEnabled(value) {
+  return typeof value === "string" && TRUE_VALUES.has(value.trim().toLowerCase());
+}
+
+function normalizePort(value) {
+  if (typeof value !== "string" || !/^\d+$/.test(value)) {
+    throw new Error("Port must be a non-negative integer.");
+  }
+
+  const port = Number(value);
+  if (!Number.isSafeInteger(port) || port > 65535) {
+    throw new Error("Port must be between 0 and 65535.");
+  }
+
+  return String(port);
+}
+
+function getHelpText() {
+  return `Usage: agent-studio [options]
+
+Start the AgentStudio UI server.
+
+Options:
+  -p, --port <port>          Server port (default: 30141, or PORT)
+  -H, --hostname <host>      Bind hostname (default: 127.0.0.1, or PI_WEB_HOSTNAME)
+      --no-open              Do not open a browser automatically
+  -h, --help                 Show this help message and exit
+
+Environment:
+  PORT                       Default port when --port is omitted
+  PI_WEB_HOSTNAME            Default hostname when --hostname is omitted
+  PI_WEB_NO_OPEN             Set to 1/true/yes/on to disable browser open
+  PI_WEB_PASSWORD            Enable browser password login and API Basic Auth
+  PI_WEB_ALLOWED_HOSTS       Extra exact proxy/custom hostnames, comma-separated
+  PI_WEB_SKIP_VERSION_CHECK  Set to 1 to disable update checks
+  PI_WEB_IDLE_TIMEOUT_MS     Session idle timeout in ms (0 disables; default 600000)
+`;
+}
+
+function parseLaunchOptions(args = process.argv.slice(2), env = process.env) {
+  let values;
+  let positionals;
+  try {
+    ({ values, positionals } = parseArgs({
+      args,
+      options: CLI_OPTIONS,
+      strict: true,
+      allowPositionals: true,
+    }));
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const err = new Error(`${message}\nUse --help to see available options.`);
+    err.code = "ERR_PARSE_ARGS_UNKNOWN_OPTION";
+    throw err;
+  }
+
+  if (values.help) {
+    return { help: true };
+  }
+
+  if (positionals.length > 0) {
+    throw new Error(
+      `Unexpected argument(s): ${positionals.join(" ")}\nUse --help to see available options.`,
+    );
+  }
+
+  return {
+    help: false,
+    port: normalizePort(values.port ?? env.PORT ?? "30141"),
+    hostname: values.hostname ?? env.PI_WEB_HOSTNAME ?? "127.0.0.1",
+    openBrowser: !values["no-open"] && !isEnabled(env.PI_WEB_NO_OPEN),
+  };
+}
+
+module.exports = { parseLaunchOptions, getHelpText };

package/bin/agent-studio.js

@@ -0,0 +1,132 @@
+#!/usr/bin/env node
+"use strict";
+
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const { getUnsupportedNodeVersionMessage, isNodeVersionSupported } = require("./node-version");
+
+if (!isNodeVersionSupported(process.versions.node)) {
+  console.error(getUnsupportedNodeVersionMessage(process.versions.node));
+  process.exit(1);
+}
+
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const { spawn } = require("child_process");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const path = require("path");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const fs = require("fs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const { getHelpText, parseLaunchOptions } = require("./agent-studio-options");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const { wireChildProcessLifecycle } = require("./process-lifecycle");
+
+let launchOptions;
+try {
+  launchOptions = parseLaunchOptions();
+} catch (error) {
+  fs.writeSync(
+    process.stderr.fd,
+    `${error instanceof Error ? error.message : String(error)}\n`,
+  );
+  process.exit(1);
+}
+
+if (launchOptions.help) {
+  fs.writeSync(process.stdout.fd, getHelpText());
+  process.exit(0);
+}
+
+const { port, hostname, openBrowser } = launchOptions;
+
+const pkgDir = path.join(__dirname, "..");
+const nextDir = path.join(pkgDir, ".next");
+
+// Resolve next's CLI entry directly to avoid relying on .bin symlinks (which
+// may not exist when installed via npx).
+let nextBin;
+try {
+  nextBin = require.resolve("next/dist/bin/next", { paths: [pkgDir] });
+} catch {
+  // Fallback: locate next package root and derive the bin path manually.
+  try {
+    const nextPkg = require.resolve("next/package.json", { paths: [pkgDir] });
+    nextBin = path.join(path.dirname(nextPkg), "dist", "bin", "next");
+  } catch {
+    nextBin = path.join(pkgDir, "node_modules", "next", "dist", "bin", "next");
+  }
+}
+
+const loopbackHostnames = new Set(["127.0.0.1", "localhost", "::1", "[::1]"]);
+const passwordEnabled = Boolean(process.env.PI_WEB_PASSWORD);
+
+if (!fs.existsSync(nextDir)) {
+  console.error("Build artifacts not found. Please report this issue.");
+  process.exit(1);
+}
+
+if (!loopbackHostnames.has(hostname)) {
+  if (passwordEnabled) {
+    console.warn(
+      `Warning: AgentStudio is listening on ${hostname} with password authentication over HTTP. Use HTTPS or a trusted VPN to protect the password in transit.`,
+    );
+  } else {
+    console.warn(
+      `Warning: AgentStudio is listening on ${hostname} without authentication. Only use this on a trusted network.`,
+    );
+  }
+}
+
+const nextArgs = ["start", "-p", port];
+nextArgs.push("-H", hostname);
+
+// Always run next's JS entry with node directly — avoids .bin symlink issues
+// and path-with-spaces problems on Windows when shell: true is used.
+const child = spawn(process.execPath, [nextBin, ...nextArgs], {
+  cwd: pkgDir,
+  stdio: ["inherit", "pipe", "inherit"],
+  env: { ...process.env, PI_WEB_HOSTNAME: hostname },
+});
+wireChildProcessLifecycle(child);
+
+let browserOpened = false;
+const url = `http://${hostname}:${port}`;
+
+child.stdout.on("data", (chunk) => {
+  const text = chunk.toString();
+  process.stdout.write(text);
+  if (openBrowser && !browserOpened && text.includes("Ready")) {
+    browserOpened = true;
+    const isWindows = process.platform === "win32";
+    const isMac = process.platform === "darwin";
+    // Avoid `shell: true` to suppress Node.js DEP0190 deprecation
+    // ("Passing args to a child process with shell option true can lead to
+    // security vulnerabilities, as the arguments are not escaped").
+    // Pass a structured argv so Node.js handles escaping instead of
+    // concatenating the args into a shell command string.
+    let opener;
+    if (isWindows) {
+      // `start` is a cmd.exe built-in, so invoke cmd directly. The empty
+      // title argument is required by `start` before the target URL.
+      opener = spawn(process.env.ComSpec || "cmd.exe", ["/c", "start", "", url], {
+        stdio: "ignore",
+        detached: true,
+      });
+    } else if (isMac) {
+      opener = spawn("open", [url], {
+        stdio: "ignore",
+        detached: true,
+      });
+    } else {
+      opener = spawn("xdg-open", [url], {
+        stdio: "ignore",
+        detached: true,
+      });
+    }
+
+    opener.on("error", (error) => {
+      console.warn(`Could not open browser automatically: ${error.message}`);
+    });
+
+    opener.unref();
+  }
+});

package/bin/node-version.js

@@ -0,0 +1,35 @@
+"use strict";
+
+const MIN_NODE_VERSION = "22.19.0";
+
+function parseNodeVersion(version) {
+  const match = /^v?(\d+)\.(\d+)\.(\d+)/.exec(version);
+  if (!match) return null;
+  return match.slice(1).map(Number);
+}
+
+function isNodeVersionSupported(version) {
+  const current = parseNodeVersion(version);
+  const minimum = parseNodeVersion(MIN_NODE_VERSION);
+  if (!current || !minimum) return false;
+
+  for (let index = 0; index < minimum.length; index += 1) {
+    if (current[index] > minimum[index]) return true;
+    if (current[index] < minimum[index]) return false;
+  }
+  return true;
+}
+
+function getUnsupportedNodeVersionMessage(version) {
+  return [
+    `AgentStudio requires Node.js ${MIN_NODE_VERSION} or newer.`,
+    `Current Node.js version: ${version}.`,
+    "Upgrade Node.js and try again: https://nodejs.org/",
+  ].join("\n");
+}
+
+module.exports = {
+  MIN_NODE_VERSION,
+  getUnsupportedNodeVersionMessage,
+  isNodeVersionSupported,
+};

package/bin/pi-web-options.js

@@ -0,0 +1,89 @@
+"use strict";
+
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const { parseArgs } = require("util");
+
+const TRUE_VALUES = new Set(["1", "true", "yes", "on"]);
+
+const CLI_OPTIONS = {
+  port: { type: "string", short: "p" },
+  hostname: { type: "string", short: "H" },
+  "no-open": { type: "boolean" },
+  help: { type: "boolean", short: "h" },
+};
+
+function isEnabled(value) {
+  return typeof value === "string" && TRUE_VALUES.has(value.trim().toLowerCase());
+}
+
+function normalizePort(value) {
+  if (typeof value !== "string" || !/^\d+$/.test(value)) {
+    throw new Error("Port must be a non-negative integer.");
+  }
+
+  const port = Number(value);
+  if (!Number.isSafeInteger(port) || port > 65535) {
+    throw new Error("Port must be between 0 and 65535.");
+  }
+
+  return String(port);
+}
+
+function getHelpText() {
+  return `Usage: pi-web [options]
+
+Start the Pi Web UI server.
+
+Options:
+  -p, --port <port>          Server port (default: 30141, or PORT)
+  -H, --hostname <host>      Bind hostname (default: 127.0.0.1, or PI_WEB_HOSTNAME)
+      --no-open              Do not open a browser automatically
+  -h, --help                 Show this help message and exit
+
+Environment:
+  PORT                       Default port when --port is omitted
+  PI_WEB_HOSTNAME            Default hostname when --hostname is omitted
+  PI_WEB_NO_OPEN             Set to 1/true/yes/on to disable browser open
+  PI_WEB_PASSWORD            Enable browser password login and API Basic Auth
+  PI_WEB_ALLOWED_HOSTS       Extra exact proxy/custom hostnames, comma-separated
+  PI_WEB_SKIP_VERSION_CHECK  Set to 1 to disable Pi Web update checks
+  PI_WEB_IDLE_TIMEOUT_MS     Session idle timeout in ms (0 disables; default 600000)
+`;
+}
+
+function parseLaunchOptions(args = process.argv.slice(2), env = process.env) {
+  let values;
+  let positionals;
+  try {
+    ({ values, positionals } = parseArgs({
+      args,
+      options: CLI_OPTIONS,
+      strict: true,
+      allowPositionals: true,
+    }));
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const err = new Error(`${message}\nUse --help to see available options.`);
+    err.code = "ERR_PARSE_ARGS_UNKNOWN_OPTION";
+    throw err;
+  }
+
+  if (values.help) {
+    return { help: true };
+  }
+
+  if (positionals.length > 0) {
+    throw new Error(
+      `Unexpected argument(s): ${positionals.join(" ")}\nUse --help to see available options.`,
+    );
+  }
+
+  return {
+    help: false,
+    port: normalizePort(values.port ?? env.PORT ?? "30141"),
+    hostname: values.hostname ?? env.PI_WEB_HOSTNAME ?? "127.0.0.1",
+    openBrowser: !values["no-open"] && !isEnabled(env.PI_WEB_NO_OPEN),
+  };
+}
+
+module.exports = { parseLaunchOptions, getHelpText };

package/bin/pi-web.js

@@ -0,0 +1,132 @@
+#!/usr/bin/env node
+"use strict";
+
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const { getUnsupportedNodeVersionMessage, isNodeVersionSupported } = require("./node-version");
+
+if (!isNodeVersionSupported(process.versions.node)) {
+  console.error(getUnsupportedNodeVersionMessage(process.versions.node));
+  process.exit(1);
+}
+
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const { spawn } = require("child_process");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const path = require("path");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const fs = require("fs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const { getHelpText, parseLaunchOptions } = require("./pi-web-options");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const { wireChildProcessLifecycle } = require("./process-lifecycle");
+
+let launchOptions;
+try {
+  launchOptions = parseLaunchOptions();
+} catch (error) {
+  fs.writeSync(
+    process.stderr.fd,
+    `${error instanceof Error ? error.message : String(error)}\n`,
+  );
+  process.exit(1);
+}
+
+if (launchOptions.help) {
+  fs.writeSync(process.stdout.fd, getHelpText());
+  process.exit(0);
+}
+
+const { port, hostname, openBrowser } = launchOptions;
+
+const pkgDir = path.join(__dirname, "..");
+const nextDir = path.join(pkgDir, ".next");
+
+// Resolve next's CLI entry directly to avoid relying on .bin symlinks (which
+// may not exist when installed via npx).
+let nextBin;
+try {
+  nextBin = require.resolve("next/dist/bin/next", { paths: [pkgDir] });
+} catch {
+  // Fallback: locate next package root and derive the bin path manually.
+  try {
+    const nextPkg = require.resolve("next/package.json", { paths: [pkgDir] });
+    nextBin = path.join(path.dirname(nextPkg), "dist", "bin", "next");
+  } catch {
+    nextBin = path.join(pkgDir, "node_modules", "next", "dist", "bin", "next");
+  }
+}
+
+const loopbackHostnames = new Set(["127.0.0.1", "localhost", "::1", "[::1]"]);
+const passwordEnabled = Boolean(process.env.PI_WEB_PASSWORD);
+
+if (!fs.existsSync(nextDir)) {
+  console.error("Build artifacts not found. Please report this issue.");
+  process.exit(1);
+}
+
+if (!loopbackHostnames.has(hostname)) {
+  if (passwordEnabled) {
+    console.warn(
+      `Warning: pi-web is listening on ${hostname} with password authentication over HTTP. Use HTTPS or a trusted VPN to protect the password in transit.`,
+    );
+  } else {
+    console.warn(
+      `Warning: pi-web is listening on ${hostname} without authentication. Only use this on a trusted network.`,
+    );
+  }
+}
+
+const nextArgs = ["start", "-p", port];
+nextArgs.push("-H", hostname);
+
+// Always run next's JS entry with node directly — avoids .bin symlink issues
+// and path-with-spaces problems on Windows when shell: true is used.
+const child = spawn(process.execPath, [nextBin, ...nextArgs], {
+  cwd: pkgDir,
+  stdio: ["inherit", "pipe", "inherit"],
+  env: { ...process.env, PI_WEB_HOSTNAME: hostname },
+});
+wireChildProcessLifecycle(child);
+
+let browserOpened = false;
+const url = `http://${hostname}:${port}`;
+
+child.stdout.on("data", (chunk) => {
+  const text = chunk.toString();
+  process.stdout.write(text);
+  if (openBrowser && !browserOpened && text.includes("Ready")) {
+    browserOpened = true;
+    const isWindows = process.platform === "win32";
+    const isMac = process.platform === "darwin";
+    // Avoid `shell: true` to suppress Node.js DEP0190 deprecation
+    // ("Passing args to a child process with shell option true can lead to
+    // security vulnerabilities, as the arguments are not escaped").
+    // Pass a structured argv so Node.js handles escaping instead of
+    // concatenating the args into a shell command string.
+    let opener;
+    if (isWindows) {
+      // `start` is a cmd.exe built-in, so invoke cmd directly. The empty
+      // title argument is required by `start` before the target URL.
+      opener = spawn(process.env.ComSpec || "cmd.exe", ["/c", "start", "", url], {
+        stdio: "ignore",
+        detached: true,
+      });
+    } else if (isMac) {
+      opener = spawn("open", [url], {
+        stdio: "ignore",
+        detached: true,
+      });
+    } else {
+      opener = spawn("xdg-open", [url], {
+        stdio: "ignore",
+        detached: true,
+      });
+    }
+
+    opener.on("error", (error) => {
+      console.warn(`Could not open browser automatically: ${error.message}`);
+    });
+
+    opener.unref();
+  }
+});

package/bin/prepare-terminal.js

@@ -0,0 +1,14 @@
+// node-pty 1.1.0 ships macOS spawn-helper binaries without executable bits.
+// Remove this workaround once the upstream package preserves those modes.
+/* eslint-disable @typescript-eslint/no-require-imports */
+const { chmodSync, statSync } = require("node:fs");
+const { dirname, join } = require("node:path");
+
+if (process.platform === "darwin") {
+  const root = dirname(require.resolve("node-pty/package.json"));
+  for (const directory of ["build/Release", "build/Debug", `prebuilds/darwin-${process.arch}`]) {
+    const helper = join(root, directory, "spawn-helper");
+    const stat = statSync(helper, { throwIfNoEntry: false });
+    if (stat?.isFile() && (stat.mode & 0o111) !== 0o111) chmodSync(helper, stat.mode | 0o111);
+  }
+}

package/bin/process-lifecycle.js

@@ -0,0 +1,81 @@
+"use strict";
+
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const os = require("node:os");
+
+const forwardedSignals = ["SIGINT", "SIGTERM"];
+const shutdownTimeoutMs = 5_000;
+
+function getSignalExitCode(signal) {
+  const signalNumber = signal ? os.constants.signals[signal] : undefined;
+  return typeof signalNumber === "number" ? 128 + signalNumber : 1;
+}
+
+function wireChildProcessLifecycle(
+  child,
+  parentProcess = process,
+  timeoutMs = shutdownTimeoutMs,
+  log = console.error,
+) {
+  const signalHandlers = new Map();
+  let shutdownTimer;
+  // Set once we forward a signal, so an exit we asked for stays quiet and one
+  // we did not gets reported.
+  let shuttingDown = false;
+
+  const forceKill = () => child.kill("SIGKILL");
+
+  function unwire() {
+    if (shutdownTimer) clearTimeout(shutdownTimer);
+    for (const [forwardedSignal, handler] of signalHandlers) {
+      parentProcess.removeListener(forwardedSignal, handler);
+    }
+    child.removeListener("error", handleError);
+  }
+
+  function handleError(error) {
+    const failedToSpawn = child.pid === undefined;
+    log(
+      `[pi-web] ${failedToSpawn ? "could not run the Next.js process" : "Next.js process error"}: ${error.message}`,
+    );
+
+    if (failedToSpawn) {
+      unwire();
+      parentProcess.exit(1);
+    }
+  }
+
+  for (const signal of forwardedSignals) {
+    const handler = () => {
+      if (shutdownTimer) {
+        forceKill();
+        return;
+      }
+
+      shuttingDown = true;
+      shutdownTimer = setTimeout(forceKill, timeoutMs);
+      shutdownTimer.unref();
+      child.kill(signal);
+    };
+    signalHandlers.set(signal, handler);
+    parentProcess.on(signal, handler);
+  }
+
+  child.on("error", handleError);
+
+  child.once("exit", (code, signal) => {
+    unwire();
+
+    // A shutdown the user asked for needs no explanation; anything else left
+    // the window closing with no stated reason.
+    if (!shuttingDown) {
+      log(
+        `[pi-web] Next.js exited unexpectedly (${signal ? `signal ${signal}` : `code ${code}`})`,
+      );
+    }
+
+    parentProcess.exit(code ?? getSignalExitCode(signal));
+  });
+}
+
+module.exports = { wireChildProcessLifecycle };

package/next.config.ts

@@ -0,0 +1,79 @@
+import type { NextConfig } from "next";
+import { readFileSync } from "fs";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+
+const configDir = dirname(fileURLToPath(import.meta.url));
+const { version } = JSON.parse(readFileSync(join(configDir, "package.json"), "utf8")) as { version: string };
+let piVersion = "unknown";
+try {
+  const piPkgPath = join(configDir, "node_modules/@earendil-works/pi-coding-agent/package.json");
+  piVersion = (JSON.parse(readFileSync(piPkgPath, "utf8")) as { version: string }).version;
+} catch { /* package not found, use default */ }
+
+const nextConfig: NextConfig = {
+  outputFileTracingRoot: configDir,
+  serverExternalPackages: [
+    "node-pty",
+    "undici",
+    "web-push",
+    "@earendil-works/pi-coding-agent",
+    "@earendil-works/pi-agent-core",
+    "@earendil-works/pi-ai",
+    "@earendil-works/pi-tui",
+  ],
+  // Next 16 blocks cross-origin access to dev resources by default. Allow the
+  // loopback and the RFC1918 LAN ranges so the dev server stays reachable
+  // from other machines on the same LAN.
+  allowedDevOrigins: [
+    "127.0.0.1",
+    "10.*.*.*",
+    // 172.16.0.0/12
+    "172.16.*.*",
+    "172.17.*.*",
+    "172.18.*.*",
+    "172.19.*.*",
+    "172.20.*.*",
+    "172.21.*.*",
+    "172.22.*.*",
+    "172.23.*.*",
+    "172.24.*.*",
+    "172.25.*.*",
+    "172.26.*.*",
+    "172.27.*.*",
+    "172.28.*.*",
+    "172.29.*.*",
+    "172.30.*.*",
+    "172.31.*.*",
+    "192.168.*.*",
+  ],
+  async headers() {
+    return [
+      {
+        source: "/",
+        headers: [
+          { key: "Cache-Control", value: "private, no-cache, max-age=0, must-revalidate" },
+        ],
+      },
+      {
+        source: "/sw.js",
+        headers: [
+          { key: "Cache-Control", value: "public, max-age=0, must-revalidate" },
+          { key: "Service-Worker-Allowed", value: "/" },
+        ],
+      },
+      {
+        source: "/manifest.webmanifest",
+        headers: [
+          { key: "Cache-Control", value: "public, max-age=0, must-revalidate" },
+        ],
+      },
+    ];
+  },
+  env: {
+    NEXT_PUBLIC_APP_VERSION: version,
+    NEXT_PUBLIC_PI_VERSION: piVersion,
+  },
+};
+
+export default nextConfig;