cartethyia 2.5.4 → 2.5.6

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

@@ -1,99 +1,99 @@
-import { existsSync } from "node:fs";
-import { readFile } from "node:fs/promises";
-import { resolve } from "node:path";
-import { PACKAGE_ROOT } from "../../../src/config/package-paths";
-
-/**
- * Absolute path of the repository root.
- *
- * Operational scripts and the npm runtime share one package-root resolver so
- * assets and repository config do not depend on the caller's working directory.
- */
-export const PROJECT_ROOT = PACKAGE_ROOT;
-
-/** Resolve the active `.env`; npm CLI sets a user-owned config directory. */
-export function resolveEnvPath(env: NodeJS.ProcessEnv = process.env): string {
-  const configDir = env.CARTETHYIA_CONFIG_DIR?.trim();
-  return configDir ? resolve(configDir, ".env") : resolve(PROJECT_ROOT, ".env");
-}
-
-/** Absolute path of the active `.env`. */
-export const ENV_PATH = resolveEnvPath();
-
-/**
- * Reads a dotenv-style file without overriding already-exported variables.
- */
-export async function readEnvFile(path: string): Promise<Record<string, string>> {
-  if (!existsSync(path)) return {};
-  const content = await readFile(path, "utf8");
-  const values: Record<string, string> = {};
-  for (const line of content.split(/\r?\n/)) {
-    if (line.startsWith("#")) continue;
-    const separator = line.indexOf("=");
-    if (separator <= 0) continue;
-    const key = line.slice(0, separator).trim();
-    const value = line.slice(separator + 1).trim();
-    if (key) values[key] = value;
-  }
-  return values;
-}
-
-/**
- * Checks if a string contains a configured placeholder value.
- */
-export function hasPlaceholderSecrets(value: string): boolean {
-  const normalized = value.toLowerCase();
-  return (
-    normalized.includes("replace-with") ||
-    normalized.includes("replace_me") ||
-    normalized.includes("your_")
-  );
-}
-
-/**
- * Generates a 256-bit hex cartethyia encryption key.
- *
- * Hex is preferred over base64 because it never carries padding or `+`/`/`
- * characters that confuse some dotenv shells, and it round-trips through
- * every adapter that accepts either encoding. The install/setup helpers call
- * this when the key is absent or still a placeholder.
- */
-export function generateCartethyiaEncryptionKey(): string {
-  const bytes = new Uint8Array(32);
-  crypto.getRandomValues(bytes);
-  let hex = "";
-  for (let i = 0; i < bytes.length; i += 1) hex += bytes[i]!.toString(16).padStart(2, "0");
-  return hex;
-}
-
-/**
- * Returns the mandatory-only `.env` body derived from `.env.example`.
- *
- * Mandatory means the key is assigned without a leading `#`. Optional entries
- * (leading `#`) carry built-in defaults and must not be copied into a fresh
- * `.env` — they would override the default with a literal `example` value.
- * The generated body therefore contains only mandatory rows, plus a single
- * `CARTETHYIA_ENCRYPTION_KEY` replacement when the caller supplies one.
- */
-export async function mandatoryEnvBody(
-  examplePath: string,
-  overrides: Readonly<Record<string, string>> = {},
-): Promise<string> {
-  const raw = await readFile(examplePath, "utf8");
-  const lines: string[] = [];
-  for (const line of raw.split(/\r?\n/)) {
-    const trimmed = line.trim();
-    if (trimmed === "" || trimmed.startsWith("#")) continue;
-    const sep = line.indexOf("=");
-    if (sep <= 0) continue;
-    const key = line.slice(0, sep).trim();
-    if (!key) continue;
-    const value = (overrides as Record<string, string>)[key] ?? line.slice(sep + 1).trim();
-    lines.push(`${key}=${value}`);
-  }
-  // Preserve overrides even when the example row was commented out (legacy case).
-  for (const [key, value] of Object.entries(overrides)) {
-    if (!lines.some((l) => l.startsWith(`${key}=`))) lines.push(`${key}=${value}`);
-  }
-  return `${lines.join("\n")}\n`;
-}
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { PACKAGE_ROOT } from "../../src/config/package-paths";
+
+/**
+ * Absolute path of the repository root.
+ *
+ * Operational scripts and the npm runtime share one package-root resolver so
+ * assets and repository config do not depend on the caller's working directory.
+ */
+export const PROJECT_ROOT = PACKAGE_ROOT;
+
+/** Resolve the active `.env`; npm CLI sets a user-owned config directory. */
+export function resolveEnvPath(env: NodeJS.ProcessEnv = process.env): string {
+  const configDir = env.CARTETHYIA_CONFIG_DIR?.trim();
+  return configDir ? resolve(configDir, ".env") : resolve(PROJECT_ROOT, ".env");
+}
+
+/** Absolute path of the active `.env`. */
+export const ENV_PATH = resolveEnvPath();
+
+/**
+ * Reads a dotenv-style file without overriding already-exported variables.
+ */
+export async function readEnvFile(path: string): Promise<Record<string, string>> {
+  if (!existsSync(path)) return {};
+  const content = await readFile(path, "utf8");
+  const values: Record<string, string> = {};
+  for (const line of content.split(/\r?\n/)) {
+    if (line.startsWith("#")) continue;
+    const separator = line.indexOf("=");
+    if (separator <= 0) continue;
+    const key = line.slice(0, separator).trim();
+    const value = line.slice(separator + 1).trim();
+    if (key) values[key] = value;
+  }
+  return values;
+}
+
+/**
+ * Checks if a string contains a configured placeholder value.
+ */
+export function hasPlaceholderSecrets(value: string): boolean {
+  const normalized = value.toLowerCase();
+  return (
+    normalized.includes("replace-with") ||
+    normalized.includes("replace_me") ||
+    normalized.includes("your_")
+  );
+}
+
+/**
+ * Generates a 256-bit hex cartethyia encryption key.
+ *
+ * Hex is preferred over base64 because it never carries padding or `+`/`/`
+ * characters that confuse some dotenv shells, and it round-trips through
+ * every adapter that accepts either encoding. The install/setup helpers call
+ * this when the key is absent or still a placeholder.
+ */
+export function generateCartethyiaEncryptionKey(): string {
+  const bytes = new Uint8Array(32);
+  crypto.getRandomValues(bytes);
+  let hex = "";
+  for (let i = 0; i < bytes.length; i += 1) hex += bytes[i]!.toString(16).padStart(2, "0");
+  return hex;
+}
+
+/**
+ * Returns the mandatory-only `.env` body derived from `.env.example`.
+ *
+ * Mandatory means the key is assigned without a leading `#`. Optional entries
+ * (leading `#`) carry built-in defaults and must not be copied into a fresh
+ * `.env` — they would override the default with a literal `example` value.
+ * The generated body therefore contains only mandatory rows, plus a single
+ * `CARTETHYIA_ENCRYPTION_KEY` replacement when the caller supplies one.
+ */
+export async function mandatoryEnvBody(
+  examplePath: string,
+  overrides: Readonly<Record<string, string>> = {},
+): Promise<string> {
+  const raw = await readFile(examplePath, "utf8");
+  const lines: string[] = [];
+  for (const line of raw.split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (trimmed === "" || trimmed.startsWith("#")) continue;
+    const sep = line.indexOf("=");
+    if (sep <= 0) continue;
+    const key = line.slice(0, sep).trim();
+    if (!key) continue;
+    const value = (overrides as Record<string, string>)[key] ?? line.slice(sep + 1).trim();
+    lines.push(`${key}=${value}`);
+  }
+  // Preserve overrides even when the example row was commented out (legacy case).
+  for (const [key, value] of Object.entries(overrides)) {
+    if (!lines.some((l) => l.startsWith(`${key}=`))) lines.push(`${key}=${value}`);
+  }
+  return `${lines.join("\n")}\n`;
+}

