@lhremote/core 0.0.0 → 0.2.0

package/dist/services/account-resolution.test.js

@@ -0,0 +1,91 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (C) 2026 Oleksii PELYKH
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+vi.mock("./launcher.js", () => ({
+    LauncherService: vi.fn(),
+}));
+import { LinkedHelperNotRunningError } from "./errors.js";
+import { LauncherService } from "./launcher.js";
+import { AccountResolutionError, resolveAccount } from "./account-resolution.js";
+const mockedLauncherService = vi.mocked(LauncherService);
+function mockLauncher(overrides = {}) {
+    const disconnect = vi.fn();
+    mockedLauncherService.mockImplementation(function () {
+        return {
+            connect: vi.fn().mockResolvedValue(undefined),
+            disconnect,
+            listAccounts: vi.fn().mockResolvedValue([]),
+            ...overrides,
+        };
+    });
+    return { disconnect };
+}
+describe("resolveAccount", () => {
+    beforeEach(() => {
+        vi.clearAllMocks();
+    });
+    afterEach(() => {
+        vi.restoreAllMocks();
+    });
+    it("returns the account ID when exactly one account exists", async () => {
+        mockLauncher({
+            listAccounts: vi.fn().mockResolvedValue([
+                { id: 42, liId: 100, name: "Alice", email: "alice@test.com" },
+            ]),
+        });
+        const id = await resolveAccount(9222);
+        expect(id).toBe(42);
+        expect(mockedLauncherService).toHaveBeenCalledWith(9222, undefined);
+    });
+    it("throws AccountResolutionError with reason 'no-accounts' when no accounts exist", async () => {
+        mockLauncher({
+            listAccounts: vi.fn().mockResolvedValue([]),
+        });
+        await expect(resolveAccount(9222)).rejects.toThrow(AccountResolutionError);
+        await expect(resolveAccount(9222)).rejects.toMatchObject({
+            reason: "no-accounts",
+        });
+    });
+    it("throws AccountResolutionError with reason 'multiple-accounts' when multiple accounts exist", async () => {
+        mockLauncher({
+            listAccounts: vi.fn().mockResolvedValue([
+                { id: 1, liId: 100, name: "Alice" },
+                { id: 2, liId: 200, name: "Bob" },
+            ]),
+        });
+        await expect(resolveAccount(9222)).rejects.toThrow(AccountResolutionError);
+        await expect(resolveAccount(9222)).rejects.toMatchObject({
+            reason: "multiple-accounts",
+        });
+    });
+    it("propagates CDP connection failure from launcher.connect()", async () => {
+        mockLauncher({
+            connect: vi.fn().mockRejectedValue(new LinkedHelperNotRunningError(9222)),
+        });
+        await expect(resolveAccount(9222)).rejects.toThrow(LinkedHelperNotRunningError);
+    });
+    it("calls disconnect in the finally block on success", async () => {
+        const { disconnect } = mockLauncher({
+            listAccounts: vi.fn().mockResolvedValue([
+                { id: 1, liId: 100, name: "Alice" },
+            ]),
+        });
+        await resolveAccount(9222);
+        expect(disconnect).toHaveBeenCalledOnce();
+    });
+    it("calls disconnect in the finally block on AccountResolutionError", async () => {
+        const { disconnect } = mockLauncher({
+            listAccounts: vi.fn().mockResolvedValue([]),
+        });
+        await expect(resolveAccount(9222)).rejects.toThrow(AccountResolutionError);
+        expect(disconnect).toHaveBeenCalledOnce();
+    });
+    it("calls disconnect in the finally block on connection failure", async () => {
+        const { disconnect } = mockLauncher({
+            connect: vi.fn().mockRejectedValue(new LinkedHelperNotRunningError(9222)),
+        });
+        await expect(resolveAccount(9222)).rejects.toThrow(LinkedHelperNotRunningError);
+        expect(disconnect).toHaveBeenCalledOnce();
+    });
+});
+//# sourceMappingURL=account-resolution.test.js.map

package/dist/services/account-resolution.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"account-resolution.test.js","sourceRoot":"","sources":["../../src/services/account-resolution.test.ts"],"names":[],"mappings":"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"}

package/dist/services/app.d.ts

