cartethyia 2.4.5 → 2.5.0

package/scripts/cli/main.ts

@@ -0,0 +1,94 @@
+import { mkdirSync } from "node:fs";
+import { resolveUserConfigDir } from "../../src/config/package-paths";
+import { ENV_PATH, readEnvFile } from "./support/env";
+import { MINIMUM_BUN_VERSION, assertBunVersion } from "./support/bun";
+import { printUpdateInstructions } from "./command/update";
+import { reportTrayStartup } from "./support/startup-signal";
+
+process.env.CARTETHYIA_CONFIG_DIR ??= resolveUserConfigDir();
+
+const HELP = `Cartethyia ${MINIMUM_BUN_VERSION}+ (Bun is required)
+
+Usage:
+  carte                  start, then show an arrow-key menu (no GUI needed)
+  carte --tray           start with a system-tray icon instead
+  cartethyia setup [--non-interactive]
+  cartethyia start
+  cartethyia menu
+  cartethyia doctor
+  cartethyia update
+
+carte starts the gateway in the background and leaves only the console menu on
+your terminal — Open Console, Reset password, Backup, Update, Hide to tray,
+Exit. Arrow keys and Enter; no desktop environment needed, so it works over SSH
+and headless. Exiting the menu drains the gateway.
+carte --tray uses a system-tray icon instead, which needs a graphical session.
+Stop a gateway whose terminal is gone with Ctrl-C in that terminal.
+Setup explains Lite (embedded SQLite) and Full (external PostgreSQL), then saves
+configuration under the current user's Cartethyia config directory.
+`;
+
+/** Loads the user's `.env` into the environment without overriding it. */
+async function loadUserConfig(): Promise<void> {
+  const configDir = process.env.CARTETHYIA_CONFIG_DIR;
+  if (!configDir) throw new Error("Cartethyia config directory could not be resolved");
+  mkdirSync(configDir, { recursive: true });
+  const values = await readEnvFile(ENV_PATH);
+  for (const [key, value] of Object.entries(values)) {
+    if (!process.env[key]) process.env[key] = value;
+  }
+}
+
+async function main(): Promise<void> {
+  assertBunVersion();
+  const [command] = process.argv.slice(2);
+  if (command === "setup" || command === "start" || command === "tray" || command === "menu" || command === "doctor") {
+    await loadUserConfig();
+  }
+
+  switch (command) {
+    case "setup": {
+      const { setup } = await import("./command/setup");
+      await setup();
+      return;
+    }
+    case "start": {
+      const { startForeground } = await import("./command/start");
+      await startForeground();
+      return;
+    }
+    case "menu": {
+      const { startMenu } = await import("./command/console-menu");
+      await startMenu();
+      return;
+    }
+    case "tray": {
+      const { startTray } = await import("./command/tray");
+      await startTray();
+      return;
+    }
+    case "doctor": {
+      const { doctor } = await import("./command/doctor");
+      await doctor();
+      return;
+    }
+    case "update":
+      printUpdateInstructions("this install", null);
+      return;
+    case "--help":
+    case "-h":
+    case undefined:
+      console.log(HELP);
+      return;
+    default:
+      console.error(`Unknown command: ${command}\n\n${HELP}`);
+      process.exitCode = 2;
+  }
+}
+
+main().catch((error: unknown) => {
+  const message = error instanceof Error ? error.message : "unknown error";
+  if (process.argv[2] === "tray") reportTrayStartup({ status: "failed", message });
+  console.error(`Cartethyia failed: ${message}`);
+  process.exitCode = 1;
+});

package/scripts/cli/support/bun.ts

