prismcast 1.10.0 → 1.10.2

package/dist/identity.js

@@ -0,0 +1,19 @@
+/* Copyright(C) 2024-2026, HJD (https://github.com/hjdhjd). All rights reserved.
+ *
+ * identity.ts: Project-wide identity constants for PrismCast.
+ */
+/* This module is the single source of truth for the values other modules need to refer to PrismCast by name: the reverse-DNS service identifier launchd plists
+ * and systemd units carry, and the human-readable product name UI surfaces display. It sits at the root of src/ - below config, utils, service, and every other
+ * subsystem - because both the path-resolution layer (config/paths.ts, which uses SERVICE_ID in the macOS LaunchAgents path) and the service-generation layer
+ * (service/generators.ts, which embeds both values in plist and unit files) consume it. Placing it inside either of those subsystems would force the other to
+ * import sideways across a boundary it otherwise respects; lifting it to a dedicated root-level identity module preserves the layering and gives the constants
+ * a home that names what they are rather than where they happened to first be used.
+ */
+// The reverse-DNS service identifier. macOS launchd uses this for the bundle name, the LaunchAgents plist file name, and the Label key inside the plist itself.
+// Linux systemd and Windows Task Scheduler do not require reverse-DNS form, but the generators still quote this value in the unit/task definitions so users see
+// a consistent identifier across platforms when inspecting or removing the installed service.
+export const SERVICE_ID = "com.github.hjdhjd.prismcast";
+// The human-readable product name. Surfaced in UI labels, in the service-install command output, and as the display name on platforms whose service managers
+// distinguish "internal identifier" from "shown name" (Windows Task Scheduler being the clearest example).
+export const SERVICE_NAME = "PrismCast";
+//# sourceMappingURL=identity.js.map

package/dist/identity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity.js","sourceRoot":"","sources":["../src/identity.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;GAMG;AAEH,gKAAgK;AAChK,gKAAgK;AAChK,8FAA8F;AAC9F,MAAM,CAAC,MAAM,UAAU,GAAG,6BAA6B,CAAC;AAExD,6JAA6J;AAC7J,2GAA2G;AAC3G,MAAM,CAAC,MAAM,YAAY,GAAG,WAAW,CAAC"}

package/dist/routes/cdp.d.ts