package/scripts/cli/{gateway/spawn.ts → gateway.ts}

@@ -1,13 +1,44 @@
-import { openSync } from "node:fs";
+import { openSync, statSync } from "node:fs";
 import {
   clearInstanceLock,
   fingerprint,
   pidAlive,
   readInstanceLock,
   writeInstanceLock,
-} from "./instance-lock";
+} from "./instance";
 import { join } from "node:path";
-import { PACKAGE_ROOT, resolvePackagePath } from "../../../src/config/package-paths";
+import { PACKAGE_ROOT, resolvePackagePath } from "../../src/config/package-paths";
+import { compiledBinaryPath } from "../build/compile";
+import { spawn as spawnDetached, type ChildProcess } from "node:child_process";
+import {
+  blockedPortMessage,
+  gatewayLogPath,
+  listenPortErrorMessage,
+  probeListenPort,
+  startupFailureMessage,
+} from "./port";
+
+function detachedSubprocess(executable: readonly string[], cwd: string, env: NodeJS.ProcessEnv, logFd: number | null): Bun.Subprocess {
+  const child: ChildProcess = spawnDetached(executable[0]!, [...executable.slice(1)], {
+    cwd,
+    env,
+    detached: true,
+    windowsHide: true,
+    stdio: ["ignore", logFd ?? "ignore", logFd ?? "ignore"],
+  });
+  child.unref();
+  const exited = new Promise<number>((resolve) => {
+    child.once("exit", (code) => resolve(code ?? 1));
+  });
+  return {
+    pid: child.pid!,
+    exited,
+    exitCode: null,
+    signalCode: null,
+    kill: () => child.kill(),
+    unref: () => child.unref(),
+  } as unknown as Bun.Subprocess;
+}
 
 /**
  * Frees the port when what holds it is this install's own gateway.
@@ -82,19 +113,25 @@ export async function startGateway(
   drainToken: string,
   options: { readonly detached?: boolean } = {},
 ): Promise<Bun.Subprocess> {
-  // Starting a second gateway on the same port used to fail with "stopped
-  // before becoming ready (exit code 1)", which says nothing about the real
-  // cause. Probe the port first and say what is actually there.
-  const existing = await fetch(`http://127.0.0.1:${port}/health`, {
-    signal: AbortSignal.timeout(1_000),
-  }).catch(() => null);
-  if (existing !== null) {
-    // Something already owns the port. Replace it only when it proves to be our
-    // own gateway — otherwise stop and say what is there. A gateway left behind
-    // by a closed terminal used to make every later start fail until the
-    // operator found and killed it by hand.
-    const claimed = await claimPort(port, drainToken);
-    if (claimed !== null) throw new Error(claimed);
+  // A dead marker from the previous process must not turn its now-reused port
+  // into an ownership claim. Only identity + drain authorization may stop one.
+  const lock = readInstanceLock();
+  if (lock && !pidAlive(lock.pid)) clearInstanceLock();
+  const probe = await probeListenPort(port);
+  if (probe.status === "blocked") {
+    if (probe.code === "EADDRINUSE") {
+      const claimed = await claimPort(port, drainToken);
+      if (claimed !== null) {
+        if (claimed.startsWith("Port") && claimed.includes("nothing there answers")) {
+          throw new Error(blockedPortMessage(port));
+        }
+        throw new Error(claimed);
+      }
+      const released = await probeListenPort(port);
+      if (released.status === "blocked") throw new Error(blockedPortMessage(port));
+    } else {
+      throw new Error(listenPortErrorMessage(port, probe));
+    }
   }
   // The gateway logs a startup phase line per stage. In menu mode those lines
   // would scroll through the same terminal the menu is drawing on, so they go
@@ -108,9 +145,22 @@ export async function startGateway(
       // A read-only config directory costs only the log, not startup.
     }
   }
-  const child = Bun.spawn(
-    [process.execPath, "run", resolvePackagePath("src", "main.ts")],
-    {
+  const logPath = gatewayLogPath(configDir);
+  let logOffset = 0;
+  if (logPath) {
+    try { logOffset = statSync(logPath).size; } catch { logOffset = 0; }
+  }
+  const configuredBinary = process.env.CARTETHYIA_GATEWAY_BINARY?.trim();
+  const defaultBinary = resolvePackagePath(compiledBinaryPath());
+  const binary = configuredBinary || defaultBinary;
+  const executable = await Bun.file(binary).exists()
+    ? [binary]
+    : configuredBinary
+      ? (() => { throw new Error(`Configured gateway binary does not exist: ${configuredBinary}`); })()
+      : [process.execPath, "run", resolvePackagePath("src", "main.ts")];
+  const child = options.detached
+    ? detachedSubprocess(executable, PACKAGE_ROOT, { ...process.env, CARTETHYIA_DRAIN_TOKEN: drainToken }, logFd)
+    : Bun.spawn(executable, {
       cwd: PACKAGE_ROOT,
       env: { ...process.env, CARTETHYIA_DRAIN_TOKEN: drainToken },
       // "ignore", not "inherit": the gateway does not read stdin, and in menu
@@ -123,9 +173,8 @@ export async function startGateway(
       // terminal, so closing that terminal took the gateway down with it and
       // "Hide to tray" left nothing running.
       stderr: logFd ?? "ignore",
-      detached: options.detached === true,
-    },
-  );
+      detached: false,
+    });
   const startupController = new AbortController();
   const ready = (async (): Promise<void> => {
     const deadline = Date.now() + 30_000;
@@ -157,13 +206,14 @@ export async function startGateway(
   try {
     const result = await Promise.race([readyResult, exitedEarly]);
     if (result.status === "exit") {
-      throw new Error(`Cartethyia stopped before becoming ready (exit code ${result.code})`);
+      throw new Error(startupFailureMessage(port, result.code, logPath, logOffset));
     }
     if (result.status === "failure") throw result.error;
     // Recorded only once the child is actually serving: a marker written before
     // readiness would name a gateway that never came up, and the next start
     // would treat a live port as ours when it is not.
-    writeInstanceLock(port, child.pid, drainToken);
+    writeInstanceLock(port, child.pid, drainToken, executable[0]!);
+    if (options.detached) child.unref();
     return child;
   } catch (error) {
     child.kill();
@@ -171,3 +221,41 @@ export async function startGateway(
     throw error;
   }
 }
+
+/** Stops a child gateway, draining in-flight responses before termination. */
+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.
+  }
+  if (!drainAccepted) {
+    console.error("Could not request a graceful gateway drain; terminating the gateway process.");
+    current.kill();
+    await current.exited;
+    return;
+  }
+  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/instance.ts

