cartethyia 2.5.4 → 2.5.6

package/scripts/cli/main.ts

@@ -1,29 +1,31 @@
 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, runDetachedUpdate } from "./command/update";
-import { reportTrayStartup } from "./support/startup-signal";
+import { readRequiredBunVersion, assertBunVersion } from "./version";
+import { printUpdateInstructions, runDetachedUpdate } from "./update";
 
 process.env.CARTETHYIA_CONFIG_DIR ??= resolveUserConfigDir();
 
-const HELP = `Cartethyia ${MINIMUM_BUN_VERSION}+ (Bun is required)
+const HELP = (minimumBunVersion: string) => `Cartethyia ${minimumBunVersion}+ (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 stop
   cartethyia menu
   cartethyia doctor
+  cartethyia admin reset-lockout <username> <clientIp>
+  cartethyia admin reset-lockout --all
   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.
+and headless. A menu started by this command drains its child gateway on Exit;
+leaving a menu attached to an existing gateway only detaches. Use stop for that.
 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.
+Stop a detached gateway with cartethyia stop (or the install's ./carte stop).
 Setup explains Lite (embedded SQLite) and Full (external PostgreSQL), then saves
 configuration under the current user's Cartethyia config directory.
 `;
@@ -33,37 +35,72 @@ 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 });
+  // Imported here rather than at module scope: `support/env` pulls in the
+  // package-root resolver and `node:fs/promises`, and `carte --help` (which
+  // never reads a .env) should not pay for either before it prints.
+  const { ENV_PATH, readEnvFile } = await import("./env");
+  // Bun injects PORT=12800 when no explicit port was supplied. It is a
+  // runner default, not an operator override; without removing it, a saved
+  // custom port is ignored by npm/carte and the gateway starts on 12800.
+  // Preserve any non-default/custom shell value exactly as before.
+  if (process.env.PORT === "12800") delete process.env.PORT;
   const values = await readEnvFile(ENV_PATH);
   for (const [key, value] of Object.entries(values)) {
     if (!process.env[key]) process.env[key] = value;
   }
 }
 
+/**
+ * Reports tray readiness to the launcher waiting on a signal file.
+ *
+ * Deferred to a dynamic import for the same reason as `loadUserConfig`: only
+ * the tray path writes this file, so the other commands should not load
+ * `node:fs` machinery they never touch.
+ */
+async function reportTrayFailed(message: string): Promise<void> {
+  const { reportTrayStartup } = await import("./startup-signal");
+  reportTrayStartup({ status: "failed", message });
+}
+
 async function main(): Promise<void> {
-  assertBunVersion();
+  await assertBunVersion();
   const [command] = process.argv.slice(2);
-  if (command === "setup" || command === "start" || command === "tray" || command === "menu" || command === "doctor") {
+  if (command === "setup" || command === "start" || command === "stop" || command === "tray" || command === "menu" || command === "doctor" || command === "admin") {
     await loadUserConfig();
   }
 
   switch (command) {
     case "setup": {
-      const { setup } = await import("./command/setup");
+      const { setup } = await import("./setup");
       await setup();
       return;
     }
     case "start": {
-      const { startForeground } = await import("./command/start");
+      const { startForeground } = await import("./start");
       await startForeground();
       return;
     }
+    case "stop": {
+      const { resolvePort } = await import("../../src/config/runtime");
+      const { ensureDrainToken, attachGateway, stopAttachedGateway } = await import("./instance");
+      const port = resolvePort();
+      const token = ensureDrainToken();
+      const gateway = await attachGateway(port, token);
+      if (!gateway) {
+        console.log("No running Cartethyia gateway is owned by this installation.");
+        return;
+      }
+      await stopAttachedGateway(gateway, token);
+      console.log("Cartethyia stopped.");
+      return;
+    }
     case "menu": {
-      const { startMenu } = await import("./command/console-menu");
+      const { startMenu } = await import("./console-menu");
       await startMenu();
       return;
     }
     case "tray": {
-      const { startTray } = await import("./command/tray");
+      const { startTray } = await import("./tray");
       await startTray();
       return;
     }
@@ -94,10 +131,16 @@ async function main(): Promise<void> {
       return;
     }
     case "doctor": {
-      const { doctor } = await import("./command/doctor");
+      const { doctor } = await import("./doctor");
       await doctor();
       return;
     }
+    case "admin": {
+      if (process.argv[3] !== "reset-lockout") throw new Error("Usage: cartethyia admin reset-lockout <username> <clientIp> | --all");
+      const { resetLockout } = await import("./admin");
+      await resetLockout(process.argv.slice(4));
+      return;
+    }
     case "update":
       runDetachedUpdate();
       printUpdateInstructions("this install", null);
@@ -105,17 +148,17 @@ async function main(): Promise<void> {
     case "--help":
     case "-h":
     case undefined:
-      console.log(HELP);
+      console.log(HELP(await readRequiredBunVersion()));
       return;
     default:
-      console.error(`Unknown command: ${command}\n\n${HELP}`);
+      console.error(`Unknown command: ${command}\n\n${HELP(await readRequiredBunVersion())}`);
       process.exitCode = 2;
   }
 }
 
-main().catch((error: unknown) => {
+main().catch(async (error: unknown) => {
   const message = error instanceof Error ? error.message : "unknown error";
-  if (process.argv[2] === "tray") reportTrayStartup({ status: "failed", message });
+  if (process.argv[2] === "tray") await reportTrayFailed(message);
   console.error(`Cartethyia failed: ${message}`);
   process.exitCode = 1;
 });

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

@@ -1,64 +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.",
-  ];
-}
+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/port.ts

@@ -0,0 +1,100 @@
+import { closeSync, openSync, readSync, statSync } from "node:fs";
+import { createServer } from "node:net";
+import { join } from "node:path";
+import { resolveEnvPath } from "./env";
+
+export interface ListenPortProbe {
+  readonly status: "free" | "blocked";
+  readonly code?: string;
+}
+
+/**
+ * Probes the actual listener boundary rather than inferring availability from
+ * an HTTP response. A non-HTTP service still owns the port when /health is
+ * unreachable. The probe socket closes before the real gateway starts.
+ */
+export async function probeListenPort(port: number): Promise<ListenPortProbe> {
+  return await new Promise((resolve) => {
+    const server = createServer();
+    server.unref();
+    server.once("error", (error: NodeJS.ErrnoException) => {
+      resolve({ status: "blocked", ...(error.code ? { code: error.code } : {}) });
+    });
+    server.listen({ port, host: "0.0.0.0", exclusive: true }, () => {
+      server.close(() => resolve({ status: "free" }));
+    });
+  });
+}
+
+export function changePortInstructions(envPath = resolveEnvPath()): string {
+  return `Stop the process using this port, or change PORT in ${envPath}. ` +
+    "If CARTETHYIA_PUBLIC_ORIGIN contains the old port, update it too, then start Cartethyia again.";
+}
+
+export function blockedPortMessage(port: number, envPath = resolveEnvPath()): string {
+  return `Cannot start Cartethyia: port ${port} is already in use by another process. ` +
+    `No process was stopped. ${changePortInstructions(envPath)}`;
+}
+
+export function listenPortErrorMessage(port: number, probe: ListenPortProbe): string {
+  if (probe.code === "EADDRINUSE") return blockedPortMessage(port);
+  const reason = probe.code ?? "unknown listener error";
+  return `Cannot start Cartethyia: the operating system refused to listen on port ${port} (${reason}). ` +
+    `Check port permissions and firewall policy, or choose another port. ${changePortInstructions()}`;
+}
+
+function readNewLogTail(path: string, offset: number): string {
+  try {
+    const size = statSync(path).size;
+    const length = Math.min(Math.max(size - offset, 0), 8_000);
+    if (length === 0) return "";
+    const buffer = Buffer.alloc(length);
+    const fd = openSync(path, "r");
+    try {
+      readSync(fd, buffer, 0, length, Math.max(offset, size - length));
+    } finally {
+      closeSync(fd);
+    }
+    const lines = buffer.toString("utf8")
+      .replace(/\u001b\[[0-9;]*m/g, "")
+      .split(/\r?\n/)
+      .map((line) => line.trim())
+      .filter((line) => line.length > 0)
+      .filter((line) => !/^at\s/.test(line) && !/^\d+\s*\|/.test(line) && !/^Bun v\d/.test(line))
+      .map((line) => {
+        if (line.length <= 300) return line;
+        const marker = /(?:Error:|ENOENT|EADDRINUSE|address already in use)/.exec(line);
+        return marker ? line.slice(marker.index, marker.index + 300) : "";
+      })
+      .filter((line) => line.length > 0);
+    return lines.slice(-8).map((line) => line.slice(0, 300)).join("\n").slice(-1_200);
+  } catch {
+    return "";
+  }
+}
+
+export function startupFailureMessage(
+  port: number,
+  exitCode: number,
+  logPath: string | null,
+  logOffset = 0,
+): string {
+  const detail = logPath ? readNewLogTail(logPath, logOffset) : "";
+  const log = logPath ?? "unavailable (the config directory is not writable)";
+  const lines = [
+    `Cartethyia exited with code ${exitCode} before becoming ready on port ${port}.`,
+  ];
+  if (detail) lines.push(`Gateway error: ${detail}`);
+  else lines.push("No startup error detail was captured from the gateway.");
+  if (/EADDRINUSE|address already in use/i.test(detail)) {
+    lines.push(blockedPortMessage(port));
+  } else {
+    lines.push("Correct the gateway error above, then run `carte` again. Use `cartethyia doctor` to check configuration.");
+  }
+  lines.push(`Startup log: ${log}`);
+  return lines.join("\n");
+}
+
+export function gatewayLogPath(configDir = process.env.CARTETHYIA_CONFIG_DIR): string | null {
+  return configDir ? join(configDir, "gateway.log") : null;
+}

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

@@ -1,88 +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;
-  }
-}
+/**
+ * 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;
+  }
+}