cartethyia 2.5.4 → 2.5.7

package/scripts/cli/command/admin.ts

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

package/scripts/cli/command/doctor.ts

@@ -1,257 +0,0 @@
-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/gateway/drain-token.ts

@@ -1,78 +0,0 @@
-import { existsSync, readFileSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
-
-/**
- * The install's drain token, persisted in the config directory.
- *
- * Why it persists instead of being generated per run: the tray that "Hide to
- * tray" starts runs in a different process and drains the gateway through the
- * loopback endpoint, so the token has to match across processes. A token
- * regenerated on each start could never authenticate against a gateway another
- * process had started.
- *
- * It is kept out of `.env` on purpose: it authorises a shutdown, so it belongs
- * in a machine-written file the operator never hand-edits and never commits.
- * Mode 0600 where the platform honours it.
- */
-const RUNTIME_STATE_FILE = "runtime.json";
-
-interface RuntimeState {
-  readonly drainToken: string;
-}
-
-function statePath(): string | null {
-  const configDir = process.env.CARTETHYIA_CONFIG_DIR;
-  return configDir ? join(configDir, RUNTIME_STATE_FILE) : null;
-}
-
-function readState(): RuntimeState | null {
-  const path = statePath();
-  if (path === null || !existsSync(path)) return null;
-  try {
-    const parsed: unknown = JSON.parse(readFileSync(path, "utf8"));
-    if (
-      parsed !== null &&
-      typeof parsed === "object" &&
-      "drainToken" in parsed &&
-      typeof parsed.drainToken === "string" &&
-      parsed.drainToken.length > 0
-    ) {
-      return { drainToken: parsed.drainToken };
-    }
-  } catch {
-    // A corrupt or stale state file reads as "no token".
-  }
-  return null;
-}
-
-/**
- * Returns the install's drain token, creating and persisting one on first use.
- *
- * Every start calls this, so a gateway started from the menu, from `tray`, or
- * from `cartethyia start` all authenticate with the same token and `stop`
- * always has the one that works.
- */
-export function ensureDrainToken(): string {
-  const existing = readState();
-  if (existing !== null) return existing.drainToken;
-
-  const token = crypto.randomUUID().replace(/-/g, "") + crypto.randomUUID().replace(/-/g, "");
-  const path = statePath();
-  if (path !== null) {
-    try {
-      writeFileSync(path, JSON.stringify({ drainToken: token }), {
-        encoding: "utf8",
-        mode: 0o600,
-      });
-    } catch {
-      // A read-only config directory still yields a usable in-process token;
-      // only `stop` from another process is lost.
-    }
-  }
-  return token;
-}
-
-/** The persisted token, or null when this install has never started. */
-export function readPersistedDrainToken(): string | null {
-  return readState()?.drainToken ?? null;
-}

package/scripts/cli/gateway/instance-lock.ts

@@ -1,105 +0,0 @@
-import { existsSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
-
-/**
- * A marker that one gateway owns this install's port.
- *
- * The port probe alone cannot tell a healthy gateway from a stranger's process:
- * something answering on 12800 is not necessarily ours, so a start that found
- * the port busy either failed outright or — worse — would have to guess before
- * stopping anything. The lock names the PID and the token it was written with,
- * which is what makes "is this our gateway?" answerable without guessing.
- *
- * It is advisory, not an OS lock: a stale file from a crashed process is the
- * normal case this exists to recover from, so presence alone never blocks a
- * start. Liveness is decided by probing the port, and identity by the token.
- */
-export interface InstanceLock {
-  readonly pid: number;
-  readonly port: number;
-  /** Fingerprint of the drain token, never the token itself. */
-  readonly tokenFingerprint: string;
-  readonly startedAt: string;
-}
-
-const LOCK_FILE = "instance.json";
-
-function lockPath(): string | null {
-  const configDir = process.env.CARTETHYIA_CONFIG_DIR;
-  return configDir ? join(configDir, LOCK_FILE) : null;
-}
-
-/** A short, non-reversible fingerprint so the token itself is never written. */
-export function fingerprint(token: string): string {
-  let hash = 0;
-  for (let i = 0; i < token.length; i += 1) {
-    hash = (hash * 31 + token.charCodeAt(i)) | 0;
-  }
-  return (hash >>> 0).toString(16).padStart(8, "0");
-}
-
-export function writeInstanceLock(port: number, pid: number, token: string): void {
-  const path = lockPath();
-  if (path === null) return;
-  const lock: InstanceLock = {
-    pid,
-    port,
-    tokenFingerprint: fingerprint(token),
-    startedAt: new Date().toISOString(),
-  };
-  try {
-    writeFileSync(path, JSON.stringify(lock), { encoding: "utf8", mode: 0o600 });
-  } catch {
-    // A read-only config directory costs the marker, not the run.
-  }
-}
-
-export function readInstanceLock(): InstanceLock | null {
-  const path = lockPath();
-  if (path === null || !existsSync(path)) return null;
-  try {
-    const parsed: unknown = JSON.parse(readFileSync(path, "utf8"));
-    if (
-      parsed !== null &&
-      typeof parsed === "object" &&
-      "pid" in parsed &&
-      typeof parsed.pid === "number" &&
-      "port" in parsed &&
-      typeof parsed.port === "number" &&
-      "tokenFingerprint" in parsed &&
-      typeof parsed.tokenFingerprint === "string"
-    ) {
-      const startedAt = "startedAt" in parsed && typeof parsed.startedAt === "string" ? parsed.startedAt : "";
-      return {
-        pid: parsed.pid,
-        port: parsed.port,
-        tokenFingerprint: parsed.tokenFingerprint,
-        startedAt,
-      };
-    }
-  } catch {
-    // A corrupt marker reads as none.
-  }
-  return null;
-}
-
-export function clearInstanceLock(): void {
-  const path = lockPath();
-  if (path === null) return;
-  try {
-    unlinkSync(path);
-  } catch {
-    // Already gone, or the directory is read-only.
-  }
-}
-
-/** Whether a process id is alive. `0` is never a real pid. */
-export function pidAlive(pid: number): boolean {
-  if (!Number.isInteger(pid) || pid <= 0) return false;
-  try {
-    process.kill(pid, 0);
-    return true;
-  } catch {
-    return false;
-  }
-}

package/scripts/cli/gateway/stop.ts

@@ -1,51 +0,0 @@
-/**
- * Stops a gateway this process started, gracefully where possible.
- *
- * The drain endpoint is the only graceful path: it lets in-flight responses
- * finish. The OS-level kill is the fallback, and it is reached whenever the
- * endpoint is unreachable — which is also what happens when the gateway is
- * already on its way out, so a failure here is not necessarily an error the
- * operator needs to act on.
- */
-export async function stopGateway(
-  current: Bun.Subprocess,
-  port: number,
-  drainToken: string,
-): Promise<void> {
-  let drainAccepted = false;
-  try {
-    const response = await fetch(`http://127.0.0.1:${port}/admin/drain`, {
-      method: "POST",
-      headers: { "x-drain-token": drainToken },
-      signal: AbortSignal.timeout(2_000),
-    });
-    drainAccepted = response.status === 202;
-  } catch {
-    // The process may already be exiting; fall back to its OS-level termination.
-  }
-  if (!drainAccepted) {
-    console.error("Could not request a graceful gateway drain; terminating the gateway process.");
-    current.kill();
-    await current.exited;
-    return;
-  }
-
-  // The drain is bounded: a gateway that accepted the request but never exits
-  // would otherwise hang the CLI. 30 s is the drain budget `src/main.ts` uses.
-  // The timer is cleared unconditionally afterwards — leaving it pending keeps
-  // the event loop alive for its full 30 s after the gateway is already gone,
-  // which made every `carte` exit take half a minute.
-  let timer: Timer | undefined;
-  const drained = await Promise.race([
-    current.exited,
-    new Promise<null>((resolveExit) => {
-      timer = setTimeout(() => resolveExit(null), 30_000);
-    }),
-  ]);
-  clearTimeout(timer);
-  if (drained === null) {
-    console.error("Graceful drain timed out; terminating the gateway process.");
-    current.kill();
-    await current.exited;
-  }
-}

package/scripts/cli/support/bun.ts

@@ -1,27 +0,0 @@
-/** Minimum Bun the repository declares in `package.json` `engines`. */
-export const MINIMUM_BUN_VERSION = "1.4.0";
-
-/**
- * True when `actual` is at least `minimum`, compared as dotted integers.
- * A non-numeric segment reads as 0, so a malformed version fails closed
- * against a real minimum instead of passing.
- */
-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;
-}
-
-/** Throws unless the running Bun satisfies the declared minimum. */
-export function assertBunVersion(): void {
-  if (bunVersionAtLeast(Bun.version, MINIMUM_BUN_VERSION)) return;
-  throw new Error(
-    `Bun ${MINIMUM_BUN_VERSION} or newer is required (found ${Bun.version}). Install it from https://bun.sh and run this command again.`,
-  );
-}

package/scripts/cli/support/version.ts

@@ -1,37 +0,0 @@
-import { resolvePackagePath } from "../../../src/config/package-paths";
-
-/** 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;
-  }
-}