@@ -0,0 +1,27 @@
+/** Minimum Bun the repository declares in `package.json` `engines`. */
+export const MINIMUM_BUN_VERSION = "1.4.0";
+
+/**
+ * True when `actual` is at least `minimum`, compared as dotted integers.
+ * A non-numeric segment reads as 0, so a malformed version fails closed
+ * against a real minimum instead of passing.
+ */
+export function bunVersionAtLeast(actual: string, minimum: string): boolean {
+  const left = actual.split(".").map((part) => Number.parseInt(part, 10) || 0);
+  const right = minimum.split(".").map((part) => Number.parseInt(part, 10) || 0);
+  const length = Math.max(left.length, right.length);
+  for (let i = 0; i < length; i += 1) {
+    const a = left[i] ?? 0;
+    const b = right[i] ?? 0;
+    if (a !== b) return a > b;
+  }
+  return true;
+}
+
+/** Throws unless the running Bun satisfies the declared minimum. */
+export function assertBunVersion(): void {
+  if (bunVersionAtLeast(Bun.version, MINIMUM_BUN_VERSION)) return;
+  throw new Error(
+    `Bun ${MINIMUM_BUN_VERSION} or newer is required (found ${Bun.version}). Install it from https://bun.sh and run this command again.`,
+  );
+}

package/scripts/cli/support/env.ts

@@ -0,0 +1,99 @@
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { PACKAGE_ROOT } from "../../../src/config/package-paths";
+
+/**
+ * Absolute path of the repository root.
+ *
+ * Operational scripts and the npm runtime share one package-root resolver so
+ * assets and repository config do not depend on the caller's working directory.
+ */
+export const PROJECT_ROOT = PACKAGE_ROOT;
+
+/** Resolve the active `.env`; npm CLI sets a user-owned config directory. */
+export function resolveEnvPath(env: NodeJS.ProcessEnv = process.env): string {
+  const configDir = env.CARTETHYIA_CONFIG_DIR?.trim();
+  return configDir ? resolve(configDir, ".env") : resolve(PROJECT_ROOT, ".env");
+}
+
+/** Absolute path of the active `.env`. */
+export const ENV_PATH = resolveEnvPath();
+
+/**
+ * Reads a dotenv-style file without overriding already-exported variables.
+ */
+export async function readEnvFile(path: string): Promise<Record<string, string>> {
+  if (!existsSync(path)) return {};
+  const content = await readFile(path, "utf8");
+  const values: Record<string, string> = {};
+  for (const line of content.split(/\r?\n/)) {
+    if (line.startsWith("#")) continue;
+    const separator = line.indexOf("=");
+    if (separator <= 0) continue;
+    const key = line.slice(0, separator).trim();
+    const value = line.slice(separator + 1).trim();
+    if (key) values[key] = value;
+  }
+  return values;
+}
+
+/**
+ * Checks if a string contains a configured placeholder value.
+ */
+export function hasPlaceholderSecrets(value: string): boolean {
+  const normalized = value.toLowerCase();
+  return (
+    normalized.includes("replace-with") ||
+    normalized.includes("replace_me") ||
+    normalized.includes("your_")
+  );
+}
+
+/**
+ * Generates a 256-bit hex cartethyia encryption key.
+ *
+ * Hex is preferred over base64 because it never carries padding or `+`/`/`
+ * characters that confuse some dotenv shells, and it round-trips through
+ * every adapter that accepts either encoding. The install/setup helpers call
+ * this when the key is absent or still a placeholder.
+ */
+export function generateCartethyiaEncryptionKey(): string {
+  const bytes = new Uint8Array(32);
+  crypto.getRandomValues(bytes);
+  let hex = "";
+  for (let i = 0; i < bytes.length; i += 1) hex += bytes[i]!.toString(16).padStart(2, "0");
+  return hex;
+}
+
+/**
+ * Returns the mandatory-only `.env` body derived from `.env.example`.
+ *
+ * Mandatory means the key is assigned without a leading `#`. Optional entries
+ * (leading `#`) carry built-in defaults and must not be copied into a fresh
+ * `.env` — they would override the default with a literal `example` value.
+ * The generated body therefore contains only mandatory rows, plus a single
+ * `CARTETHYIA_ENCRYPTION_KEY` replacement when the caller supplies one.
+ */
+export async function mandatoryEnvBody(
+  examplePath: string,
+  overrides: Readonly<Record<string, string>> = {},
+): Promise<string> {
+  const raw = await readFile(examplePath, "utf8");
+  const lines: string[] = [];
+  for (const line of raw.split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (trimmed === "" || trimmed.startsWith("#")) continue;
+    const sep = line.indexOf("=");
+    if (sep <= 0) continue;
+    const key = line.slice(0, sep).trim();
+    if (!key) continue;
+    const value = (overrides as Record<string, string>)[key] ?? line.slice(sep + 1).trim();
+    lines.push(`${key}=${value}`);
+  }
+  // Preserve overrides even when the example row was commented out (legacy case).
+  for (const [key, value] of Object.entries(overrides)) {
+    if (!lines.some((l) => l.startsWith(`${key}=`))) lines.push(`${key}=${value}`);
+  }
+  return `${lines.join("\n")}\n`;
+}