@@ -0,0 +1,224 @@
+import { existsSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+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 {
+    // Corrupt state reads as no token and is replaced on next start.
+  }
+  return null;
+}
+
+/** Returns the install's persistent drain token, creating it on first use. */
+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 only loses stop-from-another-process.
+    }
+  }
+  return token;
+}
+
+export function readPersistedDrainToken(): string | null {
+  return readState()?.drainToken ?? null;
+}
+
+/**
+ * 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;
+  readonly executable: 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, executable = ""): void {
+  const path = lockPath();
+  if (path === null) return;
+  const lock: InstanceLock = {
+    pid,
+    port,
+    tokenFingerprint: fingerprint(token),
+    startedAt: new Date().toISOString(),
+    executable,
+  };
+  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,
+        executable: "executable" in parsed && typeof parsed.executable === "string" ? parsed.executable : "",
+      };
+    }
+  } 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;
+  }
+}
+
+export interface RunningGateway { pid: number; port: number; executable: string; }
+
+interface InstanceDependencies {
+  alive: (pid: number) => boolean;
+  fetch: (input: string, init?: RequestInit) => Promise<Response>;
+  kill: (pid: number) => void;
+  sleep: (ms: number) => Promise<void>;
+}
+const instanceDependencies: InstanceDependencies = {
+  alive: pidAlive,
+  fetch: (input, init) => fetch(input, init),
+  kill: (pid) => process.kill(pid, "SIGTERM"),
+  sleep: Bun.sleep,
+};
+
+export async function findRunningGateway(port: number, token: string): Promise<RunningGateway | null> {
+  const lock = readInstanceLock();
+  if (lock === null || lock.port !== port || lock.tokenFingerprint !== fingerprint(token)) return null;
+  if (!instanceDependencies.alive(lock.pid)) {
+    clearInstanceLock();
+    return null;
+  }
+  try {
+    const response = await instanceDependencies.fetch(`http://127.0.0.1:${port}/health`, { signal: AbortSignal.timeout(1_000) });
+    if (!response.ok) return null;
+    return { pid: lock.pid, port, executable: lock.executable };
+  } catch {
+    return null;
+  }
+}
+
+export async function attachGateway(port: number, token: string): Promise<RunningGateway | null> {
+  return findRunningGateway(port, token);
+}
+
+export async function stopAttachedGateway(instance: RunningGateway, token: string): Promise<void> {
+  const lock = readInstanceLock();
+  if (lock === null || lock.pid !== instance.pid || lock.port !== instance.port || lock.tokenFingerprint !== fingerprint(token)) {
+    throw new Error("The gateway is not owned by this installation; refusing to stop it.");
+  }
+  if (!instanceDependencies.alive(instance.pid)) {
+    clearInstanceLock();
+    return;
+  }
+  let accepted = false;
+  try {
+    const response = await instanceDependencies.fetch(`http://127.0.0.1:${instance.port}/admin/drain`, {
+      method: "POST",
+      headers: { "x-drain-token": token },
+      signal: AbortSignal.timeout(2_000),
+    });
+    accepted = response.status === 202;
+    if (!accepted) throw new Error(`Gateway drain was refused (HTTP ${response.status}); process left untouched.`);
+  } catch (error) {
+    if (error instanceof Error && error.message.includes("process left untouched")) throw error;
+  }
+  if (!accepted) instanceDependencies.kill(instance.pid);
+  const deadline = Date.now() + 30_000;
+  while (instanceDependencies.alive(instance.pid) && Date.now() < deadline) await instanceDependencies.sleep(200);
+  if (instanceDependencies.alive(instance.pid)) {
+    if (accepted) instanceDependencies.kill(instance.pid);
+    throw new Error("Gateway did not stop within the drain timeout");
+  }
+  clearInstanceLock();
+}
+
+export const instanceTestInternals = {
+  dependencies: instanceDependencies,
+};