@@ -0,0 +1,171 @@
+import type { Browser } from "puppeteer-core";
+import type { Express } from "express";
+import type { Server as HttpServer } from "node:http";
+import { WebSocket } from "ws";
+/**
+ * Per-WebSocket CDP proxy state. One instance per attached client. Owns the browser-level CDPSession, the per-target sub-session map, and the lifecycle
+ * subscriptions to the Browser. Cleans up on WS close, target destruction, or browser disconnect. Exported for unit testing - production callers receive
+ * instances via the upgrade handler and do not construct them directly.
+ */
+export declare class CdpProxySession {
+    private browserSession;
+    private connection;
+    private readonly sessions;
+    private readonly sessionToTargetId;
+    private readonly originalEmits;
+    private nextSessionSerial;
+    private discoverTargets;
+    private autoAttach;
+    private attached;
+    private onBrowserDisconnect;
+    private readonly ws;
+    private readonly browser;
+    constructor(ws: WebSocket, browser: Browser);
+    /**
+     * Initializes the per-connection CDP plumbing: registers the WebSocket lifecycle handlers, subscribes to the browser's disconnect event, opens a browser-level
+     * CDPSession, captures the underlying Connection, and subscribes to CDP target events. Any failure during async setup is caught by the WS close handler
+     * (registered first), which fires when `closeWith()` closes the socket and routes cleanup through the same path the happy-path teardown takes. This invariant
+     * - lifecycle handlers wired before any async operation that can fail - is what guarantees the session is torn down (including its disconnect listener)
+     * regardless of where setup aborts. Handler bodies are null-safe so an early message arriving before browserSession is set produces a clean error frame rather
+     * than a crash.
+     */
+    start(): Promise<void>;
+    /**
+     * Closes the WS with a code/reason and triggers cleanup. Safe to call when the WS is already closed.
+     * @param code - WebSocket close code (1000 normal, 1001 going-away, 1011 internal-error).
+     * @param reason - Human-readable reason.
+     */
+    closeWith(code: number, reason: string): void;
+    /**
+     * Handles a CDP message received over the WebSocket. Parses the JSON, dispatches to the browser-level or target-level handler, and forwards the response.
+     * Malformed JSON is silently dropped (the wire protocol has no error frame for that case at the client's level).
+     * @param data - The raw WebSocket message data.
+     */
+    private handleClientMessage;
+    /**
+     * Dispatches a browser-level CDP command. Intercepts the Target domain to synthesize its semantics on top of Puppeteer's Browser API; passes everything else
+     * through to the browser session.
+     * @param msg - The parsed CDP request.
+     */
+    private handleBrowserMessage;
+    /**
+     * Dispatches a message addressed to a specific sub-session. Looks up the CDPSession by synthetic sessionId and forwards. Unknown sessionId yields a CDP error
+     * response so the client sees a clean failure rather than silently dropping.
+     * @param msg - The parsed CDP request with a sessionId.
+     */
+    private handleTargetMessage;
+    /**
+     * Forwards a CDP command to a session and sends the response (or error) back to the client. The sessionId on the response is the one the client provided so
+     * the client can correlate.
+     * @param msg - The parsed CDP request.
+     * @param session - The CDP session to forward to.
+     */
+    private passthrough;
+    /**
+     * Handles Target.setDiscoverTargets. When enabled, emits Target.targetCreated for every existing target so the client's view of the world matches Chrome's;
+     * targetcreated / targetdestroyed events thereafter flow via the Browser event subscriptions.
+     * @param msg - The parsed CDP request.
+     */
+    private handleSetDiscoverTargets;
+    /**
+     * Handles Target.setAutoAttach. When enabled, creates a per-target CDPSession for every existing target, generates a synthetic sessionId, and emits
+     * Target.attachedToTarget for each. Subsequent new targets attach via the targetcreated lifecycle hook.
+     * @param msg - The parsed CDP request.
+     */
+    private handleSetAutoAttach;
+    /**
+     * Handles Target.attachToTarget. Looks up the target's info via the browser session, creates a Puppeteer CDPSession via Connection.createSession (the public
+     * API for attaching to a target by id), generates a synthetic sessionId, and returns it. The client uses that sessionId for subsequent messages.
+     * @param msg - The parsed CDP request.
+     */
+    private handleAttachToTarget;
+    /**
+     * Attaches to a target given its TargetInfo: creates a Puppeteer CDPSession via Connection.createSession, generates a synthetic sessionId, wires event
+     * forwarding, and optionally emits Target.attachedToTarget for the client. Returns the sessionId so callers (manual attach via Target.attachToTarget) can
+     * include it in their response.
+     * @param targetInfo - The CDP TargetInfo identifying the target.
+     * @param options - emitEvent: whether to emit Target.attachedToTarget after attach (defaults to true; manual attach sets false and returns the sessionId via
+     *                  the original response).
+     * @returns The synthetic sessionId for the newly-attached session.
+     */
+    private attachToTargetInfo;
+    /**
+     * Handles Target.detachFromTarget. Looks up the session by sessionId, detaches it, emits Target.detachedFromTarget, and removes from the map.
+     * @param msg - The parsed CDP request.
+     */
+    private handleDetachFromTarget;
+    /**
+     * Detaches a sub-session by its synthetic sessionId, restoring the patched emit, calling CDPSession.detach() (best-effort - the session may already be gone if
+     * the target closed), and emitting Target.detachedFromTarget so the client's view is consistent.
+     * @param sessionId - The synthetic sessionId.
+     */
+    private detachSessionById;
+    /**
+     * Handles the CDP `Target.targetCreated` event emitted by the browser session. When autoAttach is on, mints a Puppeteer CDPSession for the new target and emits
+     * a synthetic Target.attachedToTarget to the client. Whether the client also sees the Target.targetCreated event is decided by the wildcard forwarder (which
+     * gates Target.* events on this.discoverTargets).
+     * @param event - The CDP event payload.
+     */
+    private handleCdpTargetCreated;
+    /**
+     * Handles the CDP `Target.targetDestroyed` event emitted by the browser session. Detaches every sub-session attached to this targetId and emits the
+     * corresponding Target.detachedFromTarget events. The targetId on the CDP event matches exactly what we stored in sessionToTargetId at attach time, so there is
+     * no fuzzy matching - this is the lookup the Puppeteer-level targetdestroyed event could not give us.
+     * @param event - The CDP event payload.
+     */
+    private handleCdpTargetDestroyed;
+    /**
+     * Attaches a wildcard event listener to a CDPSession. Each CDP-domain event (matched by the "Domain.event" naming pattern - uppercase first letter, dot,
+     * lowercase next letter) is forwarded to the WS client after the session's own listeners have run, so any internal state mutation (e.g. cleanup driven by
+     * Target.targetDestroyed) is settled before the client sees the event. Target.* events are gated on this.discoverTargets so a client that has not subscribed
+     * to the Target domain does not receive its events even though our internal subscription stays on.
+     *
+     * Implementation note. CDPSession exposes no public "subscribe to every event" hook, so we monkey-patch the EventEmitter.emit method. The patch saves the
+     * original so detachEventListener can restore it cleanly. Order of operations inside the patch is: dispatch through original first (specific listeners fire,
+     * including the internal Target.* handlers we registered), then forward to the client. This ordering avoids the race where the client receives an event tied
+     * to state we haven't yet cleaned up.
+     *
+     * @param session - The CDP session to monitor.
+     * @param sessionId - The synthetic sessionId to include in the forwarded events (null for browser-level events).
+     */
+    private attachEventListener;
+    /**
+     * Restores the original emit on a session, undoing attachEventListener. Called on detach / cleanup.
+     * @param session - The CDP session whose emit to restore.
+     */
+    private detachEventListener;
+    /**
+     * Sends a CDP wire response back to the client.
+     * @param response - The response object.
+     */
+    private sendResponse;
+    /**
+     * Sends a CDP wire event back to the client.
+     * @param event - The event object.
+     */
+    private sendEvent;
+    /**
+     * Serializes a frame and writes it to the WS, swallowing errors that arise from a closed socket. We do not retry; if the WS is closed, the proxy session is
+     * already on its way to cleanup.
+     * @param frame - The frame to send.
+     */
+    private sendRaw;
+    /**
+     * Detaches every sub-session, restores patched emits, and unsubscribes from the browser-disconnect event. Safe to call multiple times: detach of an
+     * already-detached CDPSession is a no-op, and the disconnect-listener field is cleared after the first removal so a repeat call is a no-op too. Triggered by
+     * WS close, WS error, or closeWith().
+     */
+    cleanup(): Promise<void>;
+}
+/**
+ * Configures the /cdp/json/version, /cdp/json, and /cdp/json/list discovery endpoints on the Express app. Each handler checks isCategoryEnabled("cdp") at request
+ * time and returns 404 when CDP is disabled, so the surface appears and disappears in sync with the toggle in /debug without requiring a restart.
+ * @param app - The Express application.
+ */
+export declare function setupCdpEndpoint(app: Express): void;
+/**
+ * Attaches the WebSocket upgrade handler for /cdp/devtools/* paths to the given HTTP server. Called from startServer after app.listen() returns the server.
+ * Upgrades for paths outside /cdp/devtools/ are ignored (left to any other upgrade handler).
+ * @param server - The Node HTTP server.
+ */
+export declare function attachCdpUpgradeHandler(server: HttpServer): void;