package/scripts/cli/support/platform.ts

@@ -0,0 +1,64 @@
+export type LocalPlatform = "windows" | "macos" | "linux" | "unknown";
+
+/** Detects the host platform once so setup/doctor share identical labels. */
+export function getLocalPlatform(): LocalPlatform {
+  if (process.platform === "win32") return "windows";
+  if (process.platform === "darwin") return "macos";
+  if (process.platform === "linux") return "linux";
+  return "unknown";
+}
+
+/**
+ * Returns actionable hints for the configured local/external service.
+ * These are hints only: setup never assumes Docker or silently mutates an
+ * external service. Windows users commonly run PostgreSQL through Laragon;
+ * Redis may be native, WSL-backed, or external.
+ */
+export function getOsHints(service: "postgres" | "redis"): string[] {
+  const platform = getLocalPlatform();
+  if (platform === "windows") {
+    return service === "postgres"
+      ? [
+          "Windows / Laragon:",
+          "  Start Laragon (Start All) and ensure PostgreSQL is enabled.",
+          "  Verify PostgreSQL is listening on the DATABASE_URL host/port (usually 5432).",
+          "  External PostgreSQL is also supported — keep DATABASE_URL unchanged and reachable.",
+        ]
+      : [
+          "Windows / Redis:",
+          "  Start Redis through WSL, a native Redis-compatible service, or an external host.",
+          "  Verify Redis is listening on the REDIS_URL host/port (usually 6379).",
+          "  Or omit REDIS_URL to use the in-memory backend.",
+        ];
+  }
+  if (platform === "macos") {
+    return service === "postgres"
+      ? [
+          "macOS / Homebrew:",
+          "  brew services start postgresql@16 (or the installed PostgreSQL version).",
+          "  External PostgreSQL is also supported — verify DATABASE_URL reachability.",
+        ]
+      : [
+          "macOS / Redis:",
+          "  brew services start redis, or use an external Redis instance.",
+          "  Or omit REDIS_URL to use the in-memory backend.",
+        ];
+  }
+  if (platform === "linux") {
+    return service === "postgres"
+      ? [
+          "Linux / systemd:",
+          "  sudo systemctl start postgresql (or the installed PostgreSQL service).",
+          "  External PostgreSQL is also supported — verify DATABASE_URL reachability.",
+        ]
+      : [
+          "Linux / Redis:",
+          "  sudo systemctl start redis-server (or the installed Redis service).",
+          "  Or omit REDIS_URL to use the in-memory backend.",
+        ];
+  }
+  return [
+    `${service} is not reachable on this platform.`,
+    "Verify the configured service URL or use an external service.",
+  ];
+}

package/scripts/cli/support/services.ts

