@page-scanner/cli 0.1.0

package/dist/daemon/state.js

@@ -0,0 +1,116 @@
+/**
+ * The daemon's record of itself, at `<configDir()>/daemon.json`.
+ *
+ * Every other process — a second `page-scanner scan`, the MCP server, a
+ * Claude Desktop bundle — finds the running daemon through this file and
+ * nothing else. There is no discovery: the RPC port is ephemeral and the
+ * bearer secret is regenerated per run, so the file is the only place either
+ * is written down. Mode 0600 for the same reason `config.json` is: the secret
+ * in it buys a scan of any tab the user has open. On Windows that mode is a
+ * no-op, as the README says.
+ *
+ * The file is deleted on a clean exit, but a daemon that is killed leaves it
+ * behind, so a reader must never trust it on its own. That is what the pid is
+ * for: `readDaemonState` reports a record whose process is gone as no record
+ * at all, and the caller starts a fresh daemon instead of posting RPC at a
+ * port nothing is listening on.
+ */
+import { chmodSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { configDir } from '../config.js';
+export function daemonStatePath() {
+    return join(configDir(), 'daemon.json');
+}
+export function daemonLogPath() {
+    return join(configDir(), 'daemon.log');
+}
+/** A port number as `listen` would have produced it, never 0: the daemon records what it bound. */
+function isPort(value) {
+    return typeof value === 'number' && Number.isInteger(value) && value > 0 && value <= 65535;
+}
+function isNonEmptyString(value) {
+    return typeof value === 'string' && value.length > 0;
+}
+/**
+ * Reads the record, or null if there is nothing usable to read: no file, bad
+ * JSON, a field missing or of the wrong type, or a pid that no longer exists.
+ * It never throws — it is on the path every command takes before it can do
+ * anything, and a corrupt file there should cost a restart, not a crash.
+ */
+export function readDaemonState() {
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(daemonStatePath(), 'utf8'));
+    }
+    catch {
+        return null;
+    }
+    if (typeof parsed !== 'object' || parsed === null)
+        return null;
+    const record = parsed;
+    const { pid, rpcPort, secret, bridgePort, version, startedAt } = record;
+    if (!isPort(rpcPort) || !isPort(bridgePort))
+        return null;
+    if (!isNonEmptyString(secret) || !isNonEmptyString(version))
+        return null;
+    if (typeof pid !== 'number' || !Number.isInteger(pid) || pid <= 0)
+        return null;
+    if (typeof startedAt !== 'number' || !Number.isFinite(startedAt))
+        return null;
+    // The liveness check comes last so a malformed file is rejected on its own
+    // terms rather than by signalling whatever the garbage in `pid` points at.
+    if (!processAlive(pid))
+        return null;
+    return { pid, rpcPort, secret, bridgePort, version, startedAt };
+}
+export function writeDaemonState(state) {
+    mkdirSync(configDir(), { recursive: true, mode: 0o700 });
+    // Written to one side and renamed over, because every other process reads
+    // this file while the daemon is coming up. `writeFileSync` truncates first,
+    // and a reader landing in that window parses an empty file and concludes
+    // there is no daemon; `rename` is atomic on the same filesystem, so a reader
+    // sees either the old record or the new one.
+    const temporary = `${daemonStatePath()}.tmp`;
+    writeFileSync(temporary, `${JSON.stringify(state, null, 2)}\n`, { mode: 0o600 });
+    // `writeFileSync`'s mode only applies when it creates the file, and a
+    // restart overwrites one the previous run left behind.
+    chmodSync(temporary, 0o600);
+    renameSync(temporary, daemonStatePath());
+}
+export function clearDaemonState() {
+    try {
+        rmSync(daemonStatePath(), { force: true });
+    }
+    catch {
+        // Deleting is housekeeping on the way out, and the exit it runs from
+        // matters more than the file. A record that survives is stale, not
+        // dangerous: `readDaemonState` drops it once the pid is gone.
+    }
+}
+/** The `code` of a Node system error, when that is what was thrown. */
+function errorCode(error) {
+    if (typeof error !== 'object' || error === null || !('code' in error))
+        return undefined;
+    return typeof error.code === 'string' ? error.code : undefined;
+}
+export function processAlive(pid) {
+    // `kill(2)` reads pid 0 as "every process in my own group" and a negative
+    // pid as a group id, both of which exist, so a record with a zeroed or
+    // corrupt pid would otherwise always report alive.
+    if (!Number.isInteger(pid) || pid <= 0)
+        return false;
+    try {
+        // Signal 0 delivers nothing; it runs the existence and permission checks
+        // and reports through errno.
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        // EPERM means the process is there and belongs to another user — alive,
+        // and the RPC secret will settle whether we may talk to it. ESRCH means
+        // there is no such process. Anything else leaves us unable to confirm a
+        // daemon we could use, which is the same thing as not having one.
+        return errorCode(error) === 'EPERM';
+    }
+}
+//# sourceMappingURL=state.js.map

