patchwarden 1.5.1 → 1.6.1

package/src/control/routes/process.ts

@@ -8,13 +8,29 @@
  * launching, so the non-interactive web UI never deadlocks on a missing
  * dependency. All endpoints are POST routes gated by the control token.
  */
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync, statSync } from "node:fs";
 import { delimiter, extname, join } from "node:path";
 import { homedir } from "node:os";
 import { spawn } from "node:child_process";
 import { type ServerResponse } from "node:http";
+import {
+  buildChildEnvironment,
+  redactProcessOutput,
+  resolveTrustedExecutable,
+  sanitizeTrustedPath,
+} from "../../runner/processSecurity.js";
 import { recordEvent } from "../runtime.js";
-import { DEFAULT_TUNNEL_CLIENT_EXE, errorMessage, getRuntimeRoot, manageScriptPath, projectRoot, sendJson } from "../shared.js";
+import { launchFileManager } from "../fileManager.js";
+import {
+  config,
+  CORE_BASE_URL,
+  DIRECT_BASE_URL,
+  errorMessage,
+  getRuntimeRoot,
+  manageScriptPath,
+  projectRoot,
+  sendJson,
+} from "../shared.js";
 
 type ControlMode = "core" | "direct";
 
@@ -24,14 +40,32 @@ interface ManageResult {
   stderr: string;
 }
 
