cartethyia 2.5.7 → 2.5.8

package/scripts/build/compile.ts

@@ -0,0 +1,88 @@
+/**
+ * Compiles the standalone gateway binary from the AOT build output.
+ *
+ * Two things here are load-bearing and neither is obvious:
+ *
+ * 1. **The entry is `dist/main.js`, not `src/main.ts`.** `aot.ts` runs
+ *    Elysia's AOT plugin, which rewrites TypeBox imports into statically wired
+ *    mirrors in its output. Bundling the raw source instead discards that work,
+ *    and Elysia's CommonJS build reaches TypeBox through a lazy
+ *    `require("typebox/type")` that the bundler cannot follow — the compiled
+ *    binary then dies at startup with `Cannot find module 'typebox/type'`,
+ *    because a standalone executable has no node_modules to resolve against.
+ *
+ * 2. **`NODE_ENV` is set to `production` here, at build time, because Bun bakes
+ *    it into the binary.** `bun build --compile` replaces `process.env.NODE_ENV`
+ *    with a literal, so the value present when this runs is the value the
+ *    binary reports forever after — a runtime `NODE_ENV=production` cannot
+ *    change it. What depends on it is the logger: the `pino-pretty` transport
+ *    is attached only in development, and that transport spawns a worker thread
+ *    loading `real-require`, which a standalone executable does not carry. A
+ *    binary built without this line therefore bundles a logger that crashes on
+ *    first use. The migrations folder is not part of this decision —
+ *    `resolveMigrationsFolder()` resolves `<cwd>/migrations` unconditionally.
+ *
+ * Usage: `bun run scripts/build/compile.ts [--outfile dist/cartethyia]`
+ */
+const DEFAULT_OUTFILE = "dist/cartethyia";
+
+/**
+ * The artifact path `bun build --compile` actually writes for `outfile`.
+ *
+ * Bun appends `.exe` when it compiles for Windows, so the extensionless
+ * `dist/cartethyia` handed to it never exists on that platform. This is the one
+ * place that knows where the compiled binary lands; `start-production.ts`
+ * resolves its target from here instead of re-deriving the name, because a
+ * launcher that probed the requested path reported "run bun run build first"
+ * immediately after a successful build.
+ */
+export function compiledBinaryPath(outfile: string = DEFAULT_OUTFILE): string {
+  return process.platform === "win32" && !outfile.toLowerCase().endsWith(".exe")
+    ? `${outfile}.exe`
+    : outfile;
+}
+
+/** Reads `--outfile <path>`, falling back to a positional path or the default. */
+export function resolveOutfile(argv: readonly string[]): string {
+  const flag = argv.indexOf("--outfile");
+  if (flag !== -1) {
+    const value = argv[flag + 1];
+    if (value === undefined || value.length === 0) {
+      throw new Error("--outfile requires a path");
+    }
+    return value;
+  }
+  return argv.find((arg) => arg.length > 0 && !arg.startsWith("-")) ?? DEFAULT_OUTFILE;
+}
+
+export async function buildBinary(
+  outfile: string = DEFAULT_OUTFILE,
+  buildFn: typeof Bun.build = Bun.build,
+): Promise<void> {
+  // Baked into the output; see the note above before changing it. Substituted
+  // through `define` rather than by assigning `process.env`, because this module
+  // is imported by tests in the same process — mutating the environment would
+  // flip `NODE_ENV` for every later suite in that process.
+  const result = await buildFn({
+    entrypoints: ["dist/main.js"],
+    minify: true,
+    target: "bun",
+    define: { "process.env.NODE_ENV": JSON.stringify("production") },
+    compile: {
+      outfile,
+    },
+  });
+
+  if (result.logs.length > 0) {
+    for (const log of result.logs) console.error(`[binary] ${log.message}`);
+    throw new Error(`binary build emitted ${result.logs.length} diagnostic(s)`);
+  }
+  console.log(`[binary] compiled ${compiledBinaryPath(outfile)}`);
+}
+
+if (import.meta.main) {
+  await buildBinary(resolveOutfile(process.argv.slice(2))).catch((error: unknown) => {
+    console.error("[binary] build failed:", error);
+    process.exit(1);
+  });
+}

package/scripts/build/restart.ts

