cartethyia 2.5.9 → 2.6.0

package/scripts/cli/background.ts

@@ -1,110 +1,120 @@
-import { spawn } from "node:child_process";
-import { readFileSync, unlinkSync } from "node:fs";
-import { PACKAGE_ROOT, resolvePackagePath } from "../../src/config/package-paths";
-
-/** Opens a URL in the operator's default browser, ignoring a missing handler. */
-export function openUrl(url: string): Promise<void> {
-  const command = process.platform === "win32"
-    ? "explorer.exe"
-    : process.platform === "darwin"
-      ? "open"
-      : "xdg-open";
-  const child = Bun.spawn([command, url], {
-    stdin: "ignore",
-    stdout: "ignore",
-    stderr: "ignore",
-  });
-  return child.exited.then(() => undefined);
-}
-
-/**
- * Starts a detached process and resolves once it reports readiness.
- *
- * The child owns no stdio, so a signal file is the only channel that survives
- * the parent. Without it the caller prints "running in the background" for a
- * child that may already have died — which is exactly what a port clash looks
- * like, because the child's own startup probe fails while the parent's gateway
- * still holds the port.
- *
- * Resolves with the URL the child reported. Rejects with the child's message
- * when it reports failure, or with a timeout if it never reports at all.
- */
-export function launchBackgroundWithStatus(
-  args: readonly string[],
-  options: { readonly signalPath: string; readonly timeoutMs?: number } = { signalPath: "" },
-): Promise<string> {
-  return new Promise<string>((resolve, reject) => {
-    const signalPath = options.signalPath;
-    const deadline = Date.now() + (options.timeoutMs ?? 60_000);
-    let settled = false;
-    const finish = (error: Error | null, url?: string): void => {
-      if (settled) return;
-      settled = true;
-      clearInterval(timer);
-      try {
-        unlinkSync(signalPath);
-      } catch {}
-      if (error) reject(error);
-      else resolve(url ?? "");
-    };
-
-    const env = { ...process.env, CARTETHYIA_TRAY_STARTUP_SIGNAL: signalPath };
-    spawnBackground(args, env);
-
-    const timer = setInterval(() => {
-      if (settled) return;
-      let raw: string;
-      try {
-        raw = readFileSync(signalPath, "utf8");
-      } catch {
-        if (Date.now() >= deadline) finish(new Error("the background process did not report startup within the deadline"));
-        return;
-      }
-      try {
-        const signal = JSON.parse(raw) as { status?: string; url?: string; message?: string };
-        if (signal.status === "ready" && typeof signal.url === "string") finish(null, signal.url);
-        else if (signal.status === "failed") finish(new Error(signal.message ?? "the background process failed to start"));
-      } catch {
-        // A partially written file is read again on the next tick.
-      }
-    }, 150);
-    timer.unref?.();
-  });
-}
-
-/**
- * Starts a Bun process that owns no console window.
- *
- * On Windows, spawning the child directly is not enough: a console-subsystem
- * child of a window-less parent allocates a new console, and when the parent is
- * inside Windows Terminal the tab is already on screen before any flag can take
- * effect — measured: `detached: true` plus `windowsHide: true` still produced a
- * Windows Terminal window titled with the bun path. `wscript.exe` is a
- * GUI-subsystem host, so it never allocates a console, and a child launched
- * from it with window style 0 inherits that. The VBS is that launcher.
- *
- * Elsewhere `detached` is enough and the helper is not used.
- */
-export function launchBackground(args: readonly string[]): void {
-  spawnBackground(args, process.env);
-}
-
-function spawnBackground(args: readonly string[], env: NodeJS.ProcessEnv): void {
-  if (process.platform !== "win32") {
-    const child = spawn(process.execPath, [...args], {
-      cwd: PACKAGE_ROOT,
-      detached: true,
-      stdio: "ignore",
-      env,
-    });
-    child.unref();
-    return;
-  }
-  const launcher = resolvePackagePath("scripts", "cli", "tray", "hidden-window.vbs");
-  const child = spawn(
-    "wscript.exe",
-    ["//nologo", launcher, process.execPath, ...args],
-    { cwd: PACKAGE_ROOT, detached: true, stdio: "ignore", windowsHide: true, env },
-  );
-  child.unref();
-}
+import { spawn } from "node:child_process";
+import { readFileSync, unlinkSync } from "node:fs";
+import { PACKAGE_ROOT, resolvePackagePath } from "../../src/config/package-paths";
+
+/** Opens a URL in the operator's default browser, ignoring a missing handler. */
+export function openUrl(url: string): Promise<void> {
+  const command = process.platform === "win32"
+    ? "explorer.exe"
+    : process.platform === "darwin"
+      ? "open"
+      : "xdg-open";
+  const child = Bun.spawn([command, url], {
+    stdin: "ignore",
+    stdout: "ignore",
+    stderr: "ignore",
+  });
+  return child.exited.then(() => undefined);
+}
+
+/**
+ * Starts a detached process and resolves once it reports readiness.
+ *
+ * The child owns no stdio, so a signal file is the only channel that survives
+ * the parent. Without it the caller prints "running in the background" for a
+ * child that may already have died — which is exactly what a port clash looks
+ * like, because the child's own startup probe fails while the parent's gateway
+ * still holds the port.
+ *
+ * Resolves with the URL the child reported. Rejects with the child's message
+ * when it reports failure, or with a timeout if it never reports at all.
+ */
+export function launchBackgroundWithStatus(
+  args: readonly string[],
+  options: {
+    readonly signalPath: string;
+    readonly timeoutMs?: number;
+    readonly controllerHandoff?: { readonly token: string; readonly parentPid: number };
+  } = { signalPath: "" },
+): Promise<string> {
+  return new Promise<string>((resolve, reject) => {
+    const signalPath = options.signalPath;
+    const deadline = Date.now() + (options.timeoutMs ?? 60_000);
+    let settled = false;
+    const finish = (error: Error | null, url?: string): void => {
+      if (settled) return;
+      settled = true;
+      clearInterval(timer);
+      try {
+        unlinkSync(signalPath);
+      } catch {}
+      if (error) reject(error);
+      else resolve(url ?? "");
+    };
+
+    const env = {
+      ...process.env,
+      CARTETHYIA_TRAY_STARTUP_SIGNAL: signalPath,
+      ...(options.controllerHandoff ? {
+        CARTETHYIA_CONTROLLER_TOKEN: options.controllerHandoff.token,
+        CARTETHYIA_CONTROLLER_PARENT_PID: String(options.controllerHandoff.parentPid),
+      } : {}),
+    };
+    spawnBackground(args, env);
+
+    const timer = setInterval(() => {
+      if (settled) return;
+      let raw: string;
+      try {
+        raw = readFileSync(signalPath, "utf8");
+      } catch {
+        if (Date.now() >= deadline) finish(new Error("the background process did not report startup within the deadline"));
+        return;
+      }
+      try {
+        const signal = JSON.parse(raw) as { status?: string; url?: string; message?: string };
+        if (signal.status === "ready" && typeof signal.url === "string") finish(null, signal.url);
+        else if (signal.status === "failed") finish(new Error(signal.message ?? "the background process failed to start"));
+      } catch {
+        // A partially written file is read again on the next tick.
+      }
+    }, 150);
+  });
+}
+
+/**
+ * Starts a Bun process that owns no console window.
+ *
+ * On Windows, spawning the child directly is not enough: a console-subsystem
+ * child of a window-less parent allocates a new console, and when the parent is
+ * inside Windows Terminal the tab is already on screen before any flag can take
+ * effect — measured: `detached: true` plus `windowsHide: true` still produced a
+ * Windows Terminal window titled with the bun path. `wscript.exe` is a
+ * GUI-subsystem host, so it never allocates a console, and a child launched
+ * from it with window style 0 inherits that. The VBS is that launcher.
+ *
+ * Elsewhere `detached` is enough and the helper is not used.
+ */
+export function launchBackground(args: readonly string[]): void {
+  spawnBackground(args, process.env);
+}
+
+function spawnBackground(args: readonly string[], env: NodeJS.ProcessEnv): void {
+  if (process.platform !== "win32") {
+    const child = spawn(process.execPath, [...args], {
+      cwd: PACKAGE_ROOT,
+      detached: true,
+      stdio: "ignore",
+      env,
+    });
+    child.unref();
+    return;
+  }
+  const launcher = resolvePackagePath("scripts", "cli", "tray", "hidden-window.vbs");
+  const child = spawn(
+    "wscript.exe",
+    ["//nologo", launcher, process.execPath, ...args],
+    { cwd: PACKAGE_ROOT, detached: true, stdio: "ignore", windowsHide: true, env },
+  );
+  child.unref();
+}

