cartethyia 2.4.5 → 2.5.0

package/package.json

@@ -1,17 +1,17 @@
 {
   "name": "cartethyia",
-  "version": "2.4.5",
+  "version": "2.5.0",
   "description": "A powerful, self-hosted reverse proxy for OpenAI- and Anthropic-compatible AI clients, powered by native Bun and Elysia. It serves both protocols from a single server, routes every model across any configured provider, and translates requests and responses in real time — streaming and prompt caching included. Underneath it runs a full delivery engine: per-account health tracking, quota and cooldown enforcement, automatic failover across pools and providers, usage accounting, and telemetry. Point OpenCode, Cline, Claude Code, Codex, or any compatible client at Cartethyia and it keeps its native protocol while the gateway absorbs every provider-specific difference behind it. Runs on embedded SQLite or external PostgreSQL with optional Redis coordination, ships as a global CLI with a system-tray console, and needs only Bun 1.4+ alongside Node.js/npm.",
   "license": "GPL-3.0-only",
   "type": "module",
   "packageManager": "bun@1.4.0",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/risunCode/Cartethyia.git"
+    "url": "git+https://github.com/risunCodex/Cartethyia.git"
   },
-  "homepage": "https://github.com/risunCode/Cartethyia#readme",
+  "homepage": "https://github.com/risunCodex/Cartethyia#readme",
   "bugs": {
-    "url": "https://github.com/risunCode/Cartethyia/issues"
+    "url": "https://github.com/risunCodex/Cartethyia/issues"
   },
   "keywords": [
     "ai",
@@ -21,18 +21,14 @@
     "self-hosted"
   ],
   "bin": {
-    "cartethyia": "scripts/cli/cli-launcher.cjs",
-    "carte": "scripts/cli/carte-launcher.cjs"
+    "cartethyia": "scripts/cli/bin/cartethyia.cjs",
+    "carte": "scripts/cli/bin/carte.cjs"
   },
   "files": [
     "scripts/cli/",
-    "scripts/operations/probe-egress.ts",
-    "scripts/operations/restart.ts",
-    "scripts/shared/env.ts",
     "src/",
     "migrations/",
     "dist/dashboard/",
-    "tray-assets/",
     ".env.example",
     "README.md"
   ],
@@ -45,48 +41,47 @@
   "scripts": {
     "dev": "bun run dev:stack",
     "dev:watch": "bun run scripts/dev/supervisor.ts",
-    "test": "bun run scripts/test/run.ts",
-    "build": "bun run scripts/build/build.ts",
+    "test": "bun run scripts/ci/run.ts",
+    "build": "bun run scripts/binary/build.ts",
     "prepack": "bun run dashboard:build",
-    "setup": "bun run scripts/cli/setup.ts",
-    "start": "bun run scripts/operations/start-production.ts",
-    "doctor": "bun run scripts/cli/doctor.ts",
+    "setup": "bun run scripts/cli/command/setup.ts",
+    "start": "bun run scripts/cli/main.ts start",
+    "doctor": "bun run scripts/cli/command/doctor.ts",
     "probe:egress": "bun run scripts/operations/probe-egress.ts",
-    "restart": "bun run scripts/operations/restart.ts",
-    "build:aot": "bun run scripts/build/aot.ts",
+    "restart": "bun run scripts/binary/restart.ts",
+    "build:aot": "bun run scripts/binary/aot.ts",
     "dev:stack": "concurrently -n BACKEND,DASHBOARD -c cyan,magenta --kill-others-on-fail \"bun run dev:backend\" \"bun run dashboard:dev\"",
     "typecheck": "tsc --noEmit",
-    "test:watch": "bun run scripts/test/run.ts --watch",
+    "test:watch": "bun run scripts/ci/run.ts --watch",
     "test-db:up": "docker compose -f docker-compose.test.yml up -d --wait postgres-test",
     "dev:backend": "bun run --hot src/main.ts",
-    "dev:console-auth": "bun run scripts/dev/console-session.ts",
-    "dev:visual-baseline": "bun run scripts/dev/visual-baseline.ts",
-    "build:binary": "bun run scripts/build/binary.ts",
-    "test:backend": "bun run scripts/test/run.ts --scope backend",
+    "dev:console-auth": "bun run scripts/qa/console-session.ts",
+    "dev:visual-baseline": "bun run scripts/qa/visual-baseline.ts",
+    "build:binary": "bun run scripts/binary/compile.ts",
+    "test:backend": "bun run scripts/ci/run.ts --scope backend",
     "test-db:down": "docker compose -f docker-compose.test.yml down",
     "dashboard:dev": "bun run --cwd dashboard dev",
-    "test-db:check": "bun run scripts/test/db-check.ts",
-    "dashboard:test": "bun run scripts/test/run.ts --scope dashboard",
+    "test-db:check": "bun run scripts/ci/db-check.ts",
+    "dashboard:test": "bun run scripts/ci/run.ts --scope dashboard",
     "test-db:reset": "docker compose -f docker-compose.test.yml down -v && docker compose -f docker-compose.test.yml up -d --wait postgres-test",
     "dashboard:build": "bun run --cwd dashboard build",
-    "dashboard:typecheck": "bun run --cwd dashboard typecheck"
+    "dashboard:typecheck": "bun run --cwd dashboard typecheck",
+    "check:migrations": "bun run scripts/ci/check-migrations.ts"
   },
   "dependencies": {
-    "@bufbuild/protobuf": "^2.14.1",
-    "@electric-sql/pglite": "^0.5.8",
     "drizzle-orm": "0.45.2",
     "elysia": "^2.0.0-beta.16",
     "enquirer": "^2.4.1",
-    "exact-mirror": "^1.2.6",
-    "impit": "^0.14.5",
     "ioredis": "6.0.0",
+    "jose": "^6.2.12",
+    "jsonrepair": "^3.15.0",
     "pg": "8.23.0",
     "pino": "^10.3.1",
     "pino-pretty": "^13.1.3",
+    "protobufjs": "^7.6.5",
     "socks-proxy-agent": "^10.1.0",
     "systray2": "2.1.4",
     "typebox": "1.3.27",
-    "undici": "^8.10.2",
     "ws": "8.22.0"
   },
   "devDependencies": {
@@ -94,6 +89,7 @@
     "@types/ws": "8.18.1",
     "bun-types": "1.4.0",
     "concurrently": "^10.0.5",
+    "drizzle-kit": "^0.31.11",
     "typescript": "5.9.2"
   }
 }