@@ -0,0 +1,88 @@
+/**
+ * TCP reachability checks for the services setup and doctor ask about.
+ *
+ * These are extracted from the env helpers so the dotenv reader and the probe
+ * stay independent: doctor can be imported without pulling in `.env` parsing.
+ */
+
+export interface ProbeResult {
+  success: boolean;
+  error?: string;
+}
+
+/**
+ * Opens a TCP connection to `host:port` and resolves once it connects, errors,
+ * or the timeout elapses. The socket is always closed so a probe never leaves a
+ * half-open connection behind.
+ */
+export async function probeTcpService(
+  host: string,
+  port: number,
+  timeoutMs: number,
+): Promise<ProbeResult> {
+  const { promise, resolve } = Promise.withResolvers<ProbeResult>();
+
+  const timeoutHandle = setTimeout(() => {
+    resolve({ success: false, error: "timeout" });
+  }, timeoutMs);
+
+  Bun.connect({
+    hostname: host,
+    port: port,
+    socket: {
+      open: () => {
+        clearTimeout(timeoutHandle);
+        resolve({ success: true });
+      },
+      data: () => {},
+      error: (err) => {
+        clearTimeout(timeoutHandle);
+        resolve({ success: false, error: String(err) });
+      },
+    },
+  })
+    .then((socket) => {
+      socket.end();
+    })
+    .catch((err) => {
+      clearTimeout(timeoutHandle);
+      resolve({ success: false, error: String(err) });
+    });
+
+  return promise;
+}
+
+/**
+ * Local PostgreSQL ports worth probing before asking for a URL. 5432 is the
+ * server default (Laragon, Homebrew, systemd); 5433 is the usual second
+ * instance when 5432 is already taken.
+ */
+export const LOCAL_POSTGRES_CANDIDATES = [
+  { host: "127.0.0.1", port: 5432 },
+  { host: "127.0.0.1", port: 5433 },
+] as const;
+
+/** First local PostgreSQL that accepts a TCP connection, or null. */
+export async function detectLocalPostgres(
+  timeoutMs: number,
+): Promise<{ host: string; port: number } | null> {
+  for (const candidate of LOCAL_POSTGRES_CANDIDATES) {
+    const probe = await probeTcpService(candidate.host, candidate.port, timeoutMs);
+    if (probe.success) return candidate;
+  }
+  return null;
+}
+
+/**
+ * Parses a service URL and requires an explicit host and port.
+ * Returns null if the URL is invalid or incomplete.
+ */
+export function parseServiceUrl(url: string): { host: string; port: number } | null {
+  try {
+    const urlObj = new URL(url);
+    if (!urlObj.hostname || !urlObj.port) return null;
+    return { host: urlObj.hostname, port: Number(urlObj.port) };
+  } catch {
+    return null;
+  }
+}

package/scripts/cli/support/startup-signal.ts

@@ -0,0 +1,23 @@
+import { writeFileSync } from "node:fs";
+
+/**
+ * Reports tray readiness to the launcher that is waiting on a signal file.
+ *
+ * The tray is spawned detached with no stdio, so the launcher cannot read its
+ * output; a one-shot file is the only channel that survives the parent exiting.
+ * `flag: "wx"` makes the write fail rather than overwrite, which keeps a late
+ * report from replacing the failure the launcher already acted on.
+ */
+export type TrayStartupSignal =
+  | { readonly status: "ready"; readonly url: string }
+  | { readonly status: "failed"; readonly message: string };
+
+export function reportTrayStartup(signal: TrayStartupSignal): void {
+  const signalPath = process.env.CARTETHYIA_TRAY_STARTUP_SIGNAL;
+  if (!signalPath) return;
+  try {
+    writeFileSync(signalPath, JSON.stringify(signal), { encoding: "utf8", flag: "wx" });
+  } catch {
+    // The launcher may have timed out and removed the one-shot signal file.
+  }
+}

package/scripts/cli/{version.ts → support/version.ts}

