cartethyia 2.5.10 → 2.6.0

package/scripts/cli/tray/windows.ps1

@@ -1,107 +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
-}
-
-# 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()
+# 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/tray.ts

@@ -1,6 +1,6 @@
 import { resolvePackagePath } from "../../src/config/package-paths";
 import { resolvePort } from "../../src/config/runtime";
-import { ensureDrainToken } from "./instance";
+import { ensureDrainToken, attachGateway, stopAttachedGateway, type RunningGateway } from "./instance";
 import { startGateway } from "./gateway";
 import { stopGateway } from "./gateway";
 import { readInstalledVersion } from "./version";
@@ -8,6 +8,8 @@ import { reportTrayStartup } from "./startup-signal";
 import { createTray } from "./tray/index";
 import { openUrl } from "./background";
 import { exportBackup, resetConsoleAccount } from "./admin";
+import { acquireController, inheritedControllerHandoff } from "./controller";
+import { restoreControllerAfterFailedHandoff } from "./controller";
 
 /**
  * Runs the gateway with a tray icon. The tray is platform-specific (`tray/`):
@@ -39,6 +41,24 @@ const TRAY_HEALTH_POLL_MS = 10_000;
 const TRAY_HEALTH_MISSES_BEFORE_CLOSE = 3;
 
 export async function startTray(): Promise<void> {
+  const handoff = inheritedControllerHandoff();
+  const controller = acquireController("tray", handoff);
+  const releaseController = (): void => controller.release();
+  const failedHandoff = (): void => {
+    if (handoff) restoreControllerAfterFailedHandoff(handoff);
+  };
+  process.once("exit", failedHandoff);
+  process.once("exit", releaseController);
+  try {
+    await runTray();
+  } finally {
+    process.removeListener("exit", failedHandoff);
+    controller.release();
+    process.removeListener("exit", releaseController);
+  }
+}
+
+async function runTray(): Promise<void> {
   const port = resolvePort();
   const drainToken = ensureDrainToken();
   const dashboardUrl = `http://127.0.0.1:${port}/console`;
@@ -46,6 +66,7 @@ export async function startTray(): Promise<void> {
   const currentVersion = await readInstalledVersion();
 
   let gateway: Bun.Subprocess | null = null;
+  let adoptedGateway: RunningGateway | null = null;
   let closing = false;
   let resetArmed = false;
   let closePromise: Promise<void> | undefined;
@@ -83,6 +104,7 @@ export async function startTray(): Promise<void> {
       const current: Bun.Subprocess | null = gateway;
       gateway = null;
       if (current) await stopGateway(current, port, drainToken);
+      else if (adoptedGateway !== null) await stopAttachedGateway(adoptedGateway, drainToken);
       await tray.close();
       process.exitCode = exitCode;
     })();
@@ -96,7 +118,9 @@ export async function startTray(): Promise<void> {
     if (id === "version") return void (await openUrl(releasesUrl));
     if (id === "backup") {
       const result = await exportBackup(port, drainToken);
-      if (result !== null) {
+      if ("error" in result) {
+        console.error(result.error);
+      } else {
         console.log(
           `Backup written to ${result.path} (${(result.bytes / 1024).toFixed(1)} KiB). Telemetry is not included.`,
         );
@@ -129,7 +153,8 @@ export async function startTray(): Promise<void> {
     // down too and "Hide to tray" left nothing serving. `stopGateway` drains
     // over HTTP before it ever reaches for `kill()`, so detaching costs the
     // exit path nothing: the tray can still stop the gateway on Exit.
-    gateway = await startGateway(port, drainToken, { detached: true });
+    adoptedGateway = await attachGateway(port, drainToken);
+    if (adoptedGateway === null) gateway = await startGateway(port, drainToken, { detached: true });
     // The launcher that spawned this tray is blocked on a signal file: it
     // cannot read our stdio, because the tray is detached. Without this write
     // it waits out its 60 s deadline and reports a failure for a tray that is
@@ -146,7 +171,7 @@ export async function startTray(): Promise<void> {
     // is up reads as up regardless of who spawned it.
     while (!closing) {
       await Bun.sleep(TRAY_HEALTH_POLL_MS);
-      if (closing || gateway === null) continue;
+      if (closing || gateway === null && adoptedGateway === null) continue;
       const alive = await fetch(`http://127.0.0.1:${port}/health`, {
         signal: AbortSignal.timeout(2_000),
       }).then((response) => response.ok).catch(() => false);

package/scripts/cli/update.ts

@@ -1,40 +1,40 @@
-/**
- * The update path.
- *
- * npm cannot replace this package's directory while a process is executing out
- * of it (EBUSY on Windows). So we spawn the installer as a detached process,
- * print a short notice, and exit — the installer runs after this process is gone.
- * After install, it attempts to restart the gateway (systemd if available, else
- * `cartethyia start`), so the new version comes up automatically.
- * Cross-OS: uses npm.cmd on Windows.
- */
-import { spawn } from "node:child_process";
-
-export function updateCommand(): string {
-  return "npm install -g cartethyia@latest --prefer-online";
-}
-
-export function runDetachedUpdate(): void {
-  const isWin = process.platform === "win32";
-  const shell = isWin ? "cmd.exe" : "/bin/sh";
-  const install = "npm install -g cartethyia@latest --prefer-online";
-  const restart = isWin
-    ? "cartethyia start"
-    : "systemctl restart cartethyia 2>/dev/null || cartethyia start";
-  const script = `${install} && ${restart}`;
-  const args = isWin ? ["/c", script] : ["-c", script];
-  const child = spawn(shell, args, {
-    detached: true,
-    stdio: "ignore",
-  });
-  child.unref();
-}
-
-export function printUpdateInstructions(from: string, to: string | null): void {
-  console.log("");
-  console.log(`Update available: ${from} \u2192 ${to ?? "latest"}`);
-  console.log("");
-  console.log("Starting detached update; this process will exit now.");
-  console.log("The gateway will restart automatically after the install.");
-  console.log("");
+/**
+ * The update path.
+ *
+ * npm cannot replace this package's directory while a process is executing out
+ * of it (EBUSY on Windows). So we spawn the installer as a detached process,
+ * print a short notice, and exit — the installer runs after this process is gone.
+ * After install, it attempts to restart the gateway (systemd if available, else
+ * `cartethyia start`), so the new version comes up automatically.
+ * Cross-OS: uses npm.cmd on Windows.
+ */
+import { spawn } from "node:child_process";
+
+export function updateCommand(): string {
+  return "npm install -g cartethyia@latest --prefer-online";
+}
+
+export function runDetachedUpdate(): void {
+  const isWin = process.platform === "win32";
+  const shell = isWin ? "cmd.exe" : "/bin/sh";
+  const install = "npm install -g cartethyia@latest --prefer-online";
+  const restart = isWin
+    ? "cartethyia start"
+    : "systemctl restart cartethyia 2>/dev/null || cartethyia start";
+  const script = `${install} && ${restart}`;
+  const args = isWin ? ["/c", script] : ["-c", script];
+  const child = spawn(shell, args, {
+    detached: true,
+    stdio: "ignore",
+  });
+  child.unref();
+}
+
+export function printUpdateInstructions(from: string, to: string | null): void {
+  console.log("");
+  console.log(`Update available: ${from} \u2192 ${to ?? "latest"}`);
+  console.log("");
+  console.log("Starting detached update; this process will exit now.");
+  console.log("The gateway will restart automatically after the install.");
+  console.log("");
 }

package/scripts/cli/version.ts

@@ -1,67 +1,67 @@
-import { resolvePackagePath } from "../../src/config/package-paths";
-
-export async function readRequiredBunVersion(): Promise<string> {
-  const metadata: unknown = await Bun.file(resolvePackagePath("package.json")).json();
-  if (metadata === null || typeof metadata !== "object" || !("engines" in metadata) ||
-    metadata.engines === null || typeof metadata.engines !== "object" ||
-    !("bun" in metadata.engines) || typeof metadata.engines.bun !== "string") {
-    throw new Error("Cartethyia's required Bun version is unavailable in package.json");
-  }
-  const minimum = metadata.engines.bun.trim().replace(/^>=\s*/, "");
-  if (!/^\d+(?:\.\d+){0,2}$/.test(minimum)) throw new Error(`Unsupported Bun engine requirement: ${metadata.engines.bun}`);
-  return minimum;
-}
-
-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;
-}
-
-export async function assertBunVersion(): Promise<void> {
-  const minimum = await readRequiredBunVersion();
-  if (bunVersionAtLeast(Bun.version, minimum)) return;
-  throw new Error(`Bun ${minimum} or newer is required (found ${Bun.version}). Install it from https://bun.sh and run this command again.`);
-}
-
-/** Reads the version from the installed package manifest. */
-export async function readInstalledVersion(): Promise<string> {
-  const metadata: unknown = await Bun.file(resolvePackagePath("package.json")).json();
-  if (
-    metadata === null ||
-    typeof metadata !== "object" ||
-    !("version" in metadata) ||
-    typeof metadata.version !== "string"
-  ) {
-    throw new Error("Cartethyia package version is unavailable");
-  }
-  return metadata.version;
-}
-
-/** Asks the npm registry for the newest published version, or null on failure. */
-export async function readLatestPublishedVersion(): Promise<string | null> {
-  try {
-    const response = await fetch("https://registry.npmjs.org/cartethyia/latest", {
-      signal: AbortSignal.timeout(4_000),
-    });
-    if (!response.ok) return null;
-    const metadata: unknown = await response.json();
-    if (
-      metadata !== null &&
-      typeof metadata === "object" &&
-      "version" in metadata &&
-      typeof metadata.version === "string"
-    ) {
-      return metadata.version;
-    }
-    return null;
-  } catch {
-    return null;
-  }
-}
+import { resolvePackagePath } from "../../src/config/package-paths";
+
+export async function readRequiredBunVersion(): Promise<string> {
+  const metadata: unknown = await Bun.file(resolvePackagePath("package.json")).json();
+  if (metadata === null || typeof metadata !== "object" || !("engines" in metadata) ||
+    metadata.engines === null || typeof metadata.engines !== "object" ||
+    !("bun" in metadata.engines) || typeof metadata.engines.bun !== "string") {
+    throw new Error("Cartethyia's required Bun version is unavailable in package.json");
+  }
+  const minimum = metadata.engines.bun.trim().replace(/^>=\s*/, "");
+  if (!/^\d+(?:\.\d+){0,2}$/.test(minimum)) throw new Error(`Unsupported Bun engine requirement: ${metadata.engines.bun}`);
+  return minimum;
+}
+
+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;
+}
+
+export async function assertBunVersion(): Promise<void> {
+  const minimum = await readRequiredBunVersion();
+  if (bunVersionAtLeast(Bun.version, minimum)) return;
+  throw new Error(`Bun ${minimum} or newer is required (found ${Bun.version}). Install it from https://bun.sh and run this command again.`);
+}
+
+/** Reads the version from the installed package manifest. */
+export async function readInstalledVersion(): Promise<string> {
+  const metadata: unknown = await Bun.file(resolvePackagePath("package.json")).json();
+  if (
+    metadata === null ||
+    typeof metadata !== "object" ||
+    !("version" in metadata) ||
+    typeof metadata.version !== "string"
+  ) {
+    throw new Error("Cartethyia package version is unavailable");
+  }
+  return metadata.version;
+}
+
+/** Asks the npm registry for the newest published version, or null on failure. */
+export async function readLatestPublishedVersion(): Promise<string | null> {
+  try {
+    const response = await fetch("https://registry.npmjs.org/cartethyia/latest", {
+      signal: AbortSignal.timeout(4_000),
+    });
+    if (!response.ok) return null;
+    const metadata: unknown = await response.json();
+    if (
+      metadata !== null &&
+      typeof metadata === "object" &&
+      "version" in metadata &&
+      typeof metadata.version === "string"
+    ) {
+      return metadata.version;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}

package/scripts/cli/wordmark.ts

@@ -1,58 +1,58 @@
-/**
- * The console wordmark.
- *
- * Rendered with half-block characters so each letter is two pixel rows tall in
- * one character cell, and coloured with a horizontal gradient across the
- * Cartethyia blue-grey range. The caller decides whether to print it: a
- * non-colour terminal, or one narrower than the wordmark, should skip it.
- */
-
-const WORDMARK: readonly string[] = [
-  " ██████╗ █████╗ ██████╗ ████████╗███████╗████████╗██╗  ██╗██╗   ██╗██╗ █████╗ ",
-  "██╔════╝██╔══██╗██╔══██╗╚══██╔══╝██╔════╝╚══██╔══╝██║  ██║╚██╗ ██╔╝██║██╔══██╗",
-  "██║     ███████║██████╔╝   ██║   █████╗     ██║   ███████║ ╚████╔╝ ██║███████║",
-  "██║     ██╔══██║██╔══██╗   ██║   ██╔══╝     ██║   ██╔══██║  ╚██╔╝  ██║██╔══██║",
-  "╚██████╗██║  ██║██║  ██║   ██║   ███████╗   ██║   ██║  ██║   ██║   ██║██║  ██║",
-  " ╚═════╝╚═╝  ╚═╝╚═╝  ╚═╝   ╚═╝   ╚══════╝   ╚═╝   ╚═╝  ╚═╝   ╚═╝   ╚═╝╚═╝  ╚═╝",
-];
-
-/** Blue-grey gradient: dim at the edges, brighter through the middle. */
-const GRADIENT: readonly [number, number, number][] = [
-  [90, 120, 150],
-  [120, 160, 200],
-  [150, 200, 240],
-  [120, 160, 200],
-  [90, 120, 150],
-];
-
-const RESET = "\u001b[0m";
-
-/**
- * Returns the wordmark lines with per-column colour, or an empty array when the
- * terminal is too narrow or colour is disabled.
- */
-export function renderWordmark(columns = process.stdout.columns ?? 80): string[] {
-  if (process.env.NO_COLOR !== undefined) return [];
-  const width = WORDMARK[0]!.length;
-  if (columns < width) return [];
-
-  const coloured: string[] = [];
-  for (const row of WORDMARK) {
-    let line = "";
-    let current = -1;
-    for (let column = 0; column < row.length; column += 1) {
-      const band = Math.min(
-        GRADIENT.length - 1,
-        Math.floor((column / width) * GRADIENT.length),
-      );
-      const [r, g, b] = GRADIENT[band]!;
-      if (band !== current) {
-        line += `\u001b[38;2;${r};${g};${b}m`;
-        current = band;
-      }
-      line += row[column];
-    }
-    coloured.push(`${line}${RESET}`);
-  }
-  return coloured;
-}
+/**
+ * The console wordmark.
+ *
+ * Rendered with half-block characters so each letter is two pixel rows tall in
+ * one character cell, and coloured with a horizontal gradient across the
+ * Cartethyia blue-grey range. The caller decides whether to print it: a
+ * non-colour terminal, or one narrower than the wordmark, should skip it.
+ */
+
+const WORDMARK: readonly string[] = [
+  " ██████╗ █████╗ ██████╗ ████████╗███████╗████████╗██╗  ██╗██╗   ██╗██╗ █████╗ ",
+  "██╔════╝██╔══██╗██╔══██╗╚══██╔══╝██╔════╝╚══██╔══╝██║  ██║╚██╗ ██╔╝██║██╔══██╗",
+  "██║     ███████║██████╔╝   ██║   █████╗     ██║   ███████║ ╚████╔╝ ██║███████║",
+  "██║     ██╔══██║██╔══██╗   ██║   ██╔══╝     ██║   ██╔══██║  ╚██╔╝  ██║██╔══██║",
+  "╚██████╗██║  ██║██║  ██║   ██║   ███████╗   ██║   ██║  ██║   ██║   ██║██║  ██║",
+  " ╚═════╝╚═╝  ╚═╝╚═╝  ╚═╝   ╚═╝   ╚══════╝   ╚═╝   ╚═╝  ╚═╝   ╚═╝   ╚═╝╚═╝  ╚═╝",
+];
+
+/** Blue-grey gradient: dim at the edges, brighter through the middle. */
+const GRADIENT: readonly [number, number, number][] = [
+  [90, 120, 150],
+  [120, 160, 200],
+  [150, 200, 240],
+  [120, 160, 200],
+  [90, 120, 150],
+];
+
+const RESET = "\u001b[0m";
+
+/**
+ * Returns the wordmark lines with per-column colour, or an empty array when the
+ * terminal is too narrow or colour is disabled.
+ */
+export function renderWordmark(columns = process.stdout.columns ?? 80): string[] {
+  if (process.env.NO_COLOR !== undefined) return [];
+  const width = WORDMARK[0]!.length;
+  if (columns < width) return [];
+
+  const coloured: string[] = [];
+  for (const row of WORDMARK) {
+    let line = "";
+    let current = -1;
+    for (let column = 0; column < row.length; column += 1) {
+      const band = Math.min(
+        GRADIENT.length - 1,
+        Math.floor((column / width) * GRADIENT.length),
+      );
+      const [r, g, b] = GRADIENT[band]!;
+      if (band !== current) {
+        line += `\u001b[38;2;${r};${g};${b}m`;
+        current = band;
+      }
+      line += row[column];
+    }
+    coloured.push(`${line}${RESET}`);
+  }
+  return coloured;
+}