@mochi.js/core 0.2.2 → 0.6.0

package/src/launch.ts

@@ -12,6 +12,10 @@
 
 import { deriveMatrix, type ProfileV1 } from "@mochi.js/consistency";
 import { resolveBinary } from "./binary";
+import { defaultProfileForHost, unsupportedHostMessage } from "./default-profile";
+import { type GeoConsistencyMode, reconcileGeoConsistency } from "./geo-consistency";
+import { probeExitGeo } from "./geo-probe";
+import { type LinuxServerEnv, probeLinuxServerEnv } from "./linux-server";
 import { spawnChromium } from "./proc";
 import { parseProxyUrl } from "./proxy-auth";
 import { Session } from "./session";
@@ -83,10 +87,70 @@ export interface ChallengeLaunchOptions {
  *     flows — never enable in production.
  */
 export interface LaunchOptions {
-  profile: ProfileId | ProfileV1;
+  /**
+   * Profile to derive the fingerprint matrix from. Either a `ProfileId`
+   * string (looked up against `KNOWN_PROFILE_IDS`) or an inline `ProfileV1`
+   * object.
+   *
+   * **Optional since task 0272** — when omitted, mochi auto-picks the
+   * profile whose declared OS matches the host's `process.platform` /
+   * `process.arch` pair via {@link defaultProfileForHost}:
+   *
+   *   - `linux/x64`     → `linux-chrome-stable`
+   *   - `darwin/arm64`  → `mac-m4-chrome-stable`
+   *   - `darwin/x64`    → `mac-chrome-stable`
+   *   - `win32/x64`     → `windows-chrome-stable`
+   *
+   * On any unsupported host (FreeBSD, Linux arm64 today, Windows arm64,
+   * Alpine musl), launch throws with a precise diagnostic listing the six
+   * explicit profile IDs the user can choose from. The default never
+   * silently overrides an explicit choice.
+   *
+   * Strategic rationale: a Linux server defaulting to a Linux profile
+   * removes the entire class of "user accidentally spoofed Windows from a
+   * Linux DC and looked weird to the WAF" failures. Linux is a real-user
+   * signal, not a bot signal — see `concepts/stealth-philosophy` for the
+   * thesis + production evidence.
+   */
+  profile?: ProfileId | ProfileV1;
   seed: string;
   proxy?: string | ProxyConfig;
+  /**
+   * Legacy boolean knob — `true` runs Chromium under `--headless=new`,
+   * `false` (default in v0.1) runs headful. New code should prefer
+   * {@link headlessMode}, which is more expressive AND env-aware.
+   *
+   * Resolution priority (task 0258):
+   *
+   *   1. `headlessMode` if set.
+   *   2. Else `headless: true → "new"`, `headless: false → "off"`.
+   *   3. Else env-aware default — Linux without DISPLAY / WAYLAND_DISPLAY
+   *      auto-resolves to `"new"` (the common server case); everywhere else
+   *      defaults to `"off"` (headful, requires a display).
+   */
   headless?: boolean;
+  /**
+   * Headless dispatch mode (task 0258). One of:
+   *
+   *   - `"new"`    — modern Chromium headless (`--headless=new`). Full
+   *                  rendering, near-byte-identical to headful for
+   *                  fingerprinting. The right default on a server.
+   *   - `"legacy"` — legacy `--headless` (no `=new`). Separate, more-
+   *                  detectable code path; only useful for parity with
+   *                  older tooling. Documented but not recommended.
+   *   - `"off"`    — run headful. Requires a real display server (DISPLAY
+   *                  on X11, WAYLAND_DISPLAY on Wayland) or xvfb.
+   *
+   * When unset, mochi infers the default from the live env: Linux without
+   * DISPLAY / WAYLAND_DISPLAY → `"new"`; otherwise `"off"`. The legacy
+   * `headless: boolean` knob (when set) overrides the env default but is
+   * itself overridden by an explicit `headlessMode`.
+   *
+   * Use `mochi.detectLinuxServerEnv()` to introspect what mochi inferred.
+   *
+   * @see docs/getting-started/linux-server.md
+   */
+  headlessMode?: "new" | "legacy" | "off";
   binary?: string;
   args?: string[];
   out?: { traceDir?: string };
@@ -151,6 +215,35 @@ export interface LaunchOptions {
    * solving is v0.3+).
    */
   challenges?: ChallengeLaunchOptions;
+  /**
+   * Reconcile `(matrix.timezone, matrix.locale)` against the proxy's
+   * exit-IP geolocation. Closes the cross-layer leak where a US profile
+   * over an EU proxy would have `Date.getTimezoneOffset()` reporting PT
+   * while the IP geolocates to UTC+1 — the canonical bot signature.
+   *
+   * - `"privacy-fallback"` *(default)* — on mismatch (or probe failure),
+   *   override the matrix to UTC + `en-US`. The session fingerprints as
+   *   a privacy-conscious user (Tor / Brave / hardened-FF style), which
+   *   is benign in most threat models.
+   * - `"auto-correct"` — on mismatch, override the matrix's timezone
+   *   with the IP's timezone and the locale with a primary-locale
+   *   guess for the IP's country. Most "stealth" but trusts mochi's
+   *   IP-derived defaults over the user's declared profile.
+   * - `"strict"` — throw `GeoMismatchError` on mismatch. The user must
+   *   change profile or change proxy. Probe failure (null) does NOT
+   *   throw under strict — that's a network blip, not a mismatch.
+   * - `"off"` — skip the probe entirely. Use in offline tests / when
+   *   the probe service is rate-limited.
+   *
+   * The probe is a single GET through wreq (using the matrix's
+   * `wreqPreset`, so the geo service sees the same JA4/headers as user
+   * traffic). 4-attempt cap, 2s per endpoint. Probe results are NOT
+   * cached across sessions — proxy IPs rotate.
+   *
+   * @see PLAN.md §9 (relational consistency, IP/TZ/Locale axis)
+   * @see tasks/0262-ip-tz-locale-exit-consistency.md
+   */
+  geoConsistency?: GeoConsistencyMode;
 }
 
 /**
@@ -172,13 +265,89 @@ export async function launch(opts: LaunchOptions): Promise<Session> {
   // are resolved against a placeholder profile until `@mochi.js/profiles`
   // ships its first capture (phase 0.4). The matrix is bit-stable per
   // `(profile, seed)` excluding the `derivedAt` timestamp.
-  const profile = resolveProfile(opts.profile);
-  const matrix = deriveMatrix(profile, opts.seed);
+  //
+  // Task 0272 — when `profile` is omitted, auto-pick the host-OS-matching
+  // profile id. Throws with a precise diagnostic if the host is one of the
+  // unsupported ones (FreeBSD, Linux arm64 today, Windows arm64, Alpine
+  // musl). Explicit `profile:` always wins; the auto-pick never overrides.
+  const profileSource = resolveProfileSource(opts.profile);
+  const matrix = deriveMatrix(profileSource.profile, opts.seed);
+  if (profileSource.autoPicked) {
+    // One info-level log line so users can see what mochi inferred without
+    // calling `defaultProfileForHost()` themselves. Wording is pinned by
+    // task 0272 — keep stable so docs + LLM-context blocks stay correct.
+    // (Routed through `console.warn` to match the existing diagnostic
+    // channel for `geoConsistency` / Linux-server inference; `console.info`
+    // is gated by the workspace lint config — `noConsole` only allows
+    // `error` and `warn` at the moment.)
+    console.warn(
+      `[mochi] no profile supplied; auto-picked ${profileSource.id} for host ` +
+        `${process.platform}/${process.arch}. To override: pass ` +
+        `profile: "${profileSource.id}" explicitly.`,
+    );
+  }
+
+  // Task 0262 — exit-IP / TZ / locale reconciliation.
+  //
+  // Probe the apparent exit IP through the configured proxy (using wreq
+  // with the matrix's `wreqPreset` so the geo service sees the same JA4
+  // / headers as user traffic). Then cross-reference against
+  // `(matrix.timezone, matrix.locale)` and apply `geoConsistency`. The
+  // adjusted matrix flows into BOTH `spawnChromium` (so `--lang` reflects
+  // any override) AND `Session` (so inject + the CDP `Emulation.set
+  // TimezoneOverride` send pick it up). PLAN.md §9.
+  //
+  // `"off"` short-circuits the probe — the probe call itself respects
+  // the mode so we don't pay the network round-trip in offline tests.
+  const geoMode: GeoConsistencyMode = opts.geoConsistency ?? "privacy-fallback";
+  let adjustedMatrix = matrix;
+  if (geoMode !== "off") {
+    const geo = await probeExitGeo({
+      ...(normalized?.netProxy !== undefined ? { proxy: normalized.netProxy } : {}),
+      matrix,
+    });
+    // Strict mode throws GeoMismatchError on real mismatch; let it
+    // propagate up so callers can recover (the orchestrator surfaced
+    // it as the canonical failure mode for "wrong proxy for profile").
+    const result = reconcileGeoConsistency(matrix, geo, geoMode);
+    adjustedMatrix = result.matrix;
+    if (result.action === "privacy-fallback" || result.action === "auto-correct") {
+      console.warn(
+        `[mochi] geoConsistency=${geoMode}: ${result.action} applied — ${result.reason ?? "(no reason)"}`,
+      );
+    }
+  }
+
+  // Resolve headless dispatch BEFORE the spawn call so we can log the
+  // env-derived default and let the user introspect via
+  // `mochi.detectLinuxServerEnv()`. Task 0258 — the "Linux server, no
+  // DISPLAY" case is the common deployment failure mode for `mochi.launch()`,
+  // and the previous default (`opts.headless ?? false` → headful) crashed
+  // immediately on a fresh Ubuntu / Debian host because there was no display
+  // to attach to. We now infer `"new"` on that environment.
+  const linuxEnv = probeLinuxServerEnv();
+  const resolvedHeadlessMode = resolveHeadlessMode(opts, linuxEnv);
+  if (
+    resolvedHeadlessMode === "new" &&
+    opts.headlessMode === undefined &&
+    opts.headless === undefined
+  ) {
+    // Only chatter when the launcher had to infer (caller said nothing). An
+    // explicit `headlessMode: "new"` from the caller is silent — they know
+    // what they asked for. The container/root signals are surfaced too so
+    // the diagnostic is one log line, not three.
+    console.warn(
+      `[mochi] Linux server detected (no DISPLAY / WAYLAND_DISPLAY) — defaulting to ` +
+        `--headless=new. ${linuxEnv.rationale}. Set headlessMode: "off" to override; ` +
+        `see docs/getting-started/linux-server.md for the xvfb path.`,
+    );
+  }
 
   const proc = await spawnChromium({
     binary,
     extraArgs: opts.args,
     headless: opts.headless ?? false,
+    headlessMode: resolvedHeadlessMode,
     // Opt-out for the auto-no-sandbox-as-root fallback (default: fallback
     // is on so first-run on a Linux server box doesn't crash).
     ...(opts.allowRootWithSandbox === true ? { allowRootWithSandbox: true } : {}),
@@ -191,17 +360,26 @@ export async function launch(opts: LaunchOptions): Promise<Session> {
     // inject layer's `navigator.languages` spoof; Chromium derives the
     // q-weighted `Accept-Language` value from the single `--lang` primary
     // automatically. Task 0251.
-    locale: matrix.locale,
+    locale: adjustedMatrix.locale,
     // Pin OS-level outer window from the matrix's display geometry so
     // `window.outerWidth/outerHeight` (which reads from the OS window,
     // NOT the JS-spoofed `screen.*`) matches the spoof. Closes the
     // `fingerprint-scan.com` 800×600 leak under `--headless=new`.
     // UDC fixes the same issue at `__init__.py:410-411`. Task 0252.
-    ...(Number.isInteger(matrix.display.width) &&
-    Number.isInteger(matrix.display.height) &&
-    matrix.display.width > 0 &&
-    matrix.display.height > 0
-      ? { windowSize: { width: matrix.display.width, height: matrix.display.height } }
+    //
+    // (`adjustedMatrix.display` === `matrix.display` since geo reconcile
+    // only touches timezone/locale/languages — but we use the adjusted
+    // ref for forward-compat.)
+    ...(Number.isInteger(adjustedMatrix.display.width) &&
+    Number.isInteger(adjustedMatrix.display.height) &&
+    adjustedMatrix.display.width > 0 &&
+    adjustedMatrix.display.height > 0
+      ? {
+          windowSize: {
+            width: adjustedMatrix.display.width,
+            height: adjustedMatrix.display.height,
+          },
+        }
       : {}),
     // Hermetic harness/CI escape hatch — re-applies the patchright-trim
     // flags (`--disable-component-update`, `--disable-default-apps`,
@@ -213,7 +391,7 @@ export async function launch(opts: LaunchOptions): Promise<Session> {
 
   const session = new Session({
     proc,
-    matrix,
+    matrix: adjustedMatrix,
     seed: opts.seed,
     ...(opts.timeout !== undefined ? { defaultTimeoutMs: opts.timeout } : {}),
     ...(opts.bypassInject === true ? { bypassInject: true } : {}),
@@ -235,12 +413,52 @@ export const mochi = {
   version: VERSION,
   /** Launch a browser session. */
   launch,
+  /**
+   * Inspect what mochi would infer about the current process environment for
+   * Linux-server detection (drives `headlessMode` defaulting). Pure read of
+   * `process.platform`, `process.env.DISPLAY`, `process.env.WAYLAND_DISPLAY`,
+   * `process.getuid?.()`, and the container probe paths. Task 0258.
+   */
+  detectLinuxServerEnv: probeLinuxServerEnv,
+  /**
+   * Inspect which profile id `mochi.launch` would auto-pick on the current
+   * host when `profile` is omitted. Pure read of `process.platform` /
+   * `process.arch`. Returns `null` on unsupported hosts — the launcher
+   * throws on that path with a list of explicit profile IDs. Task 0272.
+   *
+   * @see tasks/0271-the-linux-os-thesis.md — the strategic thesis
+   * @see https://mochijs.com/docs/concepts/stealth-philosophy
+   */
+  defaultProfileForHost,
 } as const;
 
 export type Mochi = typeof mochi;
 
 // ---- helpers ----------------------------------------------------------------
 