package/scripts/cli/bin/carte.cjs

@@ -1,8 +1,8 @@
-#!/usr/bin/env node
-
-// Default to the arrow-key menu so `carte` works without a GUI; on Windows
-// especially, the tray icon can land in the hidden-icons overflow and never
-// be seen. `carte --tray` still opts into the system-tray icon.
-if (process.argv.length <= 2) process.argv.push("menu");
-else if (process.argv[2] === "--tray") process.argv[2] = "tray";
-require("./cartethyia.cjs");
+#!/usr/bin/env node
+
+// Default to the arrow-key menu so `carte` works without a GUI; on Windows
+// especially, the tray icon can land in the hidden-icons overflow and never
+// be seen. `carte --tray` still opts into the system-tray icon.
+if (process.argv.length <= 2) process.argv.push("menu");
+else if (process.argv[2] === "--tray") process.argv[2] = "tray";
+require("./cartethyia.cjs");

package/scripts/cli/bin/cartethyia.cjs

@@ -1,167 +1,167 @@
-#!/usr/bin/env node
-"use strict";
-
-const fs = require("node:fs");
-const { randomUUID } = require("node:crypto");
-const os = require("node:os");
-const path = require("node:path");
-const { spawn } = require("node:child_process");
-
-const packageRoot = path.resolve(__dirname, "..", "..", "..");
-const cliPath = path.join(packageRoot, "scripts", "cli", "main.ts");
-const configDir = process.env.CARTETHYIA_CONFIG_DIR || (
-  process.platform === "win32"
-    ? path.join(process.env.APPDATA || os.homedir(), "Cartethyia")
-    : process.platform === "darwin"
-      ? path.join(os.homedir(), "Library", "Application Support", "Cartethyia")
-      : path.join(process.env.XDG_CONFIG_HOME || path.join(os.homedir(), ".config"), "Cartethyia")
-);
-const trayMode = process.argv[2] === "tray";
-// The launcher itself runs under Node, so `process.execPath` is node.exe — not
-// the Bun the child needs. Resolve bun from PATH instead; WScript.Shell does
-// not inherit this process's environment, so the child needs an absolute path.
-function resolveBunPath() {
-  if (process.env.CARTETHYIA_BUN) return process.env.CARTETHYIA_BUN;
-  const name = process.platform === "win32" ? "bun.exe" : "bun";
-  for (const dir of (process.env.PATH || "").split(path.delimiter)) {
-    if (!dir) continue;
-    const candidate = path.join(dir, name);
-    try {
-      if (fs.statSync(candidate).isFile()) return candidate;
-    } catch {}
-  }
-  return name;
-}
-
-const startupSignalPath = trayMode
-  ? path.join(os.tmpdir(), `cartethyia-tray-${process.pid}-${randomUUID()}.json`)
-  : null;
-let spawnError;
-// On Windows the tray must start with no console at all, and neither
-// `detached: true` nor `windowsHide: true` achieves that: a console-subsystem
-// child of a window-less parent still allocates a console, and inside Windows
-// Terminal the tab is already on screen before a flag can take effect
-// (measured). `wscript.exe` is GUI-subsystem, so it never allocates one, and a
-// child launched from it with window style 0 inherits that. Elsewhere
-// `detached: true` is enough.
-const useWindowsDetach = process.platform === "win32" && trayMode;
-const hiddenLauncher = path.join(packageRoot, "scripts", "cli", "tray", "hidden-window.vbs");
-const child = useWindowsDetach
-  ? spawn(
-      "wscript.exe",
-      // Absolute path, not "bun": the VBS runs through WScript.Shell, which
-      // does not inherit this process's PATH additions and resolves a bare
-      // name against the system PATH only.
-      ["//nologo", hiddenLauncher, resolveBunPath(), "run", cliPath, ...process.argv.slice(2)],
-      {
-        cwd: packageRoot,
-        detached: true,
-        stdio: "ignore",
-        windowsHide: true,
-        env: {
-          ...process.env,
-          CARTETHYIA_CONFIG_DIR: configDir,
-          CARTETHYIA_TRAY_STARTUP_SIGNAL: startupSignalPath,
-        },
-      },
-    )
-  : spawn(resolveBunPath(), ["run", cliPath, ...process.argv.slice(2)], {
-      cwd: packageRoot,
-      detached: trayMode,
-      stdio: trayMode ? "ignore" : "inherit",
-      windowsHide: trayMode,
-      env: {
-        ...process.env,
-        CARTETHYIA_CONFIG_DIR: configDir,
-        ...(trayMode ? { CARTETHYIA_TRAY_STARTUP_SIGNAL: startupSignalPath } : {}),
-      },
-    });
-
-child.once("error", (error) => {
-  spawnError = error;
-  if (error.code === "ENOENT") {
-    console.error("Cartethyia requires Bun 1.4.0 or newer. Install Bun from https://bun.sh, then run this command again.");
-  } else {
-    console.error(`Could not start Cartethyia's Bun runtime: ${error.message}`);
-  }
-  process.exitCode = 1;
-});
-
-if (trayMode) {
-  child.unref();
-  console.log("Loading Cartethyia…");
-  let settled = false;
-  const deadline = Date.now() + 60_000;
-  const finish = (error, url) => {
-    if (settled) return;
-    settled = true;
-    try {
-      fs.unlinkSync(startupSignalPath);
-    } catch {}
-    if (error) {
-      // `error.message` can be an empty string when the failure came from a
-      // signal rather than a thrown message, which printed as a bare
-      // "Cartethyia failed to start:" with no cause. Fall back to the code and
-      // name what usually causes it.
-      const detail =
-        error.message && error.message.trim() !== ""
-          ? error.message
-          : `the process exited without a message (code ${child.exitCode ?? "unknown"})`;
-      console.error(`Cartethyia failed to start: ${detail}`);
-      console.error(
-        "If another Cartethyia is already running on this port, stop the terminal that started it first.",
-      );
-      process.exitCode = 1;
-      if (child.exitCode === null) child.kill();
-      return;
-    }
-    console.log(`Cartethyia is ready at ${url}`);
-    // The gateway child is already detached and unref'd; this Node process is
-    // the only thing still holding the launching terminal open. Exit once the
-    // URL has been shown so the shell prompt comes back.
-    setTimeout(() => process.exit(0), 1_500);
-  };
-  const poll = () => {
-    if (settled) return;
-    if (fs.existsSync(startupSignalPath)) {
-      try {
-        const signal = JSON.parse(fs.readFileSync(startupSignalPath, "utf8"));
-        if (signal.status === "ready" && typeof signal.url === "string") {
-          finish(null, signal.url);
-          return;
-        }
-        if (signal.status === "failed" && typeof signal.message === "string") {
-          finish(new Error(signal.message));
-          return;
-        }
-      } catch {}
-    }
-    if (spawnError) {
-      finish(spawnError);
-      return;
-    }
-    if (Date.now() >= deadline) {
-      finish(new Error("startup did not complete within 60 seconds"));
-      return;
-    }
-    setTimeout(poll, 150);
-  };
-  // On Windows the spawned process is `wscript.exe`, which hands off to the
-  // tray and exits immediately — a successful handoff, not a failed start. Only
-  // a direct spawn's exit says anything about the tray, so the deadline covers
-  // the handoff case and this guard covers the direct one.
-  if (!useWindowsDetach) {
-    child.once("exit", (code, signal) => {
-      if (!settled) setTimeout(() => finish(new Error(`the tray process exited before readiness (code ${code ?? signal ?? "unknown"})`)), 250);
-    });
-  }
-  poll();
-} else {
-  child.once("exit", (code, signal) => {
-    if (signal) {
-      process.kill(process.pid, signal);
-      return;
-    }
-    process.exitCode = code ?? 1;
-  });
-}
+#!/usr/bin/env node
+"use strict";
+
+const fs = require("node:fs");
+const { randomUUID } = require("node:crypto");
+const os = require("node:os");
+const path = require("node:path");
+const { spawn } = require("node:child_process");
+
+const packageRoot = path.resolve(__dirname, "..", "..", "..");
+const cliPath = path.join(packageRoot, "scripts", "cli", "main.ts");
+const configDir = process.env.CARTETHYIA_CONFIG_DIR || (
+  process.platform === "win32"
+    ? path.join(process.env.APPDATA || os.homedir(), "Cartethyia")
+    : process.platform === "darwin"
+      ? path.join(os.homedir(), "Library", "Application Support", "Cartethyia")
+      : path.join(process.env.XDG_CONFIG_HOME || path.join(os.homedir(), ".config"), "Cartethyia")
+);
+const trayMode = process.argv[2] === "tray";
+// The launcher itself runs under Node, so `process.execPath` is node.exe — not
+// the Bun the child needs. Resolve bun from PATH instead; WScript.Shell does
+// not inherit this process's environment, so the child needs an absolute path.
+function resolveBunPath() {
+  if (process.env.CARTETHYIA_BUN) return process.env.CARTETHYIA_BUN;
+  const name = process.platform === "win32" ? "bun.exe" : "bun";
+  for (const dir of (process.env.PATH || "").split(path.delimiter)) {
+    if (!dir) continue;
+    const candidate = path.join(dir, name);
+    try {
+      if (fs.statSync(candidate).isFile()) return candidate;
+    } catch {}
+  }
+  return name;
+}
+
+const startupSignalPath = trayMode
+  ? path.join(os.tmpdir(), `cartethyia-tray-${process.pid}-${randomUUID()}.json`)
+  : null;
+let spawnError;
+// On Windows the tray must start with no console at all, and neither
+// `detached: true` nor `windowsHide: true` achieves that: a console-subsystem
+// child of a window-less parent still allocates a console, and inside Windows
+// Terminal the tab is already on screen before a flag can take effect
+// (measured). `wscript.exe` is GUI-subsystem, so it never allocates one, and a
+// child launched from it with window style 0 inherits that. Elsewhere
+// `detached: true` is enough.
+const useWindowsDetach = process.platform === "win32" && trayMode;
+const hiddenLauncher = path.join(packageRoot, "scripts", "cli", "tray", "hidden-window.vbs");
+const child = useWindowsDetach
+  ? spawn(
+      "wscript.exe",
+      // Absolute path, not "bun": the VBS runs through WScript.Shell, which
+      // does not inherit this process's PATH additions and resolves a bare
+      // name against the system PATH only.
+      ["//nologo", hiddenLauncher, resolveBunPath(), "run", cliPath, ...process.argv.slice(2)],
+      {
+        cwd: packageRoot,
+        detached: true,
+        stdio: "ignore",
+        windowsHide: true,
+        env: {
+          ...process.env,
+          CARTETHYIA_CONFIG_DIR: configDir,
+          CARTETHYIA_TRAY_STARTUP_SIGNAL: startupSignalPath,
+        },
+      },
+    )
+  : spawn(resolveBunPath(), ["run", cliPath, ...process.argv.slice(2)], {
+      cwd: packageRoot,
+      detached: trayMode,
+      stdio: trayMode ? "ignore" : "inherit",
+      windowsHide: trayMode,
+      env: {
+        ...process.env,
+        CARTETHYIA_CONFIG_DIR: configDir,
+        ...(trayMode ? { CARTETHYIA_TRAY_STARTUP_SIGNAL: startupSignalPath } : {}),
+      },
+    });
+
+child.once("error", (error) => {
+  spawnError = error;
+  if (error.code === "ENOENT") {
+    console.error("Cartethyia requires Bun 1.4.0 or newer. Install Bun from https://bun.sh, then run this command again.");
+  } else {
+    console.error(`Could not start Cartethyia's Bun runtime: ${error.message}`);
+  }
+  process.exitCode = 1;
+});
+
+if (trayMode) {
+  child.unref();
+  console.log("Loading Cartethyia…");
+  let settled = false;
+  const deadline = Date.now() + 60_000;
+  const finish = (error, url) => {
+    if (settled) return;
+    settled = true;
+    try {
+      fs.unlinkSync(startupSignalPath);
+    } catch {}
+    if (error) {
+      // `error.message` can be an empty string when the failure came from a
+      // signal rather than a thrown message, which printed as a bare
+      // "Cartethyia failed to start:" with no cause. Fall back to the code and
+      // name what usually causes it.
+      const detail =
+        error.message && error.message.trim() !== ""
+          ? error.message
+          : `the process exited without a message (code ${child.exitCode ?? "unknown"})`;
+      console.error(`Cartethyia failed to start: ${detail}`);
+      console.error(
+        "If another Cartethyia is already running on this port, stop the terminal that started it first.",
+      );
+      process.exitCode = 1;
+      if (child.exitCode === null) child.kill();
+      return;
+    }
+    console.log(`Cartethyia is ready at ${url}`);
+    // The gateway child is already detached and unref'd; this Node process is
+    // the only thing still holding the launching terminal open. Exit once the
+    // URL has been shown so the shell prompt comes back.
+    setTimeout(() => process.exit(0), 1_500);
+  };
+  const poll = () => {
+    if (settled) return;
+    if (fs.existsSync(startupSignalPath)) {
+      try {
+        const signal = JSON.parse(fs.readFileSync(startupSignalPath, "utf8"));
+        if (signal.status === "ready" && typeof signal.url === "string") {
+          finish(null, signal.url);
+          return;
+        }
+        if (signal.status === "failed" && typeof signal.message === "string") {
+          finish(new Error(signal.message));
+          return;
+        }
+      } catch {}
+    }
+    if (spawnError) {
+      finish(spawnError);
+      return;
+    }
+    if (Date.now() >= deadline) {
+      finish(new Error("startup did not complete within 60 seconds"));
+      return;
+    }
+    setTimeout(poll, 150);
+  };
+  // On Windows the spawned process is `wscript.exe`, which hands off to the
+  // tray and exits immediately — a successful handoff, not a failed start. Only
+  // a direct spawn's exit says anything about the tray, so the deadline covers
+  // the handoff case and this guard covers the direct one.
+  if (!useWindowsDetach) {
+    child.once("exit", (code, signal) => {
+      if (!settled) setTimeout(() => finish(new Error(`the tray process exited before readiness (code ${code ?? signal ?? "unknown"})`)), 250);
+    });
+  }
+  poll();
+} else {
+  child.once("exit", (code, signal) => {
+    if (signal) {
+      process.kill(process.pid, signal);
+      return;
+    }
+    process.exitCode = code ?? 1;
+  });
+}