cartethyia 2.4.5 → 2.5.0

package/scripts/cli/{doctor.ts → command/doctor.ts}

@@ -1,258 +1,257 @@
-import { accessSync, constants, existsSync, mkdirSync } from "node:fs";
-import {
-  ENV_PATH,
-  getLocalPlatform,
-  getOsHints,
-  hasPlaceholderSecrets,
-  parseServiceUrl,
-  probeTcpService,
-  readEnvFile,
-} from "../shared/env";
-import type { ProbeResult } from "../shared/env";
-import { resolveDataDir, resolveDbMode, type DbMode } from "../../src/persistence/db-mode";
-
-interface DoctorConfig {
-  envPath: string;
-  probeTimeoutMs: number;
-}
-
-function loadConfig(): DoctorConfig {
-  return {
-    envPath: ENV_PATH,
-    probeTimeoutMs: 3000,
-  };
-}
-
-/**
- * Operator escape hatch: clears the console login lockout bucket.
- *
- * The lockout is keyed by `<username>:<clientIp>` and lasts an hour, and there
- * is no console surface to clear it — a locked-out operator has no way back in
- * short of editing the database by hand. This is the documented reset.
- *
- * Usage:
- *   bun run doctor --reset-lockout <username> <clientIp>
- *   bun run doctor --reset-lockout --all
- */
-async function resetLockout(args: readonly string[]): Promise<void> {
-  const all = args.includes("--all");
-  const positional = args.filter((arg) => !arg.startsWith("--"));
-  if (!all && positional.length < 2) {
-    console.error("Usage: bun run doctor --reset-lockout <username> <clientIp>");
-    console.error("       bun run doctor --reset-lockout --all");
-    process.exit(1);
-  }
-
-  const env = await readEnvFile(ENV_PATH);
-  const databaseUrl = env.DATABASE_URL ?? process.env.DATABASE_URL;
-  if (!databaseUrl) {
-    console.error("✗ DATABASE_URL is not set; cannot reach the lockout table.");
-    process.exit(1);
-  }
-  process.env.DATABASE_URL = databaseUrl;
-
-  const { getDb, closeDb } = await import("../../src/persistence/boot");
-  const { consoleLockouts } = await import("../../src/persistence/schema");
-  const { eq, or } = await import("drizzle-orm");
-
-  const db = getDb();
-  try {
-    if (all) {
-      const cleared = await db.delete(consoleLockouts).returning({ ip: consoleLockouts.ip });
-      console.log(`✓ Cleared ${cleared.length} lockout row(s).`);
-      return;
-    }
-    const username = positional[0]!.trim().toLowerCase();
-    const clientIp = positional[1]!;
-    // The bucket key is `<identifier>:<ip>`; match either exact spelling so
-    // an operator does not have to guess how the identifier was normalized.
-    const cleared = await db
-      .delete(consoleLockouts)
-      .where(or(eq(consoleLockouts.ip, `${username}:${clientIp}`), eq(consoleLockouts.ip, clientIp)))
-      .returning({ ip: consoleLockouts.ip });
-    if (cleared.length === 0) {
-      console.log(`• No lockout row for ${username}:${clientIp} (already clear).`);
-    } else {
-      console.log(`✓ Cleared lockout for ${cleared.map((row) => row.ip).join(", ")}.`);
-    }
-  } finally {
-    await closeDb();
-  }
-}
-
-
-async function probeReadiness(port: number, timeoutMs: number): Promise<ProbeResult> {
-  const controller = new AbortController();
-  const timeoutHandle = setTimeout(() => controller.abort(), timeoutMs);
-
-  try {
-    const response = await fetch(`http://localhost:${port}/health/ready`, {
-      signal: controller.signal,
-    });
-
-    clearTimeout(timeoutHandle);
-
-    if (response.ok) {
-      return { success: true };
-    }
-    return { success: false, error: `HTTP ${response.status}` };
-  } catch (err) {
-    clearTimeout(timeoutHandle);
-    return { success: false, error: String(err) };
-  }
-}
-
-async function doctor(): Promise<void> {
-  const config = loadConfig();
-
-  const resetIndex = process.argv.indexOf("--reset-lockout");
-  if (resetIndex !== -1) {
-    await resetLockout(process.argv.slice(resetIndex + 1));
-    return;
-  }
-
-  console.log("🩺 Cartethyia Health Check\n");
-  console.log(`🖥️  Host platform: ${getLocalPlatform()}`);
-
-  // Step 1: Check .env exists
-  console.log("📋 Environment Configuration");
-  if (!existsSync(config.envPath)) {
-    console.log("  ✗ .env file not found");
-    console.log("  Run: bun setup\n");
-    process.exit(1);
-  }
-  console.log("  ✓ .env file exists");
-
-  // Step 2: Check required environment variables. DATABASE_URL is required in
-  // full mode only; lite keeps its database in the data dir. Redis is never
-  // required — unset means the in-memory backend.
-  const envVars = await readEnvFile(config.envPath);
-  // `CARTETHYIA_DB_MODE` has no default and throws when absent, which is the
-  // right answer at boot but the wrong one here: this command exists to report
-  // a broken environment readably, so the missing key joins the checklist
-  // instead of crashing before it prints.
-  const missing: string[] = [];
-  let dbMode: DbMode | null = null;
-  try {
-    dbMode = resolveDbMode({ ...process.env, ...envVars });
-  } catch {
-    console.log("  ✗ CARTETHYIA_DB_MODE is not set — run: bun setup");
-    // Counted as missing so this command exits non-zero. A boot would throw on
-    // the same key, so a green doctor here would be a false all-clear.
-    missing.push("CARTETHYIA_DB_MODE");
-  }
-  const required =
-    dbMode === "full"
-      ? ["DATABASE_URL", "CARTETHYIA_ENCRYPTION_KEY"]
-      : ["CARTETHYIA_ENCRYPTION_KEY"];
-
-  for (const key of required) {
-    const value = envVars[key] ?? process.env[key];
-    if (!value) {
-      missing.push(key);
-      console.log(`  ✗ ${key} is not set`);
-    } else if (hasPlaceholderSecrets(value)) {
-      console.log(`  ⚠️  ${key} has placeholder value — update before production`);
-    } else {
-      console.log(`  ✓ ${key} is set`);
-    }
-  }
-
-  if (missing.length > 0) {
-    console.log(
-      `\nFailed: ${missing.length} required environment variable(s) missing or using placeholders\n`,
-    );
-    process.exit(1);
-  }
-
-  console.log();
-
-  // Step 3: Check database. Full mode probes the TCP service; lite verifies
-  // the data dir is writable (the SQLite backend creates the file at boot too).
-  if (dbMode === "lite") {
-    const dataDir = resolveDataDir({ ...process.env, ...envVars });
-    try {
-      mkdirSync(dataDir, { recursive: true });
-      accessSync(dataDir, constants.W_OK);
-      console.log(`  ✓ Lite data dir is writable (${dataDir})`);
-    } catch {
-      console.log(`  ✗ Lite data dir is not writable (${dataDir})`);
-      process.exit(1);
-    }
-  } else {
-    const dbUrl = envVars.DATABASE_URL ?? process.env.DATABASE_URL;
-    const dbParsed = parseServiceUrl(dbUrl ?? "");
-
-    if (!dbParsed) {
-      console.log("  ✗ Invalid DATABASE_URL format");
-      process.exit(1);
-    }
-
-    const dbResult = await probeTcpService(dbParsed.host, dbParsed.port, config.probeTimeoutMs);
-    if (dbResult.success) {
-      console.log(`  ✓ Reachable at ${dbParsed.host}:${dbParsed.port}`);
-    } else {
-      console.log(`  ✗ Not reachable at ${dbParsed.host}:${dbParsed.port}`);
-      console.log(`    Error: ${dbResult.error || "connection refused"}`);
-      for (const hint of getOsHints("postgres")) console.log(`    ${hint}`);
-      process.exit(1);
-    }
-  }
-
-  console.log();
-
-  // Step 4: Check Redis connectivity — informational only. A configured URL
-  // is probed; unset means the in-memory backend, which is always up.
-  console.log("🔴 Redis");
-  const redisUrl = envVars.REDIS_URL ?? process.env.REDIS_URL;
-  if (!redisUrl) {
-    console.log("  ✓ in-memory backend (REDIS_URL not set)");
-  } else {
-    const redisParsed = parseServiceUrl(redisUrl);
-    if (!redisParsed) {
-      console.log("  ✗ REDIS_URL is invalid");
-      process.exit(1);
-    }
-    const redisResult = await probeTcpService(
-      redisParsed.host,
-      redisParsed.port,
-      config.probeTimeoutMs,
-    );
-    if (redisResult.success) {
-      console.log(`  ✓ Reachable at ${redisParsed.host}:${redisParsed.port}`);
-    } else {
-      console.log(`  ✗ Not reachable at ${redisParsed.host}:${redisParsed.port}`);
-      console.log(`    Error: ${redisResult.error || "connection refused"}`);
-      for (const hint of getOsHints("redis")) console.log(`    ${hint}`);
-      process.exit(1);
-    }
-  }
-
-  console.log();
-
-  // Step 5: Check application readiness
-  console.log("🏥 Application Readiness");
-  // Use the same explicit PORT resolution as the application.
-  const port = Number(envVars.PORT ?? process.env.PORT ?? "12800");
-  console.log(`  Checking http://localhost:${port}/health/ready...`);
-
-  const readinessResult = await probeReadiness(port, config.probeTimeoutMs);
-  if (readinessResult.success) {
-    console.log(`  ✓ Application is ready`);
-  } else {
-    console.log(`  ✗ Application is not ready`);
-    console.log(`    Error: ${readinessResult.error || "connection refused"}`);
-    console.log("");
-    console.log("Make sure the application is running:");
-    console.log(`  bun run dev`);
-    process.exit(1);
-  }
-
-  console.log();
-  console.log("✅ All systems operational!");
-}
-
-doctor().catch((err) => {
-  console.error("❌ Health check failed:", err);
-  process.exit(1);
-});
+import { accessSync, constants, existsSync, mkdirSync } from "node:fs";
+import { ENV_PATH, hasPlaceholderSecrets, readEnvFile } from "../support/env";
+import { getLocalPlatform, getOsHints } from "../support/platform";
+import { parseServiceUrl, probeTcpService } from "../support/services";
+import type { ProbeResult } from "../support/services";
+import { resolveDataDir, resolveDbMode, type DbMode } from "../../../src/persistence/db-mode";
+
+interface DoctorConfig {
+  envPath: string;
+  probeTimeoutMs: number;
+}
+
+function loadConfig(): DoctorConfig {
+  return {
+    envPath: ENV_PATH,
+    probeTimeoutMs: 3000,
+  };
+}
+
+/**
+ * Operator escape hatch: clears the console login lockout bucket.
+ *
+ * The lockout is keyed by `<username>:<clientIp>` and lasts an hour, and there
+ * is no console surface to clear it — a locked-out operator has no way back in
+ * short of editing the database by hand. This is the documented reset.
+ *
+ * Usage:
+ *   bun run doctor --reset-lockout <username> <clientIp>
+ *   bun run doctor --reset-lockout --all
+ */
+async function resetLockout(args: readonly string[]): Promise<void> {
+  const all = args.includes("--all");
+  const positional = args.filter((arg) => !arg.startsWith("--"));
+  if (!all && positional.length < 2) {
+    console.error("Usage: bun run doctor --reset-lockout <username> <clientIp>");
+    console.error("       bun run doctor --reset-lockout --all");
+    process.exit(1);
+  }
+
+  const env = await readEnvFile(ENV_PATH);
+  const databaseUrl = env.DATABASE_URL ?? process.env.DATABASE_URL;
+  if (!databaseUrl) {
+    console.error("✗ DATABASE_URL is not set; cannot reach the lockout table.");
+    process.exit(1);
+  }
+  process.env.DATABASE_URL = databaseUrl;
+
+  const { getDb, closeDb } = await import("../../../src/persistence/boot");
+  const { consoleLockouts } = await import("../../../src/persistence/schema");
+  const { eq, or } = await import("drizzle-orm");
+
+  const db = getDb();
+  try {
+    if (all) {
+      const cleared = await db.delete(consoleLockouts).returning({ ip: consoleLockouts.ip });
+      console.log(`✓ Cleared ${cleared.length} lockout row(s).`);
+      return;
+    }
+    const username = positional[0]!.trim().toLowerCase();
+    const clientIp = positional[1]!;
+    // The bucket key is `<identifier>:<ip>`; match either exact spelling so
+    // an operator does not have to guess how the identifier was normalized.
+    const cleared = await db
+      .delete(consoleLockouts)
+      .where(or(eq(consoleLockouts.ip, `${username}:${clientIp}`), eq(consoleLockouts.ip, clientIp)))
+      .returning({ ip: consoleLockouts.ip });
+    if (cleared.length === 0) {
+      console.log(`• No lockout row for ${username}:${clientIp} (already clear).`);
+    } else {
+      console.log(`✓ Cleared lockout for ${cleared.map((row) => row.ip).join(", ")}.`);
+    }
+  } finally {
+    await closeDb();
+  }
+}
+
+
+async function probeReadiness(port: number, timeoutMs: number): Promise<ProbeResult> {
+  const controller = new AbortController();
+  const timeoutHandle = setTimeout(() => controller.abort(), timeoutMs);
+
+  try {
+    const response = await fetch(`http://localhost:${port}/health/ready`, {
+      signal: controller.signal,
+    });
+
+    clearTimeout(timeoutHandle);
+
+    if (response.ok) {
+      return { success: true };
+    }
+    return { success: false, error: `HTTP ${response.status}` };
+  } catch (err) {
+    clearTimeout(timeoutHandle);
+    return { success: false, error: String(err) };
+  }
+}
+
+/** Runs the health check and the lockout reset; the CLI and `bun run doctor` both call this. */
+export async function doctor(): Promise<void> {
+  const config = loadConfig();
+
+  const resetIndex = process.argv.indexOf("--reset-lockout");
+  if (resetIndex !== -1) {
+    await resetLockout(process.argv.slice(resetIndex + 1));
+    return;
+  }
+
+  console.log("🩺 Cartethyia Health Check\n");
+  console.log(`🖥️  Host platform: ${getLocalPlatform()}`);
+
+  // Step 1: Check .env exists
+  console.log("📋 Environment Configuration");
+  if (!existsSync(config.envPath)) {
+    console.log("  ✗ .env file not found");
+    console.log("  Run: bun setup\n");
+    process.exit(1);
+  }
+  console.log("  ✓ .env file exists");
+
+  // Step 2: Check required environment variables. DATABASE_URL is required in
+  // full mode only; lite keeps its database in the data dir. Redis is never
+  // required — unset means the in-memory backend.
+  const envVars = await readEnvFile(config.envPath);
+  // `CARTETHYIA_DB_MODE` has no default and throws when absent, which is the
+  // right answer at boot but the wrong one here: this command exists to report
+  // a broken environment readably, so the missing key joins the checklist
+  // instead of crashing before it prints.
+  const missing: string[] = [];
+  let dbMode: DbMode | null = null;
+  try {
+    dbMode = resolveDbMode({ ...process.env, ...envVars });
+  } catch {
+    console.log("  ✗ CARTETHYIA_DB_MODE is not set — run: bun setup");
+    // Counted as missing so this command exits non-zero. A boot would throw on
+    // the same key, so a green doctor here would be a false all-clear.
+    missing.push("CARTETHYIA_DB_MODE");
+  }
+  const required =
+    dbMode === "full"
+      ? ["DATABASE_URL", "CARTETHYIA_ENCRYPTION_KEY"]
+      : ["CARTETHYIA_ENCRYPTION_KEY"];
+
+  for (const key of required) {
+    const value = envVars[key] ?? process.env[key];
+    if (!value) {
+      missing.push(key);
+      console.log(`  ✗ ${key} is not set`);
+    } else if (hasPlaceholderSecrets(value)) {
+      console.log(`  ⚠️  ${key} has placeholder value — update before production`);
+    } else {
+      console.log(`  ✓ ${key} is set`);
+    }
+  }
+
+  if (missing.length > 0) {
+    console.log(
+      `\nFailed: ${missing.length} required environment variable(s) missing or using placeholders\n`,
+    );
+    process.exit(1);
+  }
+
+  console.log();
+
+  // Step 3: Check database. Full mode probes the TCP service; lite verifies
+  // the data dir is writable (the SQLite backend creates the file at boot too).
+  if (dbMode === "lite") {
+    const dataDir = resolveDataDir({ ...process.env, ...envVars });
+    try {
+      mkdirSync(dataDir, { recursive: true });
+      accessSync(dataDir, constants.W_OK);
+      console.log(`  ✓ Lite data dir is writable (${dataDir})`);
+    } catch {
+      console.log(`  ✗ Lite data dir is not writable (${dataDir})`);
+      process.exit(1);
+    }
+  } else {
+    const dbUrl = envVars.DATABASE_URL ?? process.env.DATABASE_URL;
+    const dbParsed = parseServiceUrl(dbUrl ?? "");
+
+    if (!dbParsed) {
+      console.log("  ✗ Invalid DATABASE_URL format");
+      process.exit(1);
+    }
+
+    const dbResult = await probeTcpService(dbParsed.host, dbParsed.port, config.probeTimeoutMs);
+    if (dbResult.success) {
+      console.log(`  ✓ Reachable at ${dbParsed.host}:${dbParsed.port}`);
+    } else {
+      console.log(`  ✗ Not reachable at ${dbParsed.host}:${dbParsed.port}`);
+      console.log(`    Error: ${dbResult.error || "connection refused"}`);
+      for (const hint of getOsHints("postgres")) console.log(`    ${hint}`);
+      process.exit(1);
+    }
+  }
+
+  console.log();
+
+  // Step 4: Check Redis connectivity — informational only. A configured URL
+  // is probed; unset means the in-memory backend, which is always up.
+  console.log("🔴 Redis");
+  const redisUrl = envVars.REDIS_URL ?? process.env.REDIS_URL;
+  if (!redisUrl) {
+    console.log("  ✓ in-memory backend (REDIS_URL not set)");
+  } else {
+    const redisParsed = parseServiceUrl(redisUrl);
+    if (!redisParsed) {
+      console.log("  ✗ REDIS_URL is invalid");
+      process.exit(1);
+    }
+    const redisResult = await probeTcpService(
+      redisParsed.host,
+      redisParsed.port,
+      config.probeTimeoutMs,
+    );
+    if (redisResult.success) {
+      console.log(`  ✓ Reachable at ${redisParsed.host}:${redisParsed.port}`);
+    } else {
+      console.log(`  ✗ Not reachable at ${redisParsed.host}:${redisParsed.port}`);
+      console.log(`    Error: ${redisResult.error || "connection refused"}`);
+      for (const hint of getOsHints("redis")) console.log(`    ${hint}`);
+      process.exit(1);
+    }
+  }
+
+  console.log();
+
+  // Step 5: Check application readiness
+  console.log("🏥 Application Readiness");
+  // Use the same explicit PORT resolution as the application.
+  const port = Number(envVars.PORT ?? process.env.PORT ?? "12800");
+  console.log(`  Checking http://localhost:${port}/health/ready...`);
+
+  const readinessResult = await probeReadiness(port, config.probeTimeoutMs);
+  if (readinessResult.success) {
+    console.log(`  ✓ Application is ready`);
+  } else {
+    console.log(`  ✗ Application is not ready`);
+    console.log(`    Error: ${readinessResult.error || "connection refused"}`);
+    console.log("");
+    console.log("Make sure the application is running:");
+    console.log(`  bun run dev`);
+    process.exit(1);
+  }
+
+  console.log();
+  console.log("✅ All systems operational!");
+}
+
+// `bun run doctor` still works: the module is a script when run directly and a
+// command when imported by the CLI.
+if (import.meta.main) {
+  doctor().catch((err) => {
+    console.error("❌ Health check failed:", err);
+    process.exit(1);
+  });
+}