@@ -1,4 +1,4 @@
-import { resolvePackagePath } from "../../src/config/package-paths";
+import { resolvePackagePath } from "../../../src/config/package-paths";
 
 /** Reads the version from the installed package manifest. */
 export async function readInstalledVersion(): Promise<string> {

package/scripts/cli/tray/hidden-window.vbs

@@ -0,0 +1,28 @@
+' Launches a command with no console window at all.
+'
+' Why a VBS: `wscript.exe` is a GUI-subsystem host, so it never allocates a
+' console for itself. Everything it starts with window style 0 inherits that —
+' no console window is shown, and none is left behind. That is different from
+' spawning the child directly: a console-subsystem child spawned from a
+' window-less parent gets a new console unless CREATE_NO_WINDOW is passed, and
+' when the parent lives inside Windows Terminal the tab is already open before
+' any flag can take effect.
+'
+' Usage: wscript.exe //nologo launch-hidden.vbs <exe> [args...]
+' The third argument (True) would make wscript wait for the child; it must stay
+' False so the launcher returns immediately and the child outlives it.
+
+Set shell = CreateObject("WScript.Shell")
+
+command = ""
+For Each arg In WScript.Arguments
+  If command <> "" Then command = command & " "
+  command = command & """" & arg & """"
+Next
+
+If command = "" Then
+  WScript.Quit 2
+End If
+
+' 0 = hidden window, False = do not wait.
+shell.Run command, 0, False

package/scripts/cli/{tray.ts → tray/index.ts}

@@ -1,7 +1,7 @@
 import { spawn, type ChildProcess } from "node:child_process";
 import { createInterface } from "node:readline";
 import SysTray from "systray2";
-import { resolvePackagePath } from "../../src/config/package-paths";
+import { resolvePackagePath } from "../../../src/config/package-paths";
 
 /**
  * One tray row. `action` rows report their id on click; separators are drawn
@@ -66,7 +66,7 @@ class WindowsTray implements Tray {
         "-OutputFormat",
         "Text",
         "-File",
-        resolvePackagePath("scripts", "cli", "tray.ps1"),
+        resolvePackagePath("scripts", "cli", "tray", "windows.ps1"),
         "-IconPath",
         options.iconPath,
         "-Tooltip",
@@ -112,7 +112,7 @@ class WindowsTray implements Tray {
     let index = 0;
     for (const item of options.items) {
       if (item.kind === "separator") {
-        this.#send({ action: "add-item", index, title: "-", enabled: false });
+        this.#send({ action: "add-separator", index });
         index += 1;
         continue;
       }

package/scripts/cli/{tray.ps1 → tray/windows.ps1}

@@ -1,98 +1,107 @@
-# Cartethyia tray icon for Windows using NotifyIcon.
-#
-# Why PowerShell instead of a Node tray library: `systray2` and friends bundle a
-# helper binary and still leave the spawning process attached to a console, so
-# Windows Terminal shows an empty tab for the tray's whole lifetime. A
-# PowerShell NotifyIcon owns no console of its own when started with
-# -WindowStyle Hidden, and the protocol here is plain JSON lines on
-# stdin/stdout, so the parent stays in charge.
-#
-# Protocol: the parent writes one JSON object per line.
-#   {"action":"add-item","index":0,"title":"...","enabled":true}
-#   {"action":"update-item","index":0,"title":"...","enabled":true}
-#   {"action":"set-tooltip","text":"..."}
-#   {"action":"kill"}
-# This script writes one JSON object per line:
-#   {"type":"started"} {"type":"ready"} {"type":"click","index":0}
-param([string]$IconPath, [string]$Tooltip)
-
-$ErrorActionPreference = "Stop"
-
-Add-Type -AssemblyName System.Windows.Forms
-Add-Type -AssemblyName System.Drawing
-
-[Console]::OutputEncoding = [System.Text.Encoding]::UTF8
-[Console]::InputEncoding = [System.Text.Encoding]::UTF8
-$OutputEncoding = [System.Text.Encoding]::UTF8
-
-[System.Windows.Forms.Application]::EnableVisualStyles()
-[System.Windows.Forms.Application]::SetCompatibleTextRenderingDefault($false)
-
-$script:notifyIcon = New-Object System.Windows.Forms.NotifyIcon
-$script:notifyIcon.Icon = New-Object System.Drawing.Icon($IconPath)
-$script:notifyIcon.Text = $Tooltip
-$script:notifyIcon.Visible = $true
-
-$script:menu = New-Object System.Windows.Forms.ContextMenuStrip
-$script:notifyIcon.ContextMenuStrip = $script:menu
-$script:items = @()
-
-function Write-Event($obj) {
-  $json = $obj | ConvertTo-Json -Compress
-  [Console]::Out.WriteLine($json)
-  [Console]::Out.Flush()
-}
-
-function Add-MenuItem($index, $title, $enabled) {
-  $item = New-Object System.Windows.Forms.ToolStripMenuItem
-  $item.Text = $title
-  $item.Enabled = $enabled
-  $idx = $index
-  $item.Add_Click({ Write-Event @{ type = "click"; index = $idx } }.GetNewClosure())
-  $script:menu.Items.Add($item) | Out-Null
-  $script:items += $item
-}
-
-function Update-MenuItem($index, $title, $enabled) {
-  if ($index -lt $script:items.Count) {
-    $script:items[$index].Text = $title
-    $script:items[$index].Enabled = $enabled
-  }
-}
-
-function Set-Tooltip($text) {
-  # NotifyIcon.Text is capped at 63 characters.
-  if ($text.Length -gt 63) { $text = $text.Substring(0, 63) }
-  $script:notifyIcon.Text = $text
-}
-
-# Stdin is polled from the UI thread: a background thread reading Console.In
-# races the message loop and deadlocks when the menu is open.
-$script:timer = New-Object System.Windows.Forms.Timer
-$script:timer.Interval = 100
-$script:timer.Add_Tick({
-  try {
-    while ([Console]::In.Peek() -ne -1) {
-      $line = [Console]::In.ReadLine()
-      if ([string]::IsNullOrWhiteSpace($line)) { continue }
-      $cmd = $line | ConvertFrom-Json
-      switch ($cmd.action) {
-        "add-item"    { Add-MenuItem $cmd.index $cmd.title $cmd.enabled }
-        "update-item" { Update-MenuItem $cmd.index $cmd.title $cmd.enabled }
-        "set-tooltip" { Set-Tooltip $cmd.text }
-        "ready"       { Write-Event @{ type = "ready" } }
-        "kill"        {
-          $script:notifyIcon.Visible = $false
-          $script:notifyIcon.Dispose()
-          [System.Windows.Forms.Application]::Exit()
-        }
-      }
-    }
-  } catch {
-    Write-Event @{ type = "error"; message = $_.Exception.Message }
-  }
-})
-$script:timer.Start()
-
-Write-Event @{ type = "started" }
-[System.Windows.Forms.Application]::Run()
+# Cartethyia tray icon for Windows using NotifyIcon.
+#
+# Why PowerShell instead of a Node tray library: `systray2` and friends bundle a
+# helper binary and still leave the spawning process attached to a console, so
+# Windows Terminal shows an empty tab for the tray's whole lifetime. A
+# PowerShell NotifyIcon owns no console of its own when started with
+# -WindowStyle Hidden, and the protocol here is plain JSON lines on
+# stdin/stdout, so the parent stays in charge.
+#
+# Protocol: the parent writes one JSON object per line.
+#   {"action":"add-item","index":0,"title":"...","enabled":true}
+#   {"action":"update-item","index":0,"title":"...","enabled":true}
+#   {"action":"set-tooltip","text":"..."}
+#   {"action":"kill"}
+# This script writes one JSON object per line:
+#   {"type":"started"} {"type":"ready"} {"type":"click","index":0}
+param([string]$IconPath, [string]$Tooltip)
+
+$ErrorActionPreference = "Stop"
+
+Add-Type -AssemblyName System.Windows.Forms
+Add-Type -AssemblyName System.Drawing
+
+[Console]::OutputEncoding = [System.Text.Encoding]::UTF8
+[Console]::InputEncoding = [System.Text.Encoding]::UTF8
+$OutputEncoding = [System.Text.Encoding]::UTF8
+
+[System.Windows.Forms.Application]::EnableVisualStyles()
+[System.Windows.Forms.Application]::SetCompatibleTextRenderingDefault($false)
+
+$script:notifyIcon = New-Object System.Windows.Forms.NotifyIcon
+$script:notifyIcon.Icon = New-Object System.Drawing.Icon($IconPath)
+$script:notifyIcon.Text = $Tooltip
+$script:notifyIcon.Visible = $true
+
+$script:menu = New-Object System.Windows.Forms.ContextMenuStrip
+$script:notifyIcon.ContextMenuStrip = $script:menu
+$script:items = @()
+
+function Write-Event($obj) {
+  $json = $obj | ConvertTo-Json -Compress
+  [Console]::Out.WriteLine($json)
+  [Console]::Out.Flush()
+}
+
+function Add-MenuItem($index, $title, $enabled) {
+  $item = New-Object System.Windows.Forms.ToolStripMenuItem
+  $item.Text = $title
+  $item.Enabled = $enabled
+  $idx = $index
+  $item.Add_Click({ Write-Event @{ type = "click"; index = $idx } }.GetNewClosure())
+  $script:menu.Items.Add($item) | Out-Null
+  $script:items += $item
+}
+
+# A real ToolStripSeparator draws the divider. Sending a "-" title instead
+# renders a literal dash row, which is what the menu showed before.
+function Add-MenuSeparator($index) {
+  $item = New-Object System.Windows.Forms.ToolStripSeparator
+  $script:menu.Items.Add($item) | Out-Null
+  $script:items += $item
+}
+
+function Update-MenuItem($index, $title, $enabled) {
+  if ($index -lt $script:items.Count) {
+    $script:items[$index].Text = $title
+    $script:items[$index].Enabled = $enabled
+  }
+}
+
+function Set-Tooltip($text) {
+  # NotifyIcon.Text is capped at 63 characters.
+  if ($text.Length -gt 63) { $text = $text.Substring(0, 63) }
+  $script:notifyIcon.Text = $text
+}
+
+# Stdin is polled from the UI thread: a background thread reading Console.In
+# races the message loop and deadlocks when the menu is open.
+$script:timer = New-Object System.Windows.Forms.Timer
+$script:timer.Interval = 100
+$script:timer.Add_Tick({
+  try {
+    while ([Console]::In.Peek() -ne -1) {
+      $line = [Console]::In.ReadLine()
+      if ([string]::IsNullOrWhiteSpace($line)) { continue }
+      $cmd = $line | ConvertFrom-Json
+      switch ($cmd.action) {
+        "add-item"    { Add-MenuItem $cmd.index $cmd.title $cmd.enabled }
+        "add-separator" { Add-MenuSeparator $cmd.index }
+        "update-item" { Update-MenuItem $cmd.index $cmd.title $cmd.enabled }
+        "set-tooltip" { Set-Tooltip $cmd.text }
+        "ready"       { Write-Event @{ type = "ready" } }
+        "kill"        {
+          $script:notifyIcon.Visible = $false
+          $script:notifyIcon.Dispose()
+          [System.Windows.Forms.Application]::Exit()
+        }
+      }
+    }
+  } catch {
+    Write-Event @{ type = "error"; message = $_.Exception.Message }
+  }
+})
+$script:timer.Start()
+
+Write-Event @{ type = "started" }
+[System.Windows.Forms.Application]::Run()