+/**
+ * Resolve the effective {@link LaunchOptions.headlessMode} given a snapshot
+ * of `(opts, env)`. Pure / synchronous so tests can drive both axes without
+ * stubbing globals. Resolution order — task 0258:
+ *
+ *   1. Explicit `opts.headlessMode` wins.
+ *   2. Else legacy `opts.headless: true | false` maps to `"new"` / `"off"`.
+ *   3. Else env-aware default — Linux without DISPLAY / WAYLAND_DISPLAY →
+ *      `"new"`; otherwise `"off"`.
+ *
+ * Exported so the unit tests can lock the resolution table without spawning
+ * a Chromium or stubbing `process.platform`.
+ */
+export function resolveHeadlessMode(
+  opts: Pick<LaunchOptions, "headless" | "headlessMode">,
+  env: LinuxServerEnv,
+): "new" | "legacy" | "off" {
+  if (opts.headlessMode !== undefined) return opts.headlessMode;
+  if (opts.headless === true) return "new";
+  if (opts.headless === false) return "off";
+  return env.serverNoDisplay ? "new" : "off";
+}
+
 /**
  * Reconcile the two `LaunchOptions.proxy` shapes (URL string and
  * `ProxyConfig` record) into a single normalized record carrying:
@@ -301,14 +519,56 @@ function injectAuth(server: string, auth: { username: string; password: string }
 }
 
 /**
- * Resolve `LaunchOptions.profile` into a concrete `ProfileV1`. Inline
- * profiles flow through unchanged. String profile ids — until
- * `@mochi.js/profiles` ships (phase 0.4) — resolve to a generic placeholder
- * stamped with the id; the consistency engine still produces a real,
- * relationally-locked Matrix from it.
+ * Resolve `LaunchOptions.profile` into a concrete `ProfileV1` plus the
+ * meta-flag the launcher needs to decide whether to log the auto-pick
+ * INFO line. Three branches:
+ *
+ *   1. Explicit `ProfileV1` object — flows through unchanged. `autoPicked`
+ *      false; `id` taken from the inline object.
+ *   2. Explicit `ProfileId` string — same placeholder synthesis as before.
+ *      `autoPicked` false.
+ *   3. `undefined` — task 0272: call `defaultProfileForHost()`. Throw with
+ *      the unsupported-host diagnostic when the resolver returns `null`.
+ *      `autoPicked` true.
+ *
+ * Pure function — does not log. The launcher emits the INFO line itself
+ * after observing `autoPicked === true` so test fixtures can assert the
+ * resolution without intercepting `console`.
+ */
+function resolveProfileSource(profile: ProfileId | ProfileV1 | undefined): {
+  profile: ProfileV1;
+  id: ProfileId;
+  autoPicked: boolean;
+} {
+  if (typeof profile === "object") {
+    return { profile, id: profile.id, autoPicked: false };
+  }
+  if (typeof profile === "string") {
+    return {
+      profile: synthesizePlaceholderProfile(profile),
+      id: profile,
+      autoPicked: false,
+    };
+  }
+  // Auto-pick branch — task 0272.
+  const picked = defaultProfileForHost();
+  if (picked === null) {
+    throw new Error(unsupportedHostMessage(process.platform, process.arch));
+  }
+  return {
+    profile: synthesizePlaceholderProfile(picked),
+    id: picked,
+    autoPicked: true,
+  };
+}
+
+/**
+ * Synthesize a generic placeholder `ProfileV1` from a profile id. Until
+ * `@mochi.js/profiles.getProfile` lands (phase 0.4), the consistency engine
+ * still produces a real, relationally-locked Matrix from this skeleton —
+ * the id is what flows into `sha256(profile.id + seed)`.
  */
