import { execFile } from "node:child_process"; import { chmod, writeFile } from "node:fs/promises"; import { basename, dirname, extname, join } from "node:path"; import { promisify } from "node:util"; import { HopperCancelledError, HopperProcessError, HopperStartError, } from "../domain/hopperErrors.js"; import { err, ok, type Result } from "../domain/result.js"; import { cleanupOwnedProcessGroup } from "../process/ProcessOwnership.js"; import { execFileOutput } from "../process/ExecFileOutput.js"; import { type ProviderProcessLaunch, spawnOwnedProviderProcess, } from "../process/ProviderProcess.js"; import { waitForAbortableDelay } from "../process/ProviderDeadline.js"; import { selectLinuxPrivateDisplayStrategy, type LinuxPrivateDisplayRunnableStrategy, type LinuxPrivateDisplaySelection, } from "./LinuxPrivateDisplayProbe.js"; import writeFileAtomic from "write-file-atomic"; import { acquireHopperTargetLease } from "./HopperTargetLease.js"; import type { HopperTargetLease } from "./HopperTargetLease.js"; const execFileAsync = promisify(execFile); const HOPPER_BACKGROUND_STARTUP_MS = 5_000; /** Coordinates for one private bridge session. */ export interface BridgeSession { readonly directory: string; readonly socketPath: string; readonly token: string; readonly runId: string; } /** Process handle returned by a bridge launcher. */ export type BridgeLaunch = | (ProviderProcessLaunch & { readonly shutdownMode: "bridge-request" }) | (Extract & { readonly shutdownMode: "process-cleanup"; readonly cleanup: NonNullable; }); /** Application-owned capability that starts the in-Hopper bridge. */ export interface BridgeLauncher { launch( session: BridgeSession, options?: { readonly signal?: AbortSignal }, ): Promise< Result< BridgeLaunch, HopperStartError | HopperCancelledError | HopperProcessError > >; } interface SharedHopperApplicationLauncherOptions { readonly launcherPath: string; readonly targetPath: string; readonly targetKind: "executable" | "database"; readonly loaderArgs: readonly string[]; readonly bridgeScriptPath: string; } /** Explicit launcher contract; the Linux adapter verifies its pinned Hopper build before execution. */ export type HopperApplicationLauncherOptions = | (SharedHopperApplicationLauncherOptions & { readonly launchMode: "native"; readonly demoHelperPath?: never; }) | (SharedHopperApplicationLauncherOptions & { readonly launchMode: "verified_linux_demo"; readonly demoHelperPath: string; }); export interface HopperApplicationLauncherDependencies { readonly platform?: NodeJS.Platform; readonly acquireTargetLease?: typeof acquireHopperTargetLease; readonly selectPrivateDisplay?: (options: { readonly helperPath: string; readonly signal?: AbortSignal; }) => Promise; } /** * Launches Hopper through its documented CLI and injects only REA's owned bridge. * * Hopper's `hopper` helper internally issues an AppleScript `activate` command. * Consequently, opening a target may bring Hopper to the foreground even though * REA first asks macOS to start the application hidden and in the background. * REA cannot reliably suppress that activation without replacing Hopper's * supported launcher; callers must treat possible foreground UI as an upstream * Hopper constraint, not as evidence that analysis failed. * * REA owns only the short-lived launcher helper's run-token-authenticated * process group. It does not claim ownership of the Hopper GUI process that * macOS LaunchServices may create or reuse. */ export class HopperApplicationLauncher implements BridgeLauncher { constructor( readonly options: HopperApplicationLauncherOptions, readonly dependencies: HopperApplicationLauncherDependencies = {}, ) {} async launch( session: BridgeSession, options: { readonly signal?: AbortSignal } = {}, ): Promise< Result< BridgeLaunch, HopperStartError | HopperCancelledError | HopperProcessError > > { const leaseResult = await this.#acquireTargetLease(session.runId); if (!leaseResult.ok) return leaseResult; const lease = leaseResult.value; let leaseTransferred = false; try { const ownsProcessLifetime = usesLinuxDemo(this.options); const bootstrap = await this.#writeBootstrap( session, ownsProcessLifetime, ); if (!bootstrap.ok) return bootstrap; const launched = await this.#launchPreparedTarget({ session, signal: options.signal, bootstrapPath: bootstrap.value, ownsProcessLifetime, lease, }); leaseTransferred = launched.ok; return launched; } finally { if (!leaseTransferred) await lease?.release(); } } async #launchPreparedTarget(input: { readonly session: BridgeSession; readonly signal: AbortSignal | undefined; readonly bootstrapPath: string; readonly ownsProcessLifetime: boolean; readonly lease: HopperTargetLease | undefined; }): Promise< Result< BridgeLaunch, HopperStartError | HopperCancelledError | HopperProcessError > > { const { session, signal, bootstrapPath, ownsProcessLifetime, lease } = input; const action = this.options.targetKind === "database" ? "--database" : "--executable"; const argumentsForTarget = [ ...this.options.loaderArgs, "--analysis", "-Y", bootstrapPath, action, this.options.targetPath, ]; try { if (signal?.aborted === true) return err(new HopperCancelledError()); const display = await this.#privateDisplay(signal); if (!display.ok) return err(display.error); const prepared = await prepareHopperApplication( this.options.launcherPath, signal, ); if (!prepared) return err(new HopperCancelledError()); const linuxDemo = linuxDemoLaunch( this.options, session, argumentsForTarget, display.strategy, ); const started = await launchHopperProcess({ options: this.options, session, bootstrapPath, ownsProcessLifetime, argumentsForTarget, linuxDemo, signal, }); if (started === null) return err(new HopperCancelledError()); const cleanup = () => cleanupOwnedProcessGroup(started.ownership).finally(() => lease?.release(), ); const ownership = { run_id: session.runId, pid: started.ownership.leaderPid, process_group_id: started.ownership.leaderPid, parent_pid: process.pid, launcher: linuxDemo?.command ?? this.options.launcherPath, created_at: new Date().toISOString(), }; try { await writeFileAtomic( join(session.directory, "ownership.json"), `${JSON.stringify(ownership)}\n`, { encoding: "utf8", mode: 0o600 }, ); } catch (cause: unknown) { await cleanupOwnedProcessGroup(started.ownership); return err(new HopperStartError({ cause })); } return ok({ process: started.process, ownsProcessLifetime: true, ownership: started.ownership, shutdownMode: ownsProcessLifetime ? "process-cleanup" : "bridge-request", cleanup, }); } catch (cause: unknown) { return err(hopperLaunchFailure(cause, signal)); } } async #acquireTargetLease( runId: string, ): Promise> { if ((this.dependencies.platform ?? process.platform) !== "darwin") return ok(undefined); try { const acquisition = await ( this.dependencies.acquireTargetLease ?? acquireHopperTargetLease )({ targetPath: this.options.targetPath, targetKind: this.options.targetKind, loaderArgs: this.options.loaderArgs, runId, }); if (!acquisition.acquired) return err( new HopperStartError({ ownerRunId: acquisition.owner.runId, userMessage: `This Hopper target is already open in REA session ${acquisition.owner.runId}. ` + "Use that REA session or close it before opening this target again.", }), ); return ok(acquisition.lease); } catch (cause: unknown) { return err(new HopperStartError({ cause })); } } async #writeBootstrap( session: BridgeSession, ownsProcessLifetime: boolean, ): Promise> { const bootstrapPath = `${session.directory}/bootstrap.py`; try { await writeFile( bootstrapPath, bridgeBootstrapSource(session, this.options, ownsProcessLifetime), { encoding: "utf8", mode: 0o600 }, ); await chmod(bootstrapPath, 0o600); return ok(bootstrapPath); } catch (cause: unknown) { return err(new HopperStartError({ cause })); } } async #privateDisplay(signal: AbortSignal | undefined): Promise< | { readonly ok: true; readonly strategy: LinuxPrivateDisplayRunnableStrategy | undefined; } | { readonly ok: false; readonly error: HopperProcessError | HopperCancelledError; } > { if (!usesLinuxDemo(this.options)) return { ok: true, strategy: undefined }; const selection = await ( this.dependencies.selectPrivateDisplay ?? selectLinuxPrivateDisplayStrategy )({ helperPath: this.options.demoHelperPath, ...(signal === undefined ? {} : { signal }), }); if (signal?.aborted === true) return { ok: false, error: new HopperCancelledError() }; return selection.ok ? { ok: true, strategy: selection.strategy } : { ok: false, error: new HopperProcessError( selection.exitCode, selection.diagnostic, ), }; } } const bridgeBootstrapSource = ( session: BridgeSession, options: SharedHopperApplicationLauncherOptions, ownsProcessLifetime: boolean, ): string => [ `REA_SOCKET = ${JSON.stringify(session.socketPath)}`, `REA_TOKEN = ${JSON.stringify(session.token)}`, `REA_RUN_ID = ${JSON.stringify(session.runId)}`, `REA_TARGET_PATH = ${JSON.stringify(options.targetPath)}`, `REA_OWNS_PROCESS_LIFETIME = ${ownsProcessLifetime ? "True" : "False"}`, `exec(compile(open(${JSON.stringify(options.bridgeScriptPath)}, 'rb').read(), ${JSON.stringify(options.bridgeScriptPath)}, 'exec'))`, "", ].join("\n"); const launchHopperProcess = async (input: { readonly options: HopperApplicationLauncherOptions; readonly session: BridgeSession; readonly bootstrapPath: string; readonly ownsProcessLifetime: boolean; readonly argumentsForTarget: readonly string[]; readonly linuxDemo: ReturnType; readonly signal: AbortSignal | undefined; }): Promise> | null> => { const ownershipCommand = input.linuxDemo?.ownershipCommand ?? input.options.launcherPath; const spawn = (arguments_: readonly string[]) => spawnOwnedProviderProcess({ command: input.options.launcherPath, arguments: arguments_, runId: input.session.runId, expectedCommand: ownershipCommand, }); if (input.linuxDemo !== undefined) return spawnOwnedProviderProcess({ command: input.linuxDemo.command, arguments: input.linuxDemo.args, runId: input.session.runId, expectedCommand: ownershipCommand, }); return spawn(input.argumentsForTarget); }; export const linuxDemoLaunch = ( options: HopperApplicationLauncherOptions, session: BridgeSession, hopperArgs: readonly string[], strategy: LinuxPrivateDisplayRunnableStrategy | undefined, ): | { readonly command: string; readonly args: readonly string[]; readonly ownershipCommand: string; } | undefined => { if (!usesLinuxDemo(options) || options.demoHelperPath === undefined) return undefined; const helperArguments = [ options.demoHelperPath, "--strategy", strategy ?? "direct", ...(strategy === "user-mount-namespace" ? ["--mount-private-x11"] : []), "--hopper", options.launcherPath, "--socket", session.socketPath, "--", options.launcherPath, ...hopperArgs, ]; if (strategy === "user-mount-namespace") return { command: "/usr/bin/unshare", ownershipCommand: "/usr/bin/python3", args: [ "--user", "--map-root-user", "--mount", "--propagation", "private", "/usr/bin/python3", ...helperArguments, ], }; return { command: "/usr/bin/python3", ownershipCommand: "/usr/bin/python3", args: helperArguments, }; }; const hopperLaunchFailure = ( cause: unknown, signal: AbortSignal | undefined, ): HopperCancelledError | HopperStartError => signal?.aborted === true ? new HopperCancelledError() : new HopperStartError({ cause }); /** Select the version-pinned adapter from the caller's explicit launch mode. */ export const usesLinuxDemo = ( options: HopperApplicationLauncherOptions, ): options is HopperApplicationLauncherOptions & { readonly launchMode: "verified_linux_demo"; readonly demoHelperPath: string; } => options.launchMode === "verified_linux_demo"; const prepareHopperApplication = async ( launcherPath: string, signal?: AbortSignal, ): Promise => { const appBundle = hopperApplicationBundle(launcherPath); if (appBundle === undefined) return signal?.aborted !== true; const executablePath = join(appBundle, "Contents/MacOS/Hopper Disassembler"); if (await processIsRunning(executablePath)) return signal?.aborted !== true; // This reduces activation when Hopper is cold, but the vendor launcher that // follows may still activate its window. See HopperApplicationLauncher. await execFileAsync("/usr/bin/open", [ "--hide", "--background", "-a", appBundle, ]); return ( (await waitForAbortableDelay(HOPPER_BACKGROUND_STARTUP_MS, signal)) === "elapsed" ); }; const hopperApplicationBundle = (launcherPath: string): string | undefined => { if (basename(launcherPath) !== "hopper") return undefined; const candidate = dirname(dirname(dirname(launcherPath))); return extname(candidate) === ".app" ? candidate : undefined; }; const processIsRunning = async (executablePath: string): Promise => { try { const processes = await execFileOutput("/bin/ps", [ "-ax", "-o", "command=", ]); return processes.stdout .split("\n") .some((command) => command.trim() === executablePath); } catch { return false; } };