cartethyia 2.5.10 → 2.6.0

package/scripts/cli/console-menu.ts

@@ -16,6 +16,9 @@ import { chooseFromMenu, confirmByTyping, confirmStep, type MenuRow } from "./pr
 import { renderWordmark } from "./wordmark";
 import { exportBackup, resetConsoleAccount } from "./admin";
 import { runDetachedUpdate } from "./update";
+import { acquireController } from "./controller";
+import { restoreControllerAfterFailedHandoff } from "./controller";
+import { attachGateway as attachRunningGateway } from "./instance";
 
 
 /**
@@ -25,6 +28,18 @@ import { runDetachedUpdate } from "./update";
  * and is never seen. `carte --tray` opts into the icon instead.
  */
 export async function startMenu(): Promise<void> {
+  const controller = acquireController("menu");
+  const releaseController = (): void => controller.release();
+  process.once("exit", releaseController);
+  try {
+    await runMenu(controller.handoff);
+  } finally {
+    controller.release();
+    process.removeListener("exit", releaseController);
+  }
+}
+
+async function runMenu(handoff: { readonly token: string; readonly parentPid: number }): Promise<void> {
   // A fresh install has no config file yet, and the gateway refuses to boot
   // without CARTETHYIA_DB_MODE — which surfaced as a stack trace about a
   // missing database mode rather than "you have not set this up". Run setup
@@ -136,6 +151,7 @@ export async function startMenu(): Promise<void> {
 
   let latestVersion = await readLatestPublishedVersion();
   let running = true;
+  let backupStatus: { readonly tone: "success" | "error"; readonly text: string } | undefined;
 
   while (running) {
     const upToDate = latestVersion === null || !isNewerRelease(currentVersion, latestVersion);
@@ -146,16 +162,15 @@ export async function startMenu(): Promise<void> {
     // action that matters.
     const versionCheckerLine =
       latestVersion === null
-        ? `Version Checker: ${currentVersion} \u00b7 could not reach the registry`
+        ? `${currentVersion} \u00b7 registry unavailable`
         : upToDate
-          ? `Version Checker: ${currentVersion} \u00b7 up to date`
-          : `Version Checker: ${currentVersion} \u2192 ${latestVersion} available`;
+          ? `${currentVersion} \u00b7 up to date`
+          : `${currentVersion} \u2192 ${latestVersion} available`;
     const header = [
       ...renderWordmark(),
-      `Cartethyia ${currentVersion} \u00b7 ${dashboardUrl}`,
-      versionCheckerLine,
+      `Console  ${dashboardUrl}`,
+      `Version  ${versionCheckerLine}`,
       "",
-      "Section menu",
     ];
 
     // Anything that talks to the gateway waits for it to be listening; the menu
@@ -167,30 +182,23 @@ export async function startMenu(): Promise<void> {
     const actions: readonly (() => Promise<void>)[] = [
       async () => openUrl(dashboardUrl),
       async () => {
-        // Drain first, then start the tray.
-        //
-        // The tray's own startup probe refuses to boot when the port is busy,
-        // so starting it before this process has let go made it fail with
-        // "already running on port" every time — while the menu still printed
-        // that everything was running, because a detached child with no stdio
-        // cannot report anything back. Releasing the port first is the fix, and
-        // waiting on the child's signal is what stops the menu from claiming
-        // success for a child that died.
-        console.log("Stopping the gateway to free the port…");
+        // Transfer the live gateway rather than draining it first. The tray
+        // adopts this instance through the ownership marker and reports ready
+        // before the menu returns to the shell.
         running = false;
         stopping = true;
         handedOff = true;
-        await shutDown();
         console.log("Starting the tray in the background…");
         const signalPath = join(tmpdir(), `cartethyia-tray-menu-${process.pid}-${randomUUID()}.json`);
         try {
           const url = await launchBackgroundWithStatus(
             ["run", resolvePackagePath("scripts", "cli", "main.ts"), "tray"],
-            { signalPath },
+            { signalPath, controllerHandoff: handoff },
           );
           console.log(`Cartethyia is running in the background at ${url || dashboardUrl}.`);
           console.log("The tray icon owns it; use Exit there to stop it.");
         } catch (error) {
+          restoreControllerAfterFailedHandoff(handoff);
           handedOff = false;
           console.error(
             `Could not hand off to the tray: ${error instanceof Error ? error.message : "unknown error"}`,
@@ -205,11 +213,12 @@ export async function startMenu(): Promise<void> {
         // the database, so the loopback token is the whole gate.
         await whenReady();
         const result = await exportBackup(port, drainToken);
-        if (result === null) return;
-        console.log(
-          `Backup written to ${result.path} (${(result.bytes / 1024).toFixed(1)} KiB, ${Object.keys(result.counts).length} tables).`,
-        );
-        console.log("Telemetry is not included: it is per-request history, not configuration.");
+        backupStatus = "error" in result
+          ? { tone: "error", text: `Backup failed: ${result.error}` }
+          : {
+              tone: "success",
+              text: `Backup saved at: ${result.path} (${(result.bytes / 1024).toFixed(1)} KiB)`,
+            };
       },
       async () => {
         // Deleting the console account is the only real password recovery:
@@ -266,23 +275,23 @@ export async function startMenu(): Promise<void> {
       : [...actions.slice(0, actions.length - 1), updateAction, actions[actions.length - 1] ?? (async () => undefined)];
 
     const rows: MenuRow[] = [
-      { kind: "action", label: "Open Console", hint: `browser \u00b7 ${dashboardUrl}` },
-      { kind: "action", label: "Hide to Tray", hint: "keep the gateway running" },
-      { kind: "action", label: "Backup", hint: "export config to Downloads" },
-      { kind: "action", label: "Reset", hint: "deletes the console account" },
+      { kind: "action", label: "Open Console", hint: "Open dashboard in browser" },
+      { kind: "action", label: "Hide to Tray", hint: "Keep the gateway running" },
+      { kind: "action", label: "Backup", hint: "Export config to Downloads" },
+      { kind: "action", label: "Reset", hint: "Delete console account" },
     ];
     if (!upToDate && latestVersion !== null) {
       rows.push({ kind: "action", label: `Update to ${latestVersion}`, hint: "installs now and exits" });
     }
     rows.push({ kind: "rule" });
-    rows.push({ kind: "action", label: "Exit", hint: "stop the gateway" });
+    rows.push({ kind: "action", label: "Exit", hint: "Stop the gateway" });
 
     // Focus the Update row by default when it exists, so the operator who
     // launched `carte` *because* they saw the version checker gets a one-key
     // path to the fix.
     const updateIndex = upToDate || latestVersion === null ? -1 : 4;
     const initialActionIndex = updateIndex >= 0 ? updateIndex : 0;
-    const choice = await chooseFromMenu(header, rows, { initialIndex: initialActionIndex });
+    const choice = await chooseFromMenu(header, rows, { initialIndex: initialActionIndex, ...(backupStatus ? { status: backupStatus } : {}) });
     if (choice === -1) break;
     const action = extendedActions[choice];
     if (action) await action();
@@ -291,7 +300,7 @@ export async function startMenu(): Promise<void> {
   // would stop the very process the tray just adopted, which is why the menu
   // appeared to hand over a gateway that was not listening.
   if (handedOff) return;
-  if (runningAttached !== null) {
+  if (runningAttached !== null || (await attachRunningGateway(port, drainToken)) !== null) {
     detachAttached();
     return;
   }

package/scripts/cli/controller.ts

@@ -0,0 +1,145 @@
+import { mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { pidAlive } from "./instance";
+
+/** A menu or tray that exclusively owns this installation's interactive UI. */
+export type ControllerKind = "menu" | "tray";
+
+/** Proof passed to the tray during Hide to Tray. Never printed or persisted in logs. */
+export interface ControllerHandoff {
+  readonly token: string;
+  readonly parentPid: number;
+}
+
+export interface ControllerLease {
+  readonly handoff: ControllerHandoff;
+  readonly release: () => void;
+}
+
+interface ControllerRecord extends ControllerHandoff {
+  readonly pid: number;
+  readonly kind: ControllerKind;
+  readonly startedAt: string;
+}
+
+const CONTROLLER_FILE = "controller.json";
+
+function controllerPath(): string {
+  const configDir = process.env.CARTETHYIA_CONFIG_DIR;
+  if (!configDir) throw new Error("Cartethyia config directory is unavailable");
+  mkdirSync(configDir, { recursive: true });
+  return join(configDir, CONTROLLER_FILE);
+}
+
+function readController(path: string): ControllerRecord | null {
+  try {
+    const value = JSON.parse(readFileSync(path, "utf8")) as Partial<ControllerRecord>;
+    if (typeof value.pid !== "number" || typeof value.parentPid !== "number" ||
+      typeof value.token !== "string" || value.token.length === 0 ||
+      (value.kind !== "menu" && value.kind !== "tray") || typeof value.startedAt !== "string") return null;
+    return value as ControllerRecord;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
+    // A partially rewritten or corrupt file must not be treated as permission
+    // to start a second gateway. It is only safe to reclaim a record whose old
+    // owner can be identified and is definitely dead.
+    throw new Error("The Cartethyia controller lock is unreadable; close carte/tray before retrying");
+  }
+}
+
+function writeController(path: string, record: ControllerRecord, exclusive: boolean): void {
+  writeFileSync(path, JSON.stringify(record), {
+    encoding: "utf8",
+    mode: 0o600,
+    ...(exclusive ? { flag: "wx" } : {}),
+  });
+}
+
+/**
+ * Acquire the one interactive controller for an installation.
+ *
+ * Hide to Tray passes the existing token to its child. The child replaces the
+ * pid in the same file without unlinking it, so a second menu cannot sneak into
+ * the handoff gap and drain the gateway while the first tray is taking over.
+ */
+export function acquireController(kind: ControllerKind, handoff?: ControllerHandoff): ControllerLease {
+  const path = controllerPath();
+  if (handoff !== undefined) {
+    const current = readController(path);
+    if (current === null || current.token !== handoff.token || current.parentPid !== handoff.parentPid ||
+      current.kind !== "menu") {
+      throw new Error("The menu-to-tray handoff is no longer owned by its original menu");
+    }
+    writeController(path, { ...current, pid: process.pid, kind: "tray" }, false);
+  } else {
+    const current = readController(path);
+    if (current !== null && pidAlive(current.pid)) {
+      throw new Error(`Cartethyia is already controlled by a ${current.kind} (PID ${current.pid}); not starting another instance`);
+    }
+    const token = crypto.randomUUID();
+    // Writing the replacement atomically avoids a corruption window in which
+    // another carte cannot tell whether the old owner was alive. A concurrent
+    // claimant reads either the complete old record or this complete new one.
+    const next: ControllerRecord = {
+      pid: process.pid,
+      parentPid: process.pid,
+      token,
+      kind,
+      startedAt: new Date().toISOString(),
+    };
+    try {
+      if (current !== null) {
+        const temporary = `${path}.${process.pid}.tmp`;
+        writeFileSync(temporary, JSON.stringify(next), { encoding: "utf8", mode: 0o600 });
+        try { renameSync(temporary, path); } catch (error) {
+          try { unlinkSync(temporary); } catch { /* Preserve the rename error. */ }
+          throw error;
+        }
+      } else writeController(path, next, true);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "EEXIST") {
+        throw new Error("Another Cartethyia menu or tray acquired the controller; not starting another instance");
+      }
+      throw error;
+    }
+  }
+
+  const token = handoff?.token ?? readController(path)?.token;
+  if (!token) throw new Error("Could not establish the Cartethyia controller lock");
+  const pid = process.pid;
+  let released = false;
+  return {
+    handoff: { token, parentPid: pid },
+    release: () => {
+      if (released) return;
+      released = true;
+      const current = readController(path);
+      // During a successful handoff the file already belongs to the tray. The
+      // parent must not delete its child's lease while returning to the shell.
+      if (current?.token === token && current.pid === pid) {
+        try { unlinkSync(path); } catch { /* A dead owner is reclaimed next start. */ }
+      }
+    },
+  };
+}
+
+/** Hand a failed tray startup back to the still-running menu. */
+export function restoreControllerAfterFailedHandoff(handoff: ControllerHandoff): void {
+  const path = controllerPath();
+  const current = readController(path);
+  if (current?.token === handoff.token && current.parentPid === handoff.parentPid && current.kind === "tray") {
+    writeController(path, { ...current, pid: handoff.parentPid, kind: "menu" }, false);
+  }
+}
+
+/** Read the one-shot handoff proof without exposing it to normal process logs. */
+export function inheritedControllerHandoff(env: NodeJS.ProcessEnv = process.env): ControllerHandoff | undefined {
+  const token = env.CARTETHYIA_CONTROLLER_TOKEN;
+  const parentPid = Number(env.CARTETHYIA_CONTROLLER_PARENT_PID);
+  if (!token || !Number.isInteger(parentPid) || parentPid <= 0) {
+    delete env.CARTETHYIA_CONTROLLER_TOKEN;
+    delete env.CARTETHYIA_CONTROLLER_PARENT_PID;
+    return undefined;
+  }
+  return { token, parentPid };
+}

package/scripts/cli/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`;
+}