@@ -0,0 +1,62 @@
+export interface AppServiceOptions {
+    /** Delay in ms after spawn before checking if the app is reachable (default 3000). */
+    launchProbeDelay?: number;
+}
+/**
+ * Manages the LinkedHelper application process lifecycle.
+ *
+ * Provides methods to launch, quit, and probe the LinkedHelper
+ * Electron application.  When no explicit CDP port is provided,
+ * a free port is selected automatically at launch time.
+ */
+export declare class AppService {
+    private assignedPort;
+    private childProcess;
+    private readonly launchProbeDelay;
+    /**
+     * @param cdpPort - Explicit CDP port.  When omitted, `launch()` will
+     *   select a free port automatically via `get-port`.
+     * @param options - Additional configuration options.
+     */
+    constructor(cdpPort?: number, options?: AppServiceOptions);
+    /**
+     * The CDP port currently in use.
+     *
+     * @throws {Error} if neither an explicit port was provided nor
+     *   `launch()` has been called yet.
+     */
+    get cdpPort(): number;
+    /**
+     * Launch the LinkedHelper application with CDP enabled.
+     *
+     * If no CDP port was specified in the constructor, a free port
+     * is selected automatically.
+     *
+     * @throws {AppNotFoundError} if the binary cannot be found.
+     * @throws {AppLaunchError} if the process fails to start.
+     */
+    launch(): Promise<void>;
+    /**
+     * Quit the LinkedHelper application.
+     *
+     * When a child process handle is available, sends `SIGTERM` and waits
+     * for the process to exit.  If it does not exit within
+     * {@link QUIT_GRACEFUL_TIMEOUT}, escalates to `SIGKILL`.
+     *
+     * When no child process handle is available (app was launched
+     * externally), attempts to close via CDP.
+     */
+    quit(): Promise<void>;
+    /**
+     * Check whether LinkedHelper is running by probing its CDP endpoint.
+     */
+    isRunning(): Promise<boolean>;
+    /**
+     * Locate the LinkedHelper binary for the current platform.
+     *
+     * @throws {AppNotFoundError} if the binary does not exist at the
+     *   expected location.
+     */
+    static findBinary(): string;
+}
+//# sourceMappingURL=app.d.ts.map

package/dist/services/app.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../../src/services/app.ts"],"names":[],"mappings":"AAqBA,MAAM,WAAW,iBAAiB;IAChC,sFAAsF;IACtF,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;GAMG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,YAAY,CAAgB;IACpC,OAAO,CAAC,YAAY,CAA6B;IACjD,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAE1C;;;;OAIG;gBACS,OAAO,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,iBAAiB;IAKzD;;;;;OAKG;IACH,IAAI,OAAO,IAAI,MAAM,CAKpB;IAED;;;;;;;;OAQG;IACG,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IA0C7B;;;;;;;;;OASG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAkC3B;;OAEG;IACG,SAAS,IAAI,OAAO,CAAC,OAAO,CAAC;IAYnC;;;;;OAKG;IACH,MAAM,CAAC,UAAU,IAAI,MAAM;CAW5B"}

package/dist/services/app.js