package/dist/daemon/state.js.map

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

package/dist/errors.d.ts

@@ -0,0 +1,32 @@
+/**
+ * One error type, one exit code per class of failure.
+ *
+ * A script wrapping this CLI should not have to read the message to know what
+ * happened. The code says which of the handful of things went wrong, and
+ * `exitCodeFor` maps it onto the process exit status documented in the README.
+ */
+export declare const ERROR_CODES: readonly ["NOT_PAIRED", "NO_BROWSER", "AMBIGUOUS_BROWSER", "UNKNOWN_BROWSER", "BAD_REQUEST", "TIMEOUT", "BROWSER_GONE", "SCAN_FAILED", "DAEMON_FAILED", "PORT_IN_USE"];
+export type ErrorCode = (typeof ERROR_CODES)[number];
+export declare class PageScannerError extends Error {
+    readonly code: ErrorCode;
+    /** A second line of help, printed under the message. */
+    readonly hint: string | undefined;
+    constructor(code: ErrorCode, message: string, hint?: string);
+}
+export declare function isPageScannerError(value: unknown): value is PageScannerError;
+/**
+ * Turns whatever was thrown into a PageScannerError, so every exit goes
+ * through the same reporting path. An unrecognised failure is SCAN_FAILED
+ * rather than a crash: the caller still gets a code and a message.
+ */
+export declare function toPageScannerError(value: unknown): PageScannerError;
+/**
+ * 0  success
+ * 1  the browser was reached and the work failed
+ * 2  the arguments were wrong
+ * 3  no usable browser: none connected, several connected, or one named that is not
+ * 4  not paired
+ * 5  the daemon would not start
+ */
+export declare function exitCodeFor(code: ErrorCode): number;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,eAAO,MAAM,WAAW,wKAqBd,CAAC;AAEX,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,CAAC,CAAC;AAErD,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,wDAAwD;IACxD,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;gBAEtB,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM;CAM5D;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,gBAAgB,CAE5E;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,gBAAgB,CAInE;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,CAkBnD"}

package/dist/errors.js