-function resolveProfile(profile: ProfileId | ProfileV1): ProfileV1 {
-  if (typeof profile === "object") return profile;
+function synthesizePlaceholderProfile(profile: ProfileId): ProfileV1 {
   return {
     id: profile,
     version: "0.0.0-placeholder",

package/src/linux-server.ts

@@ -0,0 +1,157 @@
+/**
+ * Linux-server environment detection.
+ *
+ * The "common deployment env" failure mode for `mochi.launch()`: a fresh
+ * Ubuntu / Debian server, no DISPLAY, no Wayland — Chromium spawns but cannot
+ * render and either hangs or crashes on the first paint. The fix is to drive
+ * Chromium through `--headless=new` (the modern headless that ships full
+ * rendering and is near-byte-identical to headful for fingerprinting; the
+ * legacy `--headless` is a separate, more-detectable code path).
+ *
+ * This module exposes:
+ *
+ *   - {@link detectLinuxServerEnv} — pure function. Given a snapshot of
+ *     `(platform, env, container probes)`, returns a record describing what
+ *     mochi inferred (Linux-without-display? root? containerised?). Pure /
+ *     synchronous so callers can stub the inputs and unit-test without
+ *     touching `process.*`.
+ *   - {@link DEFAULT_LINUX_SERVER_PROBES} — convenience that snapshots the
+ *     real `process.platform`, `process.env.DISPLAY`,
+ *     `process.env.WAYLAND_DISPLAY`, `process.getuid?.()`, and the container
+ *     filesystem probes (`/.dockerenv`, `/proc/1/cgroup`). Calls
+ *     {@link detectLinuxServerEnv} with that snapshot and returns the result.
+ *
+ * Detection rules:
+ *
+ *   1. `platform === "linux"` AND no `DISPLAY` AND no `WAYLAND_DISPLAY`
+ *      → `serverNoDisplay = true`. This is the load-bearing signal for
+ *      auto-defaulting `headlessMode` to `"new"`.
+ *   2. `getuid?.() === 0` → `root = true`. Orthogonal to #1; drives the
+ *      existing auto-`--no-sandbox` path in `proc.ts` (kept verbatim — this
+ *      module does not own that decision).
+ *   3. `/.dockerenv` exists OR `/proc/1/cgroup` mentions
+ *      `docker | containerd | kubepods` → `container = true`. Tertiary
+ *      signal; surfaced for diagnostics only (a container with DISPLAY set
+ *      is still a "with display" environment).
+ *
+ * @see tasks/0259 (Linux first-run experience)
+ * @see tasks/0258 (Linux server env auto-detection)
+ * @see docs/getting-started/linux-server.md
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+
+/**
+ * Snapshot of the runtime probes that {@link detectLinuxServerEnv} consumes.
+ * Defined as a record (not direct `process.*` reads) so unit tests can stub
+ * each axis independently.
+ */
+export interface LinuxServerProbes {
+  /** `process.platform`. */
+  platform: NodeJS.Platform;
+  /** Value of `process.env.DISPLAY` (X11 display server). */
+  display: string | undefined;
+  /** Value of `process.env.WAYLAND_DISPLAY` (Wayland display server). */
+  waylandDisplay: string | undefined;
+  /** UID, or `undefined` on platforms without a getuid (Windows). */
+  uid: number | undefined;
+  /** `true` when `/.dockerenv` exists. */
+  hasDockerEnvFile: boolean;
+  /**
+   * Contents of `/proc/1/cgroup`, or `undefined` if absent / unreadable.
+   * Container detection scans this for `docker | containerd | kubepods`.
+   */
+  cgroup: string | undefined;
+}
+
+/**
+ * Result returned by {@link detectLinuxServerEnv}. Structured so callers
+ * (the launcher, the diagnostic helper, an end-user calling
+ * `mochi.detectLinuxServerEnv()` directly) can introspect each axis without
+ * re-running the probes.
+ */
+export interface LinuxServerEnv {
+  /** `true` iff Linux + no DISPLAY + no WAYLAND_DISPLAY. */
+  serverNoDisplay: boolean;
+  /** `true` iff the process is running as uid 0 on Linux. */
+  root: boolean;
+  /** `true` iff a container indicator (`/.dockerenv` or cgroup mention) hit. */
+  container: boolean;
+  /** Human-readable rationale string. Intended for `console.debug`. */
+  rationale: string;
+}
+
+/**
+ * Pure, synchronous classifier. Given a `LinuxServerProbes` snapshot, returns
+ * a `LinuxServerEnv` summary. No I/O, no global reads — every input is on the
+ * `probes` argument. Exposed for unit tests AND for users who want to drive
+ * the classification with their own probes (e.g. a CI matrix that wants to
+ * pretend it's running under DISPLAY=:0 to validate a code path).
+ */
+export function detectLinuxServerEnv(probes: LinuxServerProbes): LinuxServerEnv {
+  const isLinux = probes.platform === "linux";
+  const hasDisplay =
+    (probes.display !== undefined && probes.display.length > 0) ||
+    (probes.waylandDisplay !== undefined && probes.waylandDisplay.length > 0);
+  const serverNoDisplay = isLinux && !hasDisplay;
+  const root = isLinux && probes.uid === 0;
+  const container =
+    probes.hasDockerEnvFile ||
+    (probes.cgroup !== undefined && /docker|containerd|kubepods/.test(probes.cgroup));
+
+  const parts: string[] = [];
+  parts.push(`platform=${probes.platform}`);
+  parts.push(`display=${probes.display ?? "(unset)"}`);
+  parts.push(`waylandDisplay=${probes.waylandDisplay ?? "(unset)"}`);
+  parts.push(`uid=${probes.uid ?? "(none)"}`);
+  parts.push(`container=${container}`);
+  parts.push(`serverNoDisplay=${serverNoDisplay}`);
+  const rationale = parts.join(" ");
+
+  return { serverNoDisplay, root, container, rationale };
+}
+
+/**
+ * Snapshot the live process state and run {@link detectLinuxServerEnv}
+ * against it. The convenience entry point used by {@link launch} and the
+ * inspection helper exposed on the public surface (`mochi.detectLinuxServerEnv()`).
+ *
+ * Filesystem probes (`/.dockerenv`, `/proc/1/cgroup`) are guarded with
+ * `existsSync` + a try/catch so the call is safe on macOS / Windows / sandboxed
+ * environments where the paths don't exist.
+ */
+export function probeLinuxServerEnv(): LinuxServerEnv {
+  return detectLinuxServerEnv(snapshotProbes());
+}
+
+/**
+ * Build a {@link LinuxServerProbes} record from the live `process.*` and
+ * filesystem state. Exported so callers debugging an environment-detection
+ * issue can inspect the raw inputs the classifier saw.
+ */
+export function snapshotProbes(): LinuxServerProbes {
+  const platform = process.platform;
+  const display = process.env.DISPLAY;
+  const waylandDisplay = process.env.WAYLAND_DISPLAY;
+  const uid = typeof process.getuid === "function" ? process.getuid() : undefined;
+  const hasDockerEnvFile = safeExists("/.dockerenv");
+  const cgroup = safeReadText("/proc/1/cgroup");
+  return { platform, display, waylandDisplay, uid, hasDockerEnvFile, cgroup };
+}
+
+function safeExists(path: string): boolean {
+  try {
+    return existsSync(path);
+  } catch {
+    return false;
+  }
+}
+
+function safeReadText(path: string): string | undefined {
+  try {
+    if (!existsSync(path)) return undefined;
+    return readFileSync(path, "utf8");
+  } catch {
+    return undefined;
+  }
+}