@@ -0,0 +1,200 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (C) 2026 Oleksii PELYKH
+import { spawn } from "node:child_process";
+import { accessSync, constants } from "node:fs";
+import { join } from "node:path";
+import getPort from "get-port";
+import { discoverTargets } from "../cdp/index.js";
+import { AppLaunchError, AppNotFoundError } from "./errors.js";
+/** Default delay after spawn before checking if the app is reachable (ms). */
+const DEFAULT_LAUNCH_PROBE_DELAY = 3000;
+/** Maximum time to wait for the process to exit after SIGTERM (ms). */
+const QUIT_GRACEFUL_TIMEOUT = 10_000;
+/** Maximum time to wait for the process to exit after SIGKILL (ms). */
+const QUIT_FORCE_TIMEOUT = 5_000;
+/**
+ * Manages the LinkedHelper application process lifecycle.
+ *
+ * Provides methods to launch, quit, and probe the LinkedHelper
+ * Electron application.  When no explicit CDP port is provided,
+ * a free port is selected automatically at launch time.
+ */
+export class AppService {
+    assignedPort;
+    childProcess = null;
+    launchProbeDelay;
+    /**
+     * @param cdpPort - Explicit CDP port.  When omitted, `launch()` will
+     *   select a free port automatically via `get-port`.
+     * @param options - Additional configuration options.
+     */
+    constructor(cdpPort, options) {
+        this.assignedPort = cdpPort ?? null;
+        this.launchProbeDelay = options?.launchProbeDelay ?? DEFAULT_LAUNCH_PROBE_DELAY;
+    }
+    /**
+     * The CDP port currently in use.
+     *
+     * @throws {Error} if neither an explicit port was provided nor
+     *   `launch()` has been called yet.
+     */
+    get cdpPort() {
+        if (this.assignedPort === null) {
+            throw new Error("CDP port not yet assigned — call launch() first or provide a port to the constructor");
+        }
+        return this.assignedPort;
+    }
+    /**
+     * Launch the LinkedHelper application with CDP enabled.
+     *
+     * If no CDP port was specified in the constructor, a free port
+     * is selected automatically.
+     *
+     * @throws {AppNotFoundError} if the binary cannot be found.
+     * @throws {AppLaunchError} if the process fails to start.
+     */
+    async launch() {
+        if (this.assignedPort !== null && await this.isRunning()) {
+            return;
+        }
+        if (this.assignedPort === null) {
+            this.assignedPort = await getPort();
+        }
+        const binary = AppService.findBinary();
+        const args = [`--remote-debugging-port=${String(this.assignedPort)}`];
+        const child = spawn(binary, args, {
+            detached: true,
+            stdio: "ignore",
+        });
+        child.unref();
+        // Wait for an early error (e.g. ENOENT from spawn) before probing
+        await new Promise((resolve, reject) => {
+            const onError = (err) => {
+                cleanup();
+                reject(new AppLaunchError(`Failed to launch LinkedHelper: ${err.message}`, { cause: err }));
+            };
+            const timer = setTimeout(() => {
+                cleanup();
+                resolve();
+            }, this.launchProbeDelay);
+            function cleanup() {
+                child.removeListener("error", onError);
+                clearTimeout(timer);
+            }
+            child.on("error", onError);
+        });
+        this.childProcess = child;
+    }
+    /**
+     * Quit the LinkedHelper application.
+     *
+     * When a child process handle is available, sends `SIGTERM` and waits
+     * for the process to exit.  If it does not exit within
+     * {@link QUIT_GRACEFUL_TIMEOUT}, escalates to `SIGKILL`.
+     *
+     * When no child process handle is available (app was launched
+     * externally), attempts to close via CDP.
+     */
+    async quit() {
+        if (this.childProcess) {
+            const child = this.childProcess;
+            this.childProcess = null;
+            child.kill("SIGTERM");
+            const exited = await waitForExit(child, QUIT_GRACEFUL_TIMEOUT);
+            if (!exited) {
+                child.kill("SIGKILL");
+                await waitForExit(child, QUIT_FORCE_TIMEOUT);
+            }
+            return;
+        }
+        if (this.assignedPort === null) {
+            return;
+        }
+        // Fallback: close via CDP Browser.close
+        try {
+            const targets = await discoverTargets(this.assignedPort);
+            const first = targets[0];
+            if (first) {
+                await fetch(`http://127.0.0.1:${String(this.assignedPort)}/json/close/${first.id}`);
+            }
+        }
+        catch {
+            // App may already be closed
+        }
+    }
+    /**
+     * Check whether LinkedHelper is running by probing its CDP endpoint.
+     */
+    async isRunning() {
+        if (this.assignedPort === null) {
+            return false;
+        }
+        try {
+            await discoverTargets(this.assignedPort);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Locate the LinkedHelper binary for the current platform.
+     *
+     * @throws {AppNotFoundError} if the binary does not exist at the
+     *   expected location.
+     */
+    static findBinary() {
+        const envPath = process.env["LINKEDHELPER_PATH"];
+        if (envPath) {
+            assertFileExists(envPath);
+            return envPath;
+        }
+        const path = getDefaultBinaryPath();
+        assertFileExists(path);
+        return path;
+    }
+}
+function getDefaultBinaryPath() {
+    switch (process.platform) {
+        case "darwin":
+            return "/Applications/linked-helper.app/Contents/MacOS/linked-helper";
+        case "win32":
+            return join(process.env["LOCALAPPDATA"] ?? join(process.env["USERPROFILE"] ?? "C:\\Users\\Default", "AppData", "Local"), "Programs", "linked-helper", "linked-helper.exe");
+        default:
+            return "/opt/linked-helper/linked-helper";
+    }
+}
+/**
+ * Wait for a child process to exit, with a timeout.
+ *
+ * @returns `true` if the process exited within the timeout, `false` otherwise.
+ */
+function waitForExit(child, timeout) {
+    if (child.exitCode !== null) {
+        return Promise.resolve(true);
+    }
+    return new Promise((resolve) => {
+        const timer = setTimeout(() => {
+            cleanup();
+            resolve(false);
+        }, timeout);
+        const onExit = () => {
+            cleanup();
+            resolve(true);
+        };
+        function cleanup() {
+            child.removeListener("exit", onExit);
+            clearTimeout(timer);
+        }
+        child.on("exit", onExit);
+    });
+}
+function assertFileExists(path) {
+    try {
+        accessSync(path, constants.X_OK);
+    }
+    catch {
+        throw new AppNotFoundError(`LinkedHelper binary not found at ${path}. Set LINKEDHELPER_PATH to override.`);
+    }
+}
+//# sourceMappingURL=app.js.map

package/dist/services/app.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"app.js","sourceRoot":"","sources":["../../src/services/app.ts"],"names":[],"mappings":"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"}

package/dist/services/app.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=app.test.d.ts.map

package/dist/services/app.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app.test.d.ts","sourceRoot":"","sources":["../../src/services/app.test.ts"],"names":[],"mappings":""}

package/dist/services/app.test.js

@@ -0,0 +1,267 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (C) 2026 Oleksii PELYKH
+import { spawn } from "node:child_process";
+import { accessSync } from "node:fs";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { AppLaunchError, AppNotFoundError } from "./errors.js";
+import { AppService } from "./app.js";
+vi.mock("node:child_process", () => ({
+    spawn: vi.fn(),
+}));
+vi.mock("node:fs", () => ({
+    accessSync: vi.fn(),
+    constants: { X_OK: 1 },
+}));
+vi.mock("../cdp/index.js", () => ({
+    discoverTargets: vi.fn(),
+}));
+vi.mock("get-port", () => ({
+    default: vi.fn(),
+}));
+import { discoverTargets } from "../cdp/index.js";
+import getPort from "get-port";
+const mockedSpawn = vi.mocked(spawn);
+const mockedAccessSync = vi.mocked(accessSync);
+const mockedDiscoverTargets = vi.mocked(discoverTargets);
+const mockedGetPort = vi.mocked(getPort);
+/** Use zero probe delay in tests to avoid 3s waits. */
+const FAST_OPTIONS = { launchProbeDelay: 0 };
+function makeMockChild() {
+    const listeners = new Map();
+    const child = {
+        unref: vi.fn(),
+        kill: vi.fn(),
+        on: vi.fn((event, handler) => {
+            if (!listeners.has(event))
+                listeners.set(event, new Set());
+            listeners.get(event).add(handler);
+            return child;
+        }),
+        removeListener: vi.fn((event, handler) => {
+            listeners.get(event)?.delete(handler);
+            return child;
+        }),
+        pid: 12345,
+        exitCode: null,
+    };
+    // Helper to simulate process exit from tests
+    child._emitExit = (code) => {
+        child.exitCode = code;
+        for (const handler of listeners.get("exit") ?? []) {
+            handler(code, null);
+        }
+    };
+    return child;
+}
+afterEach(() => {
+    vi.restoreAllMocks();
+    delete process.env["LINKEDHELPER_PATH"];
+});
+describe("AppService", () => {
+    describe("cdpPort getter", () => {
+        it("returns the explicit port when provided", () => {
+            const service = new AppService(9222);
+            expect(service.cdpPort).toBe(9222);
+        });
+        it("throws when no port assigned and launch() not called", () => {
+            const service = new AppService();
+            expect(() => service.cdpPort).toThrow(/call launch\(\) first/);
+        });
+    });
+    describe("findBinary", () => {
+        it("returns the darwin path on macOS", () => {
+            vi.stubGlobal("process", { ...process, platform: "darwin", env: {} });
+            mockedAccessSync.mockReturnValue(undefined);
+            const result = AppService.findBinary();
+            expect(result).toBe("/Applications/linked-helper.app/Contents/MacOS/linked-helper");
+        });
+        it("returns the win32 path on Windows", () => {
+            vi.stubGlobal("process", {
+                ...process,
+                platform: "win32",
+                env: { LOCALAPPDATA: "C:\\Users\\test\\AppData\\Local" },
+            });
+            mockedAccessSync.mockReturnValue(undefined);
+            const result = AppService.findBinary();
+            expect(result).toContain("linked-helper.exe");
+            expect(result).toContain("Local");
+        });
+        it("returns the linux path on Linux", () => {
+            vi.stubGlobal("process", { ...process, platform: "linux", env: {} });
+            mockedAccessSync.mockReturnValue(undefined);
+            const result = AppService.findBinary();
+            expect(result).toBe("/opt/linked-helper/linked-helper");
+        });
+        it("uses LINKEDHELPER_PATH env override", () => {
+            vi.stubGlobal("process", {
+                ...process,
+                platform: "darwin",
+                env: { LINKEDHELPER_PATH: "/custom/path/lh" },
+            });
+            mockedAccessSync.mockReturnValue(undefined);
+            const result = AppService.findBinary();
+            expect(result).toBe("/custom/path/lh");
+        });
+        it("throws AppNotFoundError when binary does not exist", () => {
+            vi.stubGlobal("process", { ...process, platform: "darwin", env: {} });
+            mockedAccessSync.mockImplementation(() => {
+                throw new Error("ENOENT");
+            });
+            expect(() => AppService.findBinary()).toThrow(AppNotFoundError);
+        });
+    });
+    describe("isRunning", () => {
+        it("returns true when CDP endpoint responds", async () => {
+            const service = new AppService(9222);
+            mockedDiscoverTargets.mockResolvedValue([]);
+            expect(await service.isRunning()).toBe(true);
+        });
+        it("returns false when CDP endpoint is unreachable", async () => {
+            const service = new AppService(9222);
+            mockedDiscoverTargets.mockRejectedValue(new Error("connection refused"));
+            expect(await service.isRunning()).toBe(false);
+        });
+        it("returns false when no port is assigned", async () => {
+            const service = new AppService();
+            expect(await service.isRunning()).toBe(false);
+        });
+    });
+    describe("launch", () => {
+        beforeEach(() => {
+            vi.stubGlobal("process", { ...process, platform: "darwin", env: {} });
+        });
+        it("skips launch if already running with explicit port", async () => {
+            const service = new AppService(9222, FAST_OPTIONS);
+            mockedDiscoverTargets.mockResolvedValue([]);
+            await service.launch();
+            expect(mockedSpawn).not.toHaveBeenCalled();
+        });
+        it("spawns the binary with explicit CDP port argument", async () => {
+            const service = new AppService(9222, FAST_OPTIONS);
+            mockedDiscoverTargets.mockRejectedValue(new Error("not running"));
+            mockedAccessSync.mockReturnValue(undefined);
+            const child = makeMockChild();
+            mockedSpawn.mockReturnValue(child);
+            await service.launch();
+            expect(mockedSpawn).toHaveBeenCalledWith("/Applications/linked-helper.app/Contents/MacOS/linked-helper", ["--remote-debugging-port=9222"], { detached: true, stdio: "ignore" });
+            expect(child.unref).toHaveBeenCalled();
+        });
+        it("selects a free port via get-port when no port provided", async () => {
+            const service = new AppService(undefined, FAST_OPTIONS);
+            mockedGetPort.mockResolvedValue(54321);
+            mockedAccessSync.mockReturnValue(undefined);
+            const child = makeMockChild();
+            mockedSpawn.mockReturnValue(child);
+            await service.launch();
+            expect(mockedGetPort).toHaveBeenCalled();
+            expect(mockedSpawn).toHaveBeenCalledWith(expect.any(String), ["--remote-debugging-port=54321"], { detached: true, stdio: "ignore" });
+            expect(service.cdpPort).toBe(54321);
+        });
+        it("reuses assigned port on second launch() call", async () => {
+            const service = new AppService(undefined, FAST_OPTIONS);
+            mockedGetPort.mockResolvedValue(54321);
+            mockedAccessSync.mockReturnValue(undefined);
+            const child = makeMockChild();
+            mockedSpawn.mockReturnValue(child);
+            await service.launch();
+            expect(service.cdpPort).toBe(54321);
+            // Reset call counts for second launch assertions
+            mockedGetPort.mockClear();
+            mockedSpawn.mockClear();
+            // Second launch — port is already assigned, app reported as running
+            mockedDiscoverTargets.mockResolvedValue([]);
+            await service.launch();
+            // getPort must not be called again — port was already assigned
+            expect(mockedGetPort).not.toHaveBeenCalled();
+            // spawn must not be called again — app is already running
+            expect(mockedSpawn).not.toHaveBeenCalled();
+            expect(service.cdpPort).toBe(54321);
+        });
+        it("throws AppLaunchError on spawn error", async () => {
+            const service = new AppService(9222, FAST_OPTIONS);
+            mockedDiscoverTargets.mockRejectedValue(new Error("not running"));
+            mockedAccessSync.mockReturnValue(undefined);
+            const child = makeMockChild();
+            child.on.mockImplementation((event, handler) => {
+                if (event === "error") {
+                    queueMicrotask(() => handler(new Error("ENOENT")));
+                }
+                return child;
+            });
+            mockedSpawn.mockReturnValue(child);
+            await expect(service.launch()).rejects.toThrow(AppLaunchError);
+        });
+    });
+    describe("quit", () => {
+        beforeEach(() => {
+            vi.stubGlobal("process", { ...process, platform: "darwin", env: {} });
+        });
+        it("sends SIGTERM and waits for exit", async () => {
+            const service = new AppService(9222, FAST_OPTIONS);
+            mockedDiscoverTargets.mockRejectedValue(new Error("not running"));
+            mockedAccessSync.mockReturnValue(undefined);
+            const child = makeMockChild();
+            const emitExit = child._emitExit;
+            // Simulate process exiting shortly after SIGTERM
+            child.kill.mockImplementation(() => {
+                queueMicrotask(() => emitExit(0));
+            });
+            mockedSpawn.mockReturnValue(child);
+            await service.launch();
+            await service.quit();
+            expect(child.kill).toHaveBeenCalledWith("SIGTERM");
+        });
+        it("escalates to SIGKILL when process does not exit after SIGTERM", async () => {
+            vi.useFakeTimers({ shouldAdvanceTime: true });
+            const service = new AppService(9222, FAST_OPTIONS);
+            mockedDiscoverTargets.mockRejectedValue(new Error("not running"));
+            mockedAccessSync.mockReturnValue(undefined);
+            const child = makeMockChild();
+            const emitExit = child._emitExit;
+            let killCount = 0;
+            child.kill.mockImplementation(() => {
+                killCount++;
+                // Only exit on SIGKILL (second kill call)
+                if (killCount === 2) {
+                    queueMicrotask(() => emitExit(137));
+                }
+            });
+            mockedSpawn.mockReturnValue(child);
+            await service.launch();
+            const quitPromise = service.quit();
+            // Advance past the graceful timeout
+            await vi.advanceTimersByTimeAsync(11_000);
+            await quitPromise;
+            expect(child.kill).toHaveBeenCalledWith("SIGTERM");
+            expect(child.kill).toHaveBeenCalledWith("SIGKILL");
+            vi.useRealTimers();
+        });
+        it("falls back to CDP close when no spawned process", async () => {
+            const service = new AppService(9222);
+            mockedDiscoverTargets.mockResolvedValue([
+                {
+                    id: "T1",
+                    type: "page",
+                    title: "",
+                    url: "",
+                    description: "",
+                    devtoolsFrontendUrl: "",
+                },
+            ]);
+            const mockFetch = vi.fn().mockResolvedValue({ ok: true });
+            vi.stubGlobal("fetch", mockFetch);
+            await service.quit();
+            expect(mockFetch).toHaveBeenCalledWith("http://127.0.0.1:9222/json/close/T1");
+        });
+        it("does not throw when CDP close fails", async () => {
+            const service = new AppService(9222);
+            mockedDiscoverTargets.mockRejectedValue(new Error("not running"));
+            await expect(service.quit()).resolves.toBeUndefined();
+        });
+        it("does nothing when no port assigned and no child process", async () => {
+            const service = new AppService();
+            await expect(service.quit()).resolves.toBeUndefined();
+        });
+    });
+});
+//# sourceMappingURL=app.test.js.map