@@ -0,0 +1,83 @@
+/**
+ * One error type, one exit code per class of failure.
+ *
+ * A script wrapping this CLI should not have to read the message to know what
+ * happened. The code says which of the handful of things went wrong, and
+ * `exitCodeFor` maps it onto the process exit status documented in the README.
+ */
+export const ERROR_CODES = [
+    /** No pairing on disk. Run `page-scanner pair`. */
+    'NOT_PAIRED',
+    /** Nothing connected, or nothing connected before `--wait` ran out. */
+    'NO_BROWSER',
+    /** Several browsers are connected and none was named. */
+    'AMBIGUOUS_BROWSER',
+    /** A browser was named and it is not connected. */
+    'UNKNOWN_BROWSER',
+    /** The arguments do not make sense. */
+    'BAD_REQUEST',
+    /** The browser accepted the request and never answered. */
+    'TIMEOUT',
+    /** The browser disconnected with the request still outstanding. */
+    'BROWSER_GONE',
+    /** The extension reported a failure. */
+    'SCAN_FAILED',
+    /** The daemon could not be started, or could not be reached once started. */
+    'DAEMON_FAILED',
+    /** Something already holds the bridge port. */
+    'PORT_IN_USE',
+];
+export class PageScannerError extends Error {
+    code;
+    /** A second line of help, printed under the message. */
+    hint;
+    constructor(code, message, hint) {
+        super(message);
+        this.name = 'PageScannerError';
+        this.code = code;
+        this.hint = hint;
+    }
+}
+export function isPageScannerError(value) {
+    return value instanceof PageScannerError;
+}
+/**
+ * Turns whatever was thrown into a PageScannerError, so every exit goes
+ * through the same reporting path. An unrecognised failure is SCAN_FAILED
+ * rather than a crash: the caller still gets a code and a message.
+ */
+export function toPageScannerError(value) {
+    if (isPageScannerError(value))
+        return value;
+    if (value instanceof Error)
+        return new PageScannerError('SCAN_FAILED', value.message);
+    return new PageScannerError('SCAN_FAILED', String(value));
+}
+/**
+ * 0  success
+ * 1  the browser was reached and the work failed
+ * 2  the arguments were wrong
+ * 3  no usable browser: none connected, several connected, or one named that is not
+ * 4  not paired
+ * 5  the daemon would not start
+ */
+export function exitCodeFor(code) {
+    switch (code) {
+        case 'BAD_REQUEST':
+            return 2;
+        case 'NO_BROWSER':
+        case 'AMBIGUOUS_BROWSER':
+        case 'UNKNOWN_BROWSER':
+            return 3;
+        case 'NOT_PAIRED':
+            return 4;
+        case 'DAEMON_FAILED':
+        case 'PORT_IN_USE':
+            return 5;
+        case 'TIMEOUT':
+        case 'BROWSER_GONE':
+        case 'SCAN_FAILED':
+            return 1;
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,CAAC,MAAM,WAAW,GAAG;IACzB,mDAAmD;IACnD,YAAY;IACZ,uEAAuE;IACvE,YAAY;IACZ,yDAAyD;IACzD,mBAAmB;IACnB,mDAAmD;IACnD,iBAAiB;IACjB,uCAAuC;IACvC,aAAa;IACb,2DAA2D;IAC3D,SAAS;IACT,mEAAmE;IACnE,cAAc;IACd,wCAAwC;IACxC,aAAa;IACb,6EAA6E;IAC7E,eAAe;IACf,+CAA+C;IAC/C,aAAa;CACL,CAAC;AAIX,MAAM,OAAO,gBAAiB,SAAQ,KAAK;IAChC,IAAI,CAAY;IACzB,wDAAwD;IAC/C,IAAI,CAAqB;IAElC,YAAY,IAAe,EAAE,OAAe,EAAE,IAAa;QACzD,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC;QAC/B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF;AAED,MAAM,UAAU,kBAAkB,CAAC,KAAc;IAC/C,OAAO,KAAK,YAAY,gBAAgB,CAAC;AAC3C,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAAC,KAAc;IAC/C,IAAI,kBAAkB,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IAC5C,IAAI,KAAK,YAAY,KAAK;QAAE,OAAO,IAAI,gBAAgB,CAAC,aAAa,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC;IACtF,OAAO,IAAI,gBAAgB,CAAC,aAAa,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;AAC5D,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,WAAW,CAAC,IAAe;IACzC,QAAQ,IAAI,EAAE,CAAC;QACb,KAAK,aAAa;YAChB,OAAO,CAAC,CAAC;QACX,KAAK,YAAY,CAAC;QAClB,KAAK,mBAAmB,CAAC;QACzB,KAAK,iBAAiB;YACpB,OAAO,CAAC,CAAC;QACX,KAAK,YAAY;YACf,OAAO,CAAC,CAAC;QACX,KAAK,eAAe,CAAC;QACrB,KAAK,aAAa;YAChB,OAAO,CAAC,CAAC;QACX,KAAK,SAAS,CAAC;QACf,KAAK,cAAc,CAAC;QACpB,KAAK,aAAa;YAChB,OAAO,CAAC,CAAC;IACb,CAAC;AACH,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The programmatic surface of the `@page-scanner/cli` package.
+ *
+ * Importing this does not load `ws`: the bridge runs in the daemon, which is
+ * a separate process. `@page-scanner/cli/daemon` is the entry point that starts
+ * one in-process, and it is the only one that pulls the WebSocket server in.
+ */
+export { listBrowsers, listTabs, pair, scan, status, stop, waitForBrowser, type CommonOptions, type PairResult, type ScanOptions, type ScanResult, type StatusReport, type TabsResult, } from './api.js';
+export { configDir, configPath, configFileIsOwnerOnly, ensureConfig, readConfig, DEFAULT_PORT, type PairingConfig, } from './config.js';
+export { exitCodeFor, isPageScannerError, toPageScannerError, PageScannerError, ERROR_CODES, type ErrorCode, } from './errors.js';
+export { resolveOutputPath, writeScanFile } from './output.js';
+export { connectDaemon, stopDaemon, DAEMON_START_TIMEOUT_MS, type ConnectOptions, type DaemonClient, } from './daemon/client.js';
+export { daemonLogPath, daemonStatePath, readDaemonState, type DaemonState, } from './daemon/state.js';
+export type { ConnectedBrowser } from './bridge/server.js';
+export { BRIDGE_PING_INTERVAL_MS, BRIDGE_PROTOCOL_VERSION, DEFAULT_PAGE_SIZE, EXPORT_FORMAT_IDS, PAGE_SIZE_IDS, VIDEO_HANDLINGS, type ExportFormatId, type PageSizeId, type TabSummary, type TruncationReport, type VideoHandling, type WindowSummary, } from './protocol.js';
+export { CLI_VERSION } from './version.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EACL,YAAY,EACZ,QAAQ,EACR,IAAI,EACJ,IAAI,EACJ,MAAM,EACN,IAAI,EACJ,cAAc,EACd,KAAK,aAAa,EAClB,KAAK,UAAU,EACf,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,KAAK,YAAY,EACjB,KAAK,UAAU,GAChB,MAAM,UAAU,CAAC;AAElB,OAAO,EACL,SAAS,EACT,UAAU,EACV,qBAAqB,EACrB,YAAY,EACZ,UAAU,EACV,YAAY,EACZ,KAAK,aAAa,GACnB,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,WAAW,EACX,kBAAkB,EAClB,kBAAkB,EAClB,gBAAgB,EAChB,WAAW,EACX,KAAK,SAAS,GACf,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE/D,OAAO,EACL,aAAa,EACb,UAAU,EACV,uBAAuB,EACvB,KAAK,cAAc,EACnB,KAAK,YAAY,GAClB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACL,aAAa,EACb,eAAe,EACf,eAAe,EACf,KAAK,WAAW,GACjB,MAAM,mBAAmB,CAAC;AAE3B,YAAY,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAE3D,OAAO,EACL,uBAAuB,EACvB,uBAAuB,EACvB,iBAAiB,EACjB,iBAAiB,EACjB,aAAa,EACb,eAAe,EACf,KAAK,cAAc,EACnB,KAAK,UAAU,EACf,KAAK,UAAU,EACf,KAAK,gBAAgB,EACrB,KAAK,aAAa,EAClB,KAAK,aAAa,GACnB,MAAM,eAAe,CAAC;AAEvB,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC"}

package/dist/index.js

@@ -0,0 +1,16 @@
+/**
+ * The programmatic surface of the `@page-scanner/cli` package.
+ *
+ * Importing this does not load `ws`: the bridge runs in the daemon, which is
+ * a separate process. `@page-scanner/cli/daemon` is the entry point that starts
+ * one in-process, and it is the only one that pulls the WebSocket server in.
+ */
+export { listBrowsers, listTabs, pair, scan, status, stop, waitForBrowser, } from './api.js';
+export { configDir, configPath, configFileIsOwnerOnly, ensureConfig, readConfig, DEFAULT_PORT, } from './config.js';
+export { exitCodeFor, isPageScannerError, toPageScannerError, PageScannerError, ERROR_CODES, } from './errors.js';
+export { resolveOutputPath, writeScanFile } from './output.js';
+export { connectDaemon, stopDaemon, DAEMON_START_TIMEOUT_MS, } from './daemon/client.js';
+export { daemonLogPath, daemonStatePath, readDaemonState, } from './daemon/state.js';
+export { BRIDGE_PING_INTERVAL_MS, BRIDGE_PROTOCOL_VERSION, DEFAULT_PAGE_SIZE, EXPORT_FORMAT_IDS, PAGE_SIZE_IDS, VIDEO_HANDLINGS, } from './protocol.js';
+export { CLI_VERSION } from './version.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EACL,YAAY,EACZ,QAAQ,EACR,IAAI,EACJ,IAAI,EACJ,MAAM,EACN,IAAI,EACJ,cAAc,GAOf,MAAM,UAAU,CAAC;AAElB,OAAO,EACL,SAAS,EACT,UAAU,EACV,qBAAqB,EACrB,YAAY,EACZ,UAAU,EACV,YAAY,GAEb,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,WAAW,EACX,kBAAkB,EAClB,kBAAkB,EAClB,gBAAgB,EAChB,WAAW,GAEZ,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE/D,OAAO,EACL,aAAa,EACb,UAAU,EACV,uBAAuB,GAGxB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACL,aAAa,EACb,eAAe,EACf,eAAe,GAEhB,MAAM,mBAAmB,CAAC;AAI3B,OAAO,EACL,uBAAuB,EACvB,uBAAuB,EACvB,iBAAiB,EACjB,iBAAiB,EACjB,aAAa,EACb,eAAe,GAOhB,MAAM,eAAe,CAAC;AAEvB,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC"}

package/dist/output.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Turns `--out` into the absolute path to write.
+ *
+ * `cwd` is a parameter so the tests do not have to chdir the process, and so a
+ * caller holding someone else's working directory can pass it.
+ */
+export declare function resolveOutputPath(outputPath: string | undefined, suggestedName: string, cwd?: string): string;
+/**
+ * `--out captures/2026/page.pdf` should not fail because `2026` is not there
+ * yet, so the parent chain is created on the way in.
+ */
+export declare function writeScanFile(target: string, bytesBase64: string): void;
+//# sourceMappingURL=output.d.ts.map

package/dist/output.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"output.d.ts","sourceRoot":"","sources":["../src/output.ts"],"names":[],"mappings":"AA+BA;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,aAAa,EAAE,MAAM,EACrB,GAAG,GAAE,MAAsB,GAC1B,MAAM,CASR;AAqBD;;;GAGG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,IAAI,CAGvE"}

package/dist/output.js

@@ -0,0 +1,71 @@
+/**
+ * Where a scan lands on disk, and putting it there.
+ *
+ * The daemon never writes the file. It hands back bytes and the client that
+ * asked resolves `--out` against its own working directory, because the daemon
+ * was started from some other terminal at some other time and its cwd has
+ * nothing to do with where the person typing the command is standing.
+ */
+import { mkdirSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+/**
+ * A trailing separator is how the user says "this is a directory", and the only
+ * way to say it about a directory that does not exist yet.
+ *
+ * The test accepts `\` as well as `/` instead of `path.sep`, because this
+ * string came from the user's shell rather than from this platform's path API:
+ * a Windows shell hands over `C:\out\`, and a POSIX test run has to be able to
+ * reproduce that argument. It earns its keep on Windows, where `path.resolve`
+ * strips the trailing `\` before the extension test below ever sees it, so
+ * `C:\out\page.pdf\` would otherwise be read as a file called `page.pdf`.
+ */
+const TRAILING_SEPARATOR = /[\\/]$/;
+/**
+ * Two to five alphanumerics after a dot is what separates `report.pdf` from a
+ * directory called `captures`. Case is ignored: `report.PDF` off a Windows
+ * shell names the same file, and nothing downstream cares about the spelling.
+ */
+const FILE_EXTENSION = /\.[a-z0-9]{2,5}$/i;
+/**
+ * Turns `--out` into the absolute path to write.
+ *
+ * `cwd` is a parameter so the tests do not have to chdir the process, and so a
+ * caller holding someone else's working directory can pass it.
+ */
+export function resolveOutputPath(outputPath, suggestedName, cwd = process.cwd()) {
+    if (!outputPath)
+        return resolve(cwd, suggestedName);
+    const target = resolve(cwd, outputPath);
+    const namesAFile = !TRAILING_SEPARATOR.test(outputPath) &&
+        FILE_EXTENSION.test(target) &&
+        !isExistingDirectory(target);
+    return namesAFile ? target : join(target, suggestedName);
+}
+/**
+ * An existing directory wins over the extension rule, so `--out ./v1.2` writes
+ * into the directory the user already made rather than over it.
+ */
+function isExistingDirectory(candidate) {
+    try {
+        // `throwIfNoEntry: false` already covers both "not there yet" and "a
+        // parent component is a file": stat returns undefined for each. The catch
+        // is for what it cannot swallow, a lookup the OS refuses (EACCES on a
+        // share, say). "Not a directory" is the right answer there too, and if the
+        // path really is unusable the write reports it with the operation that
+        // actually failed rather than this function throwing a stat error out of
+        // argument handling.
+        return statSync(candidate, { throwIfNoEntry: false })?.isDirectory() ?? false;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * `--out captures/2026/page.pdf` should not fail because `2026` is not there
+ * yet, so the parent chain is created on the way in.
+ */
+export function writeScanFile(target, bytesBase64) {
+    mkdirSync(dirname(target), { recursive: true });
+    writeFileSync(target, Buffer.from(bytesBase64, 'base64'));
+}
+//# sourceMappingURL=output.js.map

package/dist/output.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"output.js","sourceRoot":"","sources":["../src/output.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAC7D,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEnD;;;;;;;;;;GAUG;AACH,MAAM,kBAAkB,GAAG,QAAQ,CAAC;AAEpC;;;;GAIG;AACH,MAAM,cAAc,GAAG,mBAAmB,CAAC;AAE3C;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAC/B,UAA8B,EAC9B,aAAqB,EACrB,MAAc,OAAO,CAAC,GAAG,EAAE;IAE3B,IAAI,CAAC,UAAU;QAAE,OAAO,OAAO,CAAC,GAAG,EAAE,aAAa,CAAC,CAAC;IAEpD,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,EAAE,UAAU,CAAC,CAAC;IACxC,MAAM,UAAU,GACd,CAAC,kBAAkB,CAAC,IAAI,CAAC,UAAU,CAAC;QACpC,cAAc,CAAC,IAAI,CAAC,MAAM,CAAC;QAC3B,CAAC,mBAAmB,CAAC,MAAM,CAAC,CAAC;IAC/B,OAAO,UAAU,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;AAC3D,CAAC;AAED;;;GAGG;AACH,SAAS,mBAAmB,CAAC,SAAiB;IAC5C,IAAI,CAAC;QACH,qEAAqE;QACrE,0EAA0E;QAC1E,sEAAsE;QACtE,2EAA2E;QAC3E,uEAAuE;QACvE,yEAAyE;QACzE,qBAAqB;QACrB,OAAO,QAAQ,CAAC,SAAS,EAAE,EAAE,cAAc,EAAE,KAAK,EAAE,CAAC,EAAE,WAAW,EAAE,IAAI,KAAK,CAAC;IAChF,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,MAAc,EAAE,WAAmB;IAC/D,SAAS,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAChD,aAAa,CAAC,MAAM,EAAE,MAAM,CAAC,IAAI,CAAC,WAAW,EAAE,QAAQ,CAAC,CAAC,CAAC;AAC5D,CAAC"}

package/dist/protocol.d.ts

@@ -0,0 +1,144 @@
+/**
+ * Mirror of `extension/src/lib/bridge/protocol.ts`.
+ *
+ * The extension owns the wire contract, because it owns the features the
+ * contract describes: the export formats, the paper sizes, what to do with a
+ * video. This file restates them for a package that cannot import the
+ * extension's source, and `protocol.contract.test.ts` fails if the two drift.
+ *
+ * The direction is the other half of the mirror, too. Over there the guards
+ * check what arrives *at the extension*; here they check what arrives *at the
+ * server*: a handshake, a ping, and the frames that answer a request. A
+ * loopback port is reachable by every process on the machine, so nothing here
+ * assumes a shape it has not checked, and a frame that fails a guard is
+ * dropped rather than coerced.
+ */
+/** Bumped when a change would make an older server and a newer extension disagree. */
+export declare const BRIDGE_PROTOCOL_VERSION = 1;
+/** Ping cadence. Chrome resets the service worker's idle timer on every frame. */
+export declare const BRIDGE_PING_INTERVAL_MS = 20000;
+/** Mirrors EXPORT_FORMAT_IDS in `extension/src/lib/export/formats.ts`. */
+export declare const EXPORT_FORMAT_IDS: readonly ["pdf", "png", "jpeg"];
+export type ExportFormatId = (typeof EXPORT_FORMAT_IDS)[number];
+/** Mirrors the keys of PAGE_SIZE_LABELS in `extension/src/lib/pdf/layout.ts`. */
+export declare const PAGE_SIZE_IDS: readonly ["auto", "a4", "letter"];
+export type PageSizeId = (typeof PAGE_SIZE_IDS)[number];
+/** Mirrors DEFAULT_PAGE_SIZE in `extension/src/lib/pdf/layout.ts`. */
+export declare const DEFAULT_PAGE_SIZE: PageSizeId;
+/** Mirrors VIDEO_HANDLINGS in `extension/src/lib/capture/viewport-units.ts`. */
+export declare const VIDEO_HANDLINGS: readonly ["frame", "blank"];
+export type VideoHandling = (typeof VIDEO_HANDLINGS)[number];
+/** First frame the extension sends. The server answers `hello-ok` or closes. */
+export interface HelloFrame {
+    type: 'hello';
+    protocol: number;
+    token: string;
+    extensionVersion: string;
+    /** Stable per install, so an agent can name the same browser across restarts. */
+    browserId: string;
+    /** What the user called this browser in the settings page, e.g. "work". */
+    label: string;
+}
+export interface HelloAck {
+    type: 'hello-ok';
+}
+/**
+ * Sent instead of `hello-ok` when the handshake is refused for a reason the
+ * user can act on, so the settings page can say what is wrong rather than
+ * showing a bare close code. The socket closes straight after.
+ */
+export interface HelloReject {
+    type: 'hello-error';
+    message: string;
+}
+export interface PingFrame {
+    type: 'ping';
+}
+export interface ListTabsRequest {
+    type: 'list-tabs';
+    id: string;
+}
+export interface ScanRequest {
+    type: 'scan';
+    id: string;
+    /** Scan a tab the user already has open, or open one on `url` and scan that. */
+    tabId?: number;
+    url?: string;
+    /** Which window to open `url` in. Ignored when `tabId` is given. */
+    windowId?: number;
+    format: ExportFormatId;
+    pageSize: PageSizeId;
+    /** 0..1, only meaningful for a lossy format. */
+    quality?: number;
+    videoHandling?: VideoHandling;
+    /** Leave the capture open in an editor tab afterwards. Default false. */
+    openEditor?: boolean;
+}
+export interface WindowSummary {
+    windowId: number;
+    focused: boolean;
+    /** `normal`, `popup`, and so on, straight from `chrome.windows`. */
+    windowType: string;
+    tabCount: number;
+}
+export interface TabSummary {
+    tabId: number;
+    windowId: number;
+    url: string;
+    title: string;
+    active: boolean;
+}
+/**
+ * What was left out, when the page was larger than the capture ceiling.
+ *
+ * The sentence travels on the wire rather than being rebuilt here: the CLI
+ * would otherwise have to keep its own copy of a limit that lives in the
+ * extension.
+ */
+export interface TruncationReport {
+    /** What the page measured, in CSS px, before the ceiling clamped it. */
+    requestedWidth: number;
+    requestedHeight: number;
+    /** What was captured instead. */
+    width: number;
+    height: number;
+    /** One sentence naming the gap, ready to hand to a person. */
+    message: string;
+}
+export interface TabsResponse {
+    type: 'tabs';
+    id: string;
+    windows: WindowSummary[];
+    tabs: TabSummary[];
+}
+export interface ScanResultResponse {
+    type: 'scan-result';
+    id: string;
+    width: number;
+    height: number;
+    mode: 'vector' | 'raster';
+    /** Absent unless the capture stopped short of the whole page. */
+    truncated?: TruncationReport;
+    fileName: string;
+    /** The built file. Base64 because JSON is the frame format. */
+    bytesBase64: string;
+}
+export interface ErrorResponse {
+    type: 'error';
+    id: string;
+    message: string;
+}
+export type BridgeResponse = TabsResponse | ScanResultResponse | ErrorResponse;
+/** Anything the extension may send to the server. */
+export type InboundFrame = HelloFrame | PingFrame | BridgeResponse;
+export declare function isHelloFrame(value: unknown): value is HelloFrame;
+export declare function isPingFrame(value: unknown): value is PingFrame;
+export declare function isTabsResponse(value: unknown): value is TabsResponse;
+export declare function isScanResultResponse(value: unknown): value is ScanResultResponse;
+export declare function isErrorResponse(value: unknown): value is ErrorResponse;
+export declare function isBridgeResponse(value: unknown): value is BridgeResponse;
+/** Everything the extension may send, parsed from one socket message. */
+export declare function parseInbound(raw: string): InboundFrame | null;
+export declare function helloAck(): HelloAck;
+export declare function helloReject(message: string): HelloReject;
+//# sourceMappingURL=protocol.d.ts.map

package/dist/protocol.d.ts.map

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