+const MAX_MANAGE_OUTPUT_CHARS = 128 * 1024;
+const MANAGE_ALLOWED_ENVIRONMENT = [
+  "PATCHWARDEN_CONFIG",
+  "PATCHWARDEN_TUNNEL_ID",
+  "PATCHWARDEN_CREDENTIAL_PATH",
+  "PATCHWARDEN_TUNNEL_CLIENT_EXE",
+  "TUNNEL_CLIENT_EXE",
+  "OPENCODE_BIN_DIR",
+  "HTTP_PROXY",
+  "HTTPS_PROXY",
+  "ALL_PROXY",
+  "NO_PROXY",
+] as const;
+
 function runManageAction(action: string, mode: string): Promise<ManageResult> {
   return new Promise((resolveP, rejectP) => {
     let child;
+    let exactValues: string[] = [];
     try {
+      const env = buildManageEnvironment();
+      exactValues = manageSensitiveValues(env);
+      const command = resolveTrustedExecutable("powershell.exe", projectRoot, { pathValue: env.PATH });
       child = spawn(
-        "powershell.exe",
+        command,
         ["-NoProfile", "-ExecutionPolicy", "Bypass", "-File", manageScriptPath, action, mode, "-Background"],
-        { cwd: projectRoot, windowsHide: true }
+        { cwd: projectRoot, windowsHide: true, env }
       );
     } catch (err) {
       rejectP(err);
@@ -47,10 +81,10 @@ function runManageAction(action: string, mode: string): Promise<ManageResult> {
       rejectP(new Error(`manage-patchwarden.ps1 timed out after 60s (action=${action}, mode=${mode})`));
     }, 60_000);
     child.stdout.on("data", (d: Buffer) => {
-      stdout += d.toString("utf-8");
+      stdout = appendBoundedManageOutput(stdout, d.toString("utf-8"));
     });
     child.stderr.on("data", (d: Buffer) => {
-      stderr += d.toString("utf-8");
+      stderr = appendBoundedManageOutput(stderr, d.toString("utf-8"));
     });
     child.on("error", (err) => {
       if (settled) return;
@@ -62,14 +96,31 @@ function runManageAction(action: string, mode: string): Promise<ManageResult> {
       if (settled) return;
       settled = true;
       clearTimeout(timer);
-      resolveP({ exitCode: code ?? -1, stdout, stderr });
+      resolveP({
+        exitCode: code ?? -1,
+        stdout: redactProcessOutput(stdout, exactValues),
+        stderr: redactProcessOutput(stderr, exactValues),
+      });
     });
   });
 }
 
-function selectedControlModes(mode: string): ControlMode[] {
-  if (mode === "core" || mode === "direct") return [mode];
-  return ["core", "direct"];
+export function resolveManageProfiles(mode: string, action: string, directEnabled: boolean): { selected: ControlMode[]; skipped: ControlMode[] } {
+  if (mode === "core" || mode === "direct") return { selected: [mode], skipped: [] };
+  if ((action === "start" || action === "restart") && !directEnabled) return { selected: ["core"], skipped: ["direct"] };
+  return { selected: ["core", "direct"], skipped: [] };
+}
+
+function selectedControlModes(mode: string, action = "status"): ControlMode[] {
+  return resolveManageProfiles(mode, action, config.enableDirectProfile === true).selected;
+}
+
+function skippedControlModes(mode: string, action: string): ControlMode[] {
+  return resolveManageProfiles(mode, action, config.enableDirectProfile === true).skipped;
+}
+
+function effectiveManageMode(modes: ControlMode[]): string {
+  return modes.length === 1 ? modes[0] : "all";
 }
 
 function launcherPathForMode(mode: ControlMode): string {
@@ -78,7 +129,7 @@ function launcherPathForMode(mode: ControlMode): string {
 }
 
 function findExecutableOnPath(fileName: string): string | null {
-  const pathValue = process.env.PATH || "";
+  const pathValue = sanitizeTrustedPath(process.env.PATH || "", projectRoot);
   const extensions =
     process.platform === "win32"
       ? (process.env.PATHEXT || ".EXE;.CMD;.BAT;.COM").split(";").filter(Boolean)
@@ -86,11 +137,11 @@ function findExecutableOnPath(fileName: string): string | null {
   for (const entry of pathValue.split(delimiter)) {
     if (!entry) continue;
     const direct = join(entry, fileName);
-    if (existsSync(direct)) return direct;
+    if (isRegularFile(direct)) return direct;
     if (process.platform === "win32" && !extname(fileName)) {
       for (const ext of extensions) {
         const candidate = join(entry, fileName + ext.toLowerCase());
-        if (existsSync(candidate)) return candidate;
+        if (isRegularFile(candidate)) return candidate;
       }
     }
   }
@@ -99,70 +150,296 @@ function findExecutableOnPath(fileName: string): string | null {
 
 function findTunnelClientExecutable(): string | null {
   if (process.env.PATCHWARDEN_CONTROL_FORCE_MISSING_TUNNEL_CLIENT === "1") return null;
-  const explicit = process.env.TUNNEL_CLIENT_EXE || process.env.PATCHWARDEN_TUNNEL_CLIENT_EXE;
-  if (explicit && existsSync(explicit)) return explicit;
+  const configured = config.tunnelClientPath;
+  if (configured && isRegularFile(configured)) return configured;
+  const explicit = process.env.PATCHWARDEN_TUNNEL_CLIENT_EXE || process.env.TUNNEL_CLIENT_EXE;
+  if (explicit && isRegularFile(explicit)) return explicit;
   const fromPath = findExecutableOnPath("tunnel-client.exe") ?? findExecutableOnPath("tunnel-client");
   if (fromPath) return fromPath;
 
   const candidates = [
-    DEFAULT_TUNNEL_CLIENT_EXE,
-    process.env.LOCALAPPDATA ? join(process.env.LOCALAPPDATA, "patchwarden", "tunnel-client.exe") : null,
+    process.env.LOCALAPPDATA ? join(process.env.LOCALAPPDATA, "PatchWarden", "tunnel-client.exe") : null,
     process.env.APPDATA ? join(process.env.APPDATA, "tunnel-client", "tunnel-client.exe") : null,
     join(homedir(), "tunnel-client", "tunnel-client.exe"),
   ].filter((v): v is string => typeof v === "string" && v.length > 0);
   for (const candidate of candidates) {
-    if (existsSync(candidate)) return candidate;
+    if (isRegularFile(candidate)) return candidate;
   }
   return null;
 }
 
+export function buildManageEnvironment(): NodeJS.ProcessEnv {
+  const agentEnvironmentNames = [...new Set(Object.values(config.agents)
+    .flatMap((agent) => agent.envAllowlist ?? []))];
+  const env = buildChildEnvironment({
+    cwd: projectRoot,
+    allowedNames: [...MANAGE_ALLOWED_ENVIRONMENT, ...agentEnvironmentNames],
+    blockedNames: [config.http?.ownerTokenEnv || "PATCHWARDEN_OWNER_TOKEN"],
+  });
+  const lifecycleNames = new Set(MANAGE_ALLOWED_ENVIRONMENT.map((name) => name.toUpperCase()));
+  const providerOnlyNames = agentEnvironmentNames.filter(
+    (name) => !lifecycleNames.has(name.toUpperCase()),
+  );
+  env.PATCHWARDEN_AGENT_ENV_ALLOWLIST = providerOnlyNames.join(";");
+  const tunnelClient = findTunnelClientExecutable();
+  if (tunnelClient) {
+    env.PATCHWARDEN_TUNNEL_CLIENT_EXE = tunnelClient;
+    env.TUNNEL_CLIENT_EXE = tunnelClient;
+  }
+  const proxy = config.tunnelProxy;
+  const core = proxy?.core || { mode: "environment" as const };
+  const direct = proxy?.scope === "separate" ? proxy.direct : core;
+  env.PATCHWARDEN_TUNNEL_PROXY_MODE = core.mode;
+  env.PATCHWARDEN_TUNNEL_PROXY_URL = core.mode === "manual" ? core.url || "" : "";
+  env.PATCHWARDEN_DIRECT_PROXY_MODE = direct.mode;
+  env.PATCHWARDEN_DIRECT_PROXY_URL = direct.mode === "manual" ? direct.url || "" : "";
+  return env;
+}
+
 // Re-exported so the status route can surface tunnel-client availability in
 // /api/status without duplicating the discovery logic.
 export { findTunnelClientExecutable };
 
+function profilePathForMode(mode: ControlMode): string | null {
+  if (!process.env.APPDATA) return null;
+  return join(process.env.APPDATA, "tunnel-client", mode === "direct" ? "patchwarden-direct.yaml" : "patchwarden.yaml");
+}
+
+function credentialPath(): string | null {
+  return process.env.APPDATA ? join(process.env.APPDATA, "patchwarden", "control-plane-api-key.dpapi") : null;
+}
+
 function preflightManageAction(action: string, mode: string): { status: number; body: Record<string, unknown> } | null {
   if (action !== "start" && action !== "restart") return null;
 
-  const missingLaunchers = selectedControlModes(mode)
+  const selectedModes = selectedControlModes(mode, action);
+  const missingLaunchers = selectedModes
     .map((m) => ({ mode: m, path: launcherPathForMode(m) }))
     .filter((entry) => !existsSync(entry.path));
   const tunnelClient = findTunnelClientExecutable();
+  const missingProfiles = selectedModes
+    .map((m) => ({ mode: m, path: profilePathForMode(m) }))
+    .filter((entry) => !entry.path || !existsSync(entry.path));
+  const savedCredential = credentialPath();
   const missing: string[] = [];
   if (!tunnelClient) missing.push("tunnel-client.exe");
   for (const entry of missingLaunchers) missing.push(`${entry.mode} launcher`);
+  for (const entry of missingProfiles) missing.push(`${entry.mode} profile`);
+  if (!savedCredential || !existsSync(savedCredential)) missing.push("tunnel runtime credential");
 
   if (missing.length === 0) return null;
 
+  const reasonCode = !tunnelClient
+    ? "tunnel_client_missing"
+    : missingLaunchers.length > 0
+      ? "launcher_missing"
+      : missingProfiles.length > 0
+        ? "tunnel_profile_missing"
+        : "tunnel_credential_missing";
+
   return {
     status: 409,
     body: {
       ok: false,
       action,
       mode,
+      reason_code: reasonCode,
       error:
         "Control Center preflight failed. Start/restart from the Web UI is non-interactive, so required runtime dependencies must be available before launching.",
       missing,
       next_steps: [
-        "Install tunnel-client.exe or set TUNNEL_CLIENT_EXE / PATCHWARDEN_TUNNEL_CLIENT_EXE to its full path.",
-        `Default checked path: ${DEFAULT_TUNNEL_CLIENT_EXE}`,
-        "Verify the launcher files under scripts/launchers are present.",
-        "Then retry from PatchWarden Control Center or PatchWarden-Control-Tray.cmd.",
+        "在桌面设置中自动检测或选择 tunnel-client.exe，也可设置 PATCHWARDEN_TUNNEL_CLIENT_EXE。",
+        "在桌面设置中配置 Tunnel ID 和专用 runtime API key，并完成 doctor 验证。",
+        "确认 scripts/launchers 下的启动器存在，然后重试。",
       ],
     },
   };
 }
 
+function preflightDirectProfile(action: string, mode: string): { status: number; body: Record<string, unknown> } | null {
+  if ((action !== "start" && action !== "restart") || mode !== "direct") return null;
+  if (config.enableDirectProfile === true) return null;
+  return {
+    status: 409,
+    body: {
+      ok: false,
+      action,
+      mode,
+      reason_code: "direct_profile_disabled",
+      error: "Direct profile 尚未启用。请先在桌面设置中启用 Direct，再启动对应隧道。",
+      next_steps: ["打开 设置 -> MCP 与隧道", "启用 Direct profile 并保存", "重新启动 Direct"],
+    },
+  };
+}
+
+function readRuntimeState(mode: ControlMode, fileName: string): Record<string, unknown> | null {
+  try {
+    return JSON.parse(readFileSync(join(getRuntimeRoot(mode === "direct"), fileName), "utf8").replace(/^\uFEFF/, ""));
+  } catch {
+    return null;
+  }
+}
+
+function readRuntimeLog(mode: ControlMode, fileName: string): string {
+  try {
+    const value = readFileSync(join(getRuntimeRoot(mode === "direct"), fileName), "utf8");
+    return value.length > 64_000 ? value.slice(-64_000) : value;
+  } catch {
+    return "";
+  }
+}
+
+export function classifySupervisorFailure(diagnosticText: string): string {
+  if (/unsupported_country_region_territory|unsupported.{0,30}(country|region|territory)/i.test(diagnosticText)) return "unsupported_region";
+  if (/\b(401|403)\b|unauthori[sz]ed|invalid.{0,30}(api.?key|credential)|api.?key.{0,30}(invalid|missing)/i.test(diagnosticText)) return "auth_failed";
+  if (/proxy|ECONNREFUSED|ENETUNREACH|ETIMEDOUT|could not resolve|name resolution|connection (failed|refused)/i.test(diagnosticText)) return "proxy_unreachable";
+  if (/tool manifest preflight|tool_manifest_(check_failed|invalid)|mcp-manifest-check/i.test(diagnosticText)) return "tool_manifest_check_failed";
+  if (/spawn EPERM|access (is )?denied|permission denied/i.test(diagnosticText)) return "supervisor_permission_denied";
+  if (/watcher.{0,40}(failed|unhealthy|missing|exited)/i.test(diagnosticText)) return "watcher_unhealthy";
+  if (/profile.{0,30}(missing|invalid)|config.{0,30}(missing|invalid)|launcher.{0,30}(missing|not found)/i.test(diagnosticText)) return "config_error";
+  return "supervisor_exited";
+}
+
+function processIsAlive(pid: unknown): boolean {
+  if (typeof pid !== "number" || !Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return (err as NodeJS.ErrnoException).code === "EPERM";
+  }
+}
+
+function inspectSupervisor(mode: ControlMode, startedAt: number): { terminal: boolean; reasonCode: string | null } {
+  const state = readRuntimeState(mode, "supervisor-status.json");
+  const checkedAt = typeof state?.checked_at === "string" ? Date.parse(state.checked_at) : 0;
+  const fresh = Number.isFinite(checkedAt) && checkedAt >= startedAt - 2000;
+  if (!fresh) return { terminal: false, reasonCode: null };
+  const explicitlyFailed = state?.status === "failed";
+  if (!explicitlyFailed && processIsAlive(state?.pid)) return { terminal: false, reasonCode: null };
+  const diagnostics = `${readRuntimeLog(mode, "supervisor.stderr.log")}\n${readRuntimeLog(mode, "supervisor.stdout.log")}`;
+  const recordedReason = typeof state?.reason_code === "string" ? state.reason_code : null;
+  return { terminal: true, reasonCode: recordedReason || classifySupervisorFailure(diagnostics) };
+}
+
+async function probeReady(baseUrl: string): Promise<boolean> {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), 1500);
+  try {
+    const response = await fetch(`${baseUrl}/readyz`, { signal: controller.signal, cache: "no-store" });
+    return response.ok;
+  } catch {
+    return false;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function inspectStartup(mode: ControlMode, startedAt: number): Promise<Record<string, unknown>> {
+  const tunnel = readRuntimeState(mode, "tunnel-status.json");
+  const checkedAt = typeof tunnel?.checked_at === "string" ? Date.parse(tunnel.checked_at) : 0;
+  const fresh = Number.isFinite(checkedAt) && checkedAt >= startedAt - 2000;
+  const endpointReady = await probeReady(mode === "direct" ? DIRECT_BASE_URL : CORE_BASE_URL);
+  const watcher = mode === "core" ? readRuntimeState(mode, "watcher-status.json") : null;
+  const watcherReady = mode === "direct" || watcher?.status === "healthy";
+  const ready = endpointReady && tunnel?.ready !== false && watcherReady;
+  const terminalStatuses = new Set(["failed", "error", "stopped", "restart_limit_reached"]);
+  const tunnelTerminal = fresh && terminalStatuses.has(String(tunnel?.status || "")) && tunnel?.reason_code !== "stopped_by_manager";
+  const supervisor = inspectSupervisor(mode, startedAt);
+  const terminal = tunnelTerminal || supervisor.terminal;
+  const reasonCode = tunnelTerminal
+    ? (typeof tunnel?.reason_code === "string" ? tunnel.reason_code : "startup_failed")
+    : supervisor.reasonCode;
+  return {
+    mode,
+    ready,
+    endpoint_ready: endpointReady,
+    watcher_ready: watcherReady,
+    status: tunnel?.status || "starting",
+    reason_code: reasonCode,
+    error: tunnel?.last_error || null,
+    terminal,
+  };
+}
+
+async function waitForStartup(modes: ControlMode[], startedAt: number): Promise<{ ok: boolean; profiles: Record<string, unknown>[]; reasonCode?: string }> {
+  const configured = Number(process.env.PATCHWARDEN_CONTROL_START_TIMEOUT_MS || "30000");
+  const timeoutMs = Number.isFinite(configured) ? Math.min(Math.max(configured, 1000), 120000) : 30000;
+  const deadline = Date.now() + timeoutMs;
+  let profiles: Record<string, unknown>[] = [];
+  while (Date.now() < deadline) {
+    profiles = await Promise.all(modes.map((mode) => inspectStartup(mode, startedAt)));
+    if (profiles.every((profile) => profile.ready === true)) return { ok: true, profiles };
+    const failed = profiles.find((profile) => profile.terminal === true);
+    if (failed) {
+      const reasonCode = typeof failed.reason_code === "string" ? failed.reason_code : "supervisor_exited";
+      return { ok: false, profiles, reasonCode };
+    }
+    await new Promise((resolvePromise) => setTimeout(resolvePromise, 500));
+  }
+  profiles = await Promise.all(modes.map((mode) => inspectStartup(mode, startedAt)));
+  return { ok: false, profiles, reasonCode: "startup_timeout" };
+}
+
 export async function handleManageAction(res: ServerResponse, action: string, mode: string): Promise<void> {
   try {
+    const directPreflight = preflightDirectProfile(action, mode);
+    if (directPreflight) {
+      recordEvent("manage." + mode + "." + action + ".profile_disabled", { reason_code: "direct_profile_disabled" });
+      sendJson(res, directPreflight.status, directPreflight.body);
+      return;
+    }
+    const selectedModes = selectedControlModes(mode, action);
+    const skippedModes = skippedControlModes(mode, action);
+    const managedMode = effectiveManageMode(selectedModes);
     const preflight = preflightManageAction(action, mode);
     if (preflight) {
       recordEvent("manage." + mode + "." + action + ".preflight_failed", {
         missing: preflight.body.missing,
       });
-      sendJson(res, preflight.status, preflight.body);
+      sendJson(res, preflight.status, {
+        ...preflight.body,
+        started_profiles: [],
+        skipped_profiles: skippedModes,
+      });
       return;
     }
-    const result = await runManageAction(action, mode);
+    const startedAt = Date.now();
+    const result = await runManageAction(action, managedMode);
+    if (result.exitCode !== 0) {
+      recordEvent("manage." + mode + "." + action, { exit_code: result.exitCode, ok: false });
+      sendJson(res, 500, {
+        ok: false,
+        action,
+        mode,
+        started_profiles: [],
+        skipped_profiles: skippedModes,
+        reason_code: "manager_failed",
+        error: result.stderr.trim() || result.stdout.trim() || `manage-patchwarden.ps1 exited with code ${result.exitCode}`,
+      });
+      return;
+    }
+    if (action === "start" || action === "restart") {
+      const startup = await waitForStartup(selectedModes, startedAt);
+      if (!startup.ok) {
+        const timeout = startup.reasonCode === "startup_timeout";
+        recordEvent("manage." + mode + "." + action + ".not_ready", { reason_code: startup.reasonCode, profiles: startup.profiles });
+        sendJson(res, timeout ? 504 : 502, {
+          ok: false,
+          action,
+          mode,
+          started_profiles: selectedModes,
+          skipped_profiles: skippedModes,
+          reason_code: startup.reasonCode,
+          error: timeout
+            ? "启动命令已执行，但服务未在等待时间内通过就绪检查。"
+            : "隧道 supervisor 在服务就绪前退出。",
+          profiles: startup.profiles,
+          next_steps: ["检查设置中的 tunnel-client 与代理", "运行健康检查", "查看本次 Core / Direct 日志"],
+        });
+        return;
+      }
+    }
     recordEvent("manage." + mode + "." + action, {
       exit_code: result.exitCode,
       ok: result.exitCode === 0,
@@ -172,6 +449,10 @@ export async function handleManageAction(res: ServerResponse, action: string, mo
       exitCode: result.exitCode,
       stdout: result.stdout,
       stderr: result.stderr,
+      verified: action === "start" || action === "restart",
+      started_profiles: action === "start" || action === "restart" ? selectedModes : [],
+      skipped_profiles: skippedModes,
+      reason_code: skippedModes.length > 0 ? "direct_profile_disabled" : null,
     });
   } catch (err) {
     recordEvent("manage." + mode + "." + action + ".failed", { error: errorMessage(err) });
@@ -182,23 +463,43 @@ export async function handleManageAction(res: ServerResponse, action: string, mo
 export function handleOpenLogsFolder(res: ServerResponse): void {
   try {
     const target = getRuntimeRoot(false);
-    let cmd: string;
-    if (process.platform === "win32") {
-      cmd = "explorer.exe";
-    } else if (process.platform === "darwin") {
-      cmd = "open";
-    } else {
-      cmd = "xdg-open";
-    }
-    try {
-      const child = spawn(cmd, [target], { detached: true, stdio: "ignore" });
-      child.on("error", () => { /* ignore spawn errors */ });
-      child.unref();
-    } catch {
-      /* ignore */
-    }
+    launchFileManager(target, projectRoot);
     sendJson(res, 200, { ok: true, path: target });
   } catch (err) {
     sendJson(res, 500, { error: errorMessage(err) });
   }
 }
+
+function appendBoundedManageOutput(current: string, next: string): string {
+  if (current.length >= MAX_MANAGE_OUTPUT_CHARS) return current;
+  return current + next.slice(0, MAX_MANAGE_OUTPUT_CHARS - current.length);
+}
+
+function manageSensitiveValues(env: NodeJS.ProcessEnv): string[] {
+  const agentEnvironmentValues = Object.values(config.agents)
+    .flatMap((agent) => agent.envAllowlist ?? [])
+    .map((name) => findEnvironmentValue(env, name));
+  const values = [
+    env.HTTP_PROXY,
+    env.HTTPS_PROXY,
+    env.ALL_PROXY,
+    env.PATCHWARDEN_TUNNEL_PROXY_URL,
+    env.PATCHWARDEN_DIRECT_PROXY_URL,
+    ...agentEnvironmentValues,
+  ].filter((value): value is string => typeof value === "string" && Buffer.byteLength(value, "utf-8") >= 8);
+  return [...new Set(values)].sort((left, right) => right.length - left.length);
+}
+
+function findEnvironmentValue(env: NodeJS.ProcessEnv, name: string): string | undefined {
+  if (process.platform !== "win32") return env[name];
+  const match = Object.keys(env).find((key) => key.toUpperCase() === name.toUpperCase());
+  return match ? env[match] : undefined;
+}
+
+function isRegularFile(path: string): boolean {
+  try {
+    return statSync(path).isFile();
+  } catch {
+    return false;
+  }
+}