package/scripts/cli/{carte-launcher.cjs → bin/carte.cjs}

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

package/scripts/cli/{cli-launcher.cjs → bin/cartethyia.cjs}

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

package/scripts/cli/command/admin.ts

@@ -0,0 +1,65 @@
+/**
+ * The two admin actions the menu and the tray both offer.
+ *
+ * Both go through the running gateway rather than the database file: the
+ * gateway holds the connection and the schema is dialect-dependent, so reading
+ * or writing the tables from this process would need a second implementation
+ * of both.
+ */
+
+/**
+ * Asks the gateway to write a gzipped config backup into the download
+ * directory. Returns the written path and counts, or null when it failed.
+ */
+export async function exportBackup(
+  port: number,
+  token: string,
+): Promise<{ path: string; bytes: number; counts: Record<string, number> } | null> {
+  try {
+    const response = await fetch(`http://127.0.0.1:${port}/admin/export-backup`, {
+      method: "POST",
+      headers: { "content-type": "application/json", "x-drain-token": token },
+      body: JSON.stringify({}),
+      signal: AbortSignal.timeout(60_000),
+    });
+    if (!response.ok) {
+      const detail = await response.text().catch(() => "");
+      console.error(`The gateway refused the backup (HTTP ${response.status}). ${detail}`.trim());
+      return null;
+    }
+    return (await response.json()) as {
+      path: string;
+      bytes: number;
+      counts: Record<string, number>;
+    };
+  } catch {
+    console.error("Could not reach the gateway. Is it still running?");
+    return null;
+  }
+}
+
+/**
+ * Posts the console-account reset to the running gateway.
+ *
+ * Returns 0 on success and 1 on any failure so the caller can print one line
+ * either way.
+ */
+export async function resetConsoleAccount(port: number, token: string): Promise<number> {
+  try {
+    const response = await fetch(`http://127.0.0.1:${port}/admin/reset-console-account`, {
+      method: "POST",
+      headers: { "content-type": "application/json", "x-drain-token": token },
+      body: JSON.stringify({ confirm: "RESET" }),
+      signal: AbortSignal.timeout(10_000),
+    });
+    if (!response.ok) {
+      const detail = await response.text().catch(() => "");
+      console.error(`The gateway refused the reset (HTTP ${response.status}). ${detail}`.trim());
+      return 1;
+    }
+    return 0;
+  } catch {
+    console.error("Could not reach the gateway. Is it still running?");
+    return 1;
+  }
+}