package/scripts/cli/{setup.ts → command/setup.ts}

@@ -4,23 +4,19 @@ import { existsSync, mkdirSync } from "node:fs";
 import { readFile, writeFile } from "node:fs/promises";
 import { dirname, resolve } from "node:path";
 import { createServer } from "node:net";
+import { MINIMUM_BUN_VERSION, bunVersionAtLeast } from "../support/bun";
 import {
-  MINIMUM_BUN_VERSION,
-  bunVersionAtLeast,
-  detectLocalPostgres,
+  ENV_PATH,
+  PROJECT_ROOT,
   generateCartethyiaEncryptionKey,
-  getLocalPlatform,
-  getOsHints,
   hasPlaceholderSecrets,
   mandatoryEnvBody,
-  parseServiceUrl,
-  probeTcpService,
   readEnvFile,
-  ENV_PATH,
-  PROJECT_ROOT,
-} from "../shared/env";
-import type { ProbeResult } from "../shared/env";
-import { resolveDataDir, resolveDbMode } from "../../src/persistence/db-mode";
+} from "../support/env";
+import { getLocalPlatform, getOsHints } from "../support/platform";
+import { detectLocalPostgres, parseServiceUrl, probeTcpService } from "../support/services";
+import type { ProbeResult } from "../support/services";
+import { resolveDataDir, resolveDbMode } from "../../../src/persistence/db-mode";
 
 async function ask(question: string, defaultValue = ""): Promise<string> {
   const rl = createInterface({ input, output });

package/scripts/cli/command/start.ts

@@ -0,0 +1,77 @@
+import { resolvePort } from "../../../src/config/runtime";
+import { ensureDrainToken } from "../gateway/drain-token";
+import { clearInstanceLock, pidAlive, readInstanceLock, writeInstanceLock } from "../gateway/instance-lock";
+
+/**
+ * Runs the gateway in the foreground, in this process.
+ *
+ * A foreground run still needs a drain token on disk: the gateway registers
+ * `/admin/drain` only when one is set, and "Hide to tray" hands this run to a
+ * tray that drains it through that route.
+ *
+ * Unlike the menu and tray paths this one does not spawn a child, so the
+ * port-busy check has to happen here too — otherwise a stale gateway makes a
+ * plain `cartethyia start` fail from inside `src/main` with a message that says
+ * nothing about what to do.
+ */
+export async function startForeground(): Promise<void> {
+  const token = ensureDrainToken();
+  process.env.CARTETHYIA_DRAIN_TOKEN ??= token;
+  const port = resolvePort();
+  const blocker = await inspectPortHolder(port, token);
+  if (blocker !== null) throw new Error(blocker);
+  writeInstanceLock(port, process.pid, token);
+  await import("../../../src/main");
+}
+
+/**
+ * What to tell the operator when the port is already taken, or `null` when the
+ * port is free (or was freed).
+ *
+ * Same rule as the spawned path: only ever stop a gateway that proves it is
+ * this install's own. A drain request is token-gated, so a 401 means another
+ * Cartethyia install and anything else is not a gateway at all — neither may be
+ * touched, and both are reported instead.
+ */
+async function inspectPortHolder(port: number, token: string): Promise<string | null> {
+  const up = await fetch(`http://127.0.0.1:${port}/health`, {
+    signal: AbortSignal.timeout(1_000),
+  }).catch(() => null);
+  if (up === null) {
+    // Port is free. Drop a stale marker from a crashed run so the next start
+    // does not read a dead pid as a live gateway.
+    const lock = readInstanceLock();
+    if (lock !== null && lock.port === port && !pidAlive(lock.pid)) clearInstanceLock();
+    return null;
+  }
+  const response = await fetch(`http://127.0.0.1:${port}/admin/drain`, {
+    method: "POST",
+    headers: { "x-drain-token": token },
+    signal: AbortSignal.timeout(3_000),
+  }).catch(() => null);
+  if (response === null) {
+    return `Port ${port} is busy and nothing there answers a drain request. Stop whatever holds it, or set a different PORT.`;
+  }
+  if (response.status === 401) {
+    return `Another Cartethyia gateway is already running on port ${port} under a different install. Stop it from its own terminal or tray — this install will not stop a gateway it does not own.`;
+  }
+  if (response.status === 403) {
+    return `Port ${port} refused a drain from loopback. Stop what holds it, then start again.`;
+  }
+  if (response.status !== 202) {
+    return `Port ${port} is busy and refused to drain (HTTP ${response.status}). Stop it manually, then start again.`;
+  }
+  // Drain accepted; wait for the port to actually close.
+  const deadline = Date.now() + 30_000;
+  while (Date.now() < deadline) {
+    const stillUp = await fetch(`http://127.0.0.1:${port}/health`, {
+      signal: AbortSignal.timeout(500),
+    }).catch(() => null);
+    if (stillUp === null) {
+      clearInstanceLock();
+      return null;
+    }
+    await Bun.sleep(200);
+  }
+  return `The gateway on port ${port} accepted a drain but did not release the port within 30 seconds. Stop it manually, then start again.`;
+}