@@ -0,0 +1,120 @@
+#!/usr/bin/env bun
+/**
+ * restart.ts — rebuild and restart the compiled gateway gracefully.
+ *
+ * Why this exists: a hard kill (`taskkill /F`, `kill -9`) truncates every
+ * in-flight response. On Linux the process handles SIGTERM/SIGINT and drains,
+ * but Windows has no deliverable catchable signal — `process.kill(pid,
+ * "SIGTERM")` of a console-less Bun process runs no JS handler (measured). So
+ * this script stops the running instance through the drain endpoint when
+ * `CARTETHYIA_DRAIN_TOKEN` is set (loopback + `x-drain-token`), and only falls
+ * back to a hard kill when no token is configured.
+ *
+ * Env:
+ *   CARTETHYIA_DRAIN_TOKEN  token for POST /admin/drain (required for graceful stop)
+ *   PORT                    gateway port (default 12800)
+ *   DRAIN_WAIT_MS           how long to wait for the drain to finish (default 30000)
+ */
+import { compiledBinaryPath } from "./compile";
+
+function intEnv(name: string, fallback: number): number {
+  const raw = process.env[name];
+  if (raw === undefined || raw.trim() === "") return fallback;
+  const value = Number(raw);
+  return Number.isFinite(value) && value > 0 ? Math.trunc(value) : fallback;
+}
+
+const PORT = intEnv("PORT", 12800);
+const DRAIN_WAIT_MS = intEnv("DRAIN_WAIT_MS", 30_000);
+
+/** PIDs currently listening on `port` (best-effort, platform-specific). */
+async function listeningPids(port: number): Promise<number[]> {
+  try {
+    if (process.platform === "win32") {
+      const proc = Bun.spawnSync(["netstat", "-ano", "-p", "TCP"]);
+      const out = new TextDecoder().decode(proc.stdout);
+      const pids = new Set<number>();
+      for (const line of out.split(/\r?\n/)) {
+        if (!line.includes(`:${port} `) || !line.includes("LISTENING")) continue;
+        const pid = Number(line.trim().split(/\s+/).pop());
+        if (Number.isInteger(pid) && pid > 0) pids.add(pid);
+      }
+      return [...pids];
+    }
+    const proc = Bun.spawnSync(["lsof", "-ti", `tcp:${port}`, "-sTCP:LISTEN"]);
+    return new TextDecoder()
+      .decode(proc.stdout)
+      .split(/\s+/)
+      .map(Number)
+      .filter((n) => Number.isInteger(n) && n > 0);
+  } catch {
+    return [];
+  }
+}
+
+async function waitForPortFree(port: number, timeoutMs: number): Promise<boolean> {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if ((await listeningPids(port)).length === 0) return true;
+    await new Promise((r) => setTimeout(r, 250));
+  }
+  return (await listeningPids(port)).length === 0;
+}
+
+async function stopGracefully(): Promise<boolean> {
+  const token = process.env.CARTETHYIA_DRAIN_TOKEN?.trim();
+  if (token === undefined || token.length === 0) {
+    console.warn("[restart] CARTETHYIA_DRAIN_TOKEN unset — cannot drain gracefully");
+    return false;
+  }
+  try {
+    const response = await fetch(`http://127.0.0.1:${PORT}/admin/drain`, {
+      method: "POST",
+      headers: { "x-drain-token": token },
+    });
+    if (!response.ok) {
+      console.warn(`[restart] drain request returned HTTP ${response.status}`);
+      return false;
+    }
+    console.log("[restart] drain acknowledged; waiting for the process to exit");
+    return await waitForPortFree(PORT, DRAIN_WAIT_MS);
+  } catch (error) {
+    console.warn(`[restart] drain request failed: ${(error as Error).message}`);
+    return false;
+  }
+}
+
+async function hardKill(): Promise<void> {
+  const pids = await listeningPids(PORT);
+  if (pids.length === 0) return;
+  console.warn(`[restart] force-killing pid(s) ${pids.join(", ")} on :${PORT}`);
+  for (const pid of pids) {
+    try {
+      process.kill(pid, "SIGKILL");
+    } catch {
+      // Already gone.
+    }
+  }
+  await waitForPortFree(PORT, 5_000);
+}
+
+async function main(): Promise<number> {
+  const graceful = await stopGracefully();
+  if (!graceful) await hardKill();
+
+  console.log("[restart] building");
+  const build = Bun.spawnSync(["bun", "run", "build"], { stdout: "inherit", stderr: "inherit" });
+  if (build.exitCode !== 0) {
+    console.error("[restart] build failed");
+    return build.exitCode ?? 1;
+  }
+
+  const binary = compiledBinaryPath();
+  console.log(`[restart] starting ${binary}`);
+  const child = Bun.spawn([binary], { stdin: "ignore", stdout: "inherit", stderr: "inherit" });
+  return await child.exited;
+}
+
+if (import.meta.main) {
+  process.exit(await main());
+}

package/scripts/build/start.ts

