cartethyia 2.4.5 → 2.4.6

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()

package/scripts/cli/ui/background.ts

@@ -0,0 +1,49 @@
+import { spawn } from "node:child_process";
+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 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 {
+  if (process.platform !== "win32") {
+    const child = spawn(process.execPath, [...args], {
+      cwd: PACKAGE_ROOT,
+      detached: true,
+      stdio: "ignore",
+    });
+    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 },
+  );
+  child.unref();
+}

package/src/boot/app.ts

@@ -196,7 +196,9 @@ export function createGatewayApp(deps: GatewayAppDeps) {
   const peerAddresses = new WeakMap<Request, string>();
   const serveDashboard = async ({ request }: { request: Request }): Promise<Response> => {
     const pathname = fastPathname(request.url);
-    const result = await staticHandler(pathname);
+    // The client's `accept-encoding` is what decides whether a precompressed
+    // `.gz` sibling can be served instead of the plain asset.
+    const result = await staticHandler(pathname, request.headers.get("accept-encoding"));
     return new Response(result.body ? (result.body as unknown as BodyInit) : null, {
       status: result.status,
       headers: result.headers,