@@ -0,0 +1,25 @@
+/** Runs the compiled binary from the repository root. */
+import { compiledBinaryPath } from "./compile";
+
+/** Runs the compiled binary with inherited stdio; resolves to its exit code. */
+export async function startBinary(): Promise<number> {
+  const binary = compiledBinaryPath();
+  if (!(await Bun.file(binary).exists())) {
+    throw new Error(`${binary} is missing; run bun run build first`);
+  }
+
+  process.env.NODE_ENV ??= "production";
+  process.env.CARTETHYIA_SERVER_MAX_BODY_BYTES ??= String(8 * 1024 * 1024 * 1024);
+
+  const child = Bun.spawn([binary], {
+    env: process.env,
+    stdin: "inherit",
+    stdout: "inherit",
+    stderr: "inherit",
+  });
+  return await child.exited;
+}
+
+if (import.meta.main) {
+  process.exit(await startBinary());
+}

package/scripts/health.ts

@@ -0,0 +1,186 @@
+import { access } from "node:fs/promises";
+import { constants } from "node:fs";
+import { join, resolve } from "node:path";
+import { Client } from "pg";
+import Redis from "ioredis";
+import { hasPlaceholderSecrets, readEnvFile } from "./cli/env";
+import { parseServiceUrl, probeTcpService } from "./cli/services";
+import { resolveDataDir, resolveDbMode } from "../src/persistence/db-mode";
+import { bunVersionAtLeast, readRequiredBunVersion } from "./cli/version";
+
+export type CheckPhase = "preflight" | "configuration" | "runtime";
+export type CheckStatus = "pass" | "warn" | "fail" | "skip";
+export interface CheckResult {
+  id: string;
+  phase: CheckPhase;
+  status: CheckStatus;
+  required: boolean;
+  summary: string;
+  remediation?: string;
+}
+export interface HealthContext {
+  target: "local" | "vps" | "docker";
+  env: Record<string, string>;
+  envPath: string;
+  port: number;
+  phases: readonly CheckPhase[];
+}
+export interface HealthDependencies {
+  dockerCompose: () => Promise<boolean>;
+  postgres: (url: string) => Promise<void>;
+  redis: (url: string) => Promise<void>;
+  tcp: typeof probeTcpService;
+  ready: (port: number) => Promise<string | null>;
+  writable: (path: string) => Promise<boolean>;
+  exists: (path: string) => Promise<boolean>;
+}
+const defaultDependencies: HealthDependencies = {
+  async dockerCompose() {
+    try {
+      return Bun.spawnSync(["docker", "compose", "version"], { stdout: "ignore", stderr: "ignore" }).exitCode === 0;
+    } catch {
+      return false;
+    }
+  },
+  async postgres(url) {
+    const client = new Client({ connectionString: url, connectionTimeoutMillis: 3_000 });
+    try {
+      await client.connect();
+      await client.query("SELECT 1");
+    } finally {
+      await client.end().catch(() => undefined);
+    }
+  },
+  async redis(url) {
+    const client = new Redis(url, { lazyConnect: true, connectTimeout: 3_000, maxRetriesPerRequest: 0 });
+    try {
+      await client.connect();
+      const result = await client.ping();
+      if (result !== "PONG") throw new Error(`Unexpected Redis response: ${result}`);
+    } finally {
+      client.disconnect();
+    }
+  },
+  tcp: probeTcpService,
+  async ready(port) {
+    try {
+      const response = await fetch(`http://127.0.0.1:${port}/health/ready`, { signal: AbortSignal.timeout(3_000) });
+      return response.ok ? null : `HTTP ${response.status}`;
+    } catch (error) {
+      return error instanceof Error ? error.message : "connection failed";
+    }
+  },
+  async writable(path) {
+    try {
+      await access(path, constants.W_OK);
+      return true;
+    } catch {
+      return false;
+    }
+  },
+  async exists(path) {
+    try {
+      await access(path, constants.F_OK);
+      return true;
+    } catch {
+      return false;
+    }
+  },
+};
+function result(id: string, phase: CheckPhase, status: CheckStatus, summary: string, required = true, remediation?: string): CheckResult {
+  return { id, phase, status, required, summary, ...(remediation ? { remediation } : {}) };
+}
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+export async function runHealthChecks(
+  context: HealthContext,
+  dependencies: HealthDependencies = defaultDependencies,
+): Promise<CheckResult[]> {
+  const results: CheckResult[] = [];
+  const phases = new Set(context.phases);
+  const env = { ...(await readEnvFile(context.envPath)), ...context.env };
+  if (phases.has("preflight")) {
+    const minimum = await readRequiredBunVersion();
+    const bunOkay = bunVersionAtLeast(Bun.version, minimum);
+    results.push(result("runtime-bun", "preflight", bunOkay ? "pass" : "fail", bunOkay ? `Bun ${Bun.version} satisfies ${minimum}+` : `Bun ${Bun.version} is older than required ${minimum}`, true, bunOkay ? undefined : "Install the required Bun version"));
+    if (context.target === "docker") {
+      const available = await dependencies.dockerCompose();
+      results.push(result("docker-compose", "preflight", available ? "pass" : "fail", available ? "Docker Compose is available" : "Docker Compose is unavailable", true, "Install Docker Engine with the Compose plugin"));
+    }
+  }
+  if (phases.has("configuration")) {
+    if (!(await dependencies.exists(context.envPath))) {
+      results.push(result("env-file", "configuration", "fail", `.env not found at ${context.envPath}`, true, "Run setup or the installer"));
+    } else {
+      results.push(result("env-file", "configuration", "pass", `.env exists at ${context.envPath}`));
+    }
+    let mode: "lite" | "full" | null = null;
+    try {
+      mode = resolveDbMode(env);
+      results.push(result("db-mode", "configuration", "pass", `Database mode: ${mode}`));
+    } catch (error) {
+      results.push(result("db-mode", "configuration", "fail", errorMessage(error), true, "Set CARTETHYIA_DB_MODE=lite or full"));
+    }
+    const key = env.CARTETHYIA_ENCRYPTION_KEY?.trim() ?? "";
+    results.push(!key
+      ? result("encryption-key", "configuration", "fail", "CARTETHYIA_ENCRYPTION_KEY is missing")
+      : hasPlaceholderSecrets(key)
+        ? result("encryption-key", "configuration", "fail", "CARTETHYIA_ENCRYPTION_KEY is still a placeholder")
+        : result("encryption-key", "configuration", "pass", "Encryption key is configured"));
+    if (mode === "lite") {
+      const data = resolveDataDir(env);
+      const paths = [data, env.CARTETHYIA_TELEMETRY_PAYLOAD_DIR?.trim() || join(data, "telemetry-payloads"), env.CARTETHYIA_INSTALL_ID_DIR?.trim() || join(data, ".cartethyia")];
+      for (const path of paths) {
+        if (context.target === "docker" && path.startsWith("/app/")) {
+          results.push(result(`container-path-${path}`, "configuration", "pass", `Container state path is declared: ${path}; runtime checks verify its writability`));
+          continue;
+        }
+        const writable = await dependencies.writable(resolve(path));
+        results.push(result(`writable-${path}`, "configuration", writable ? "pass" : "fail", `${writable ? "Writable" : "Not writable"}: ${path}`));
+      }
+    }
+    if (mode === "full") {
+      const url = env.DATABASE_URL?.trim() ?? "";
+      if (!url) results.push(result("postgres", "configuration", "fail", "DATABASE_URL is required in Full mode"));
+      else if (!parseServiceUrl(url)) results.push(result("postgres", "configuration", "fail", "DATABASE_URL must include a host and port"));
+      else if (context.target === "docker") results.push(result("postgres", "configuration", "pass", "External DATABASE_URL is configured; container readiness verifies connectivity"));
+      else {
+        try {
+          await dependencies.postgres(url);
+          results.push(result("postgres", "configuration", "pass", "PostgreSQL authenticated SELECT 1 succeeded"));
+        } catch (error) {
+          const parsed = parseServiceUrl(url)!;
+          const tcp = await dependencies.tcp(parsed.host, parsed.port, 3_000);
+          results.push(result("postgres", "configuration", tcp.success ? "warn" : "fail", tcp.success ? "PostgreSQL port is reachable, but authenticated query failed" : "PostgreSQL is unreachable or authentication failed", true, "Verify DATABASE_URL credentials and database availability"));
+        }
+      }
+    }
+    const redis = env.REDIS_URL?.trim() ?? "";
+    if (!redis) results.push(result("redis", "configuration", "pass", "Redis is not configured; in-memory coordination applies"));
+    else if (context.target === "docker") results.push(result("redis", "configuration", "pass", "Container Redis coordination is configured; container readiness verifies connectivity"));
+    else {
+      try {
+        await dependencies.redis(redis);
+        results.push(result("redis", "configuration", "pass", "Redis PING succeeded"));
+      } catch (error) {
+        results.push(result("redis", "configuration", "fail", "Configured Redis is unavailable or authentication failed", true, "Verify REDIS_URL and Redis availability"));
+      }
+    }
+  }
+  if (phases.has("runtime")) {
+    if (!Number.isInteger(context.port) || context.port < 1 || context.port > 65535) {
+      results.push(result("app-ready", "runtime", "fail", `Invalid application port: ${context.port}`));
+    } else {
+      const failure = await dependencies.ready(context.port);
+      results.push(result("app-ready", "runtime", failure ? "fail" : "pass", failure ? `Application is not ready: ${failure}` : `Application is ready on port ${context.port}`));
+    }
+  }
+  return results;
+}
+export function hasRequiredFailure(results: readonly CheckResult[]): boolean {
+  return results.some((item) => item.required && item.status === "fail");
+}
+export function skippedRuntimeCheck(): CheckResult {
+  return result("app-ready", "runtime", "skip", "Runtime readiness was not requested", false);
+}