gologin-web-access 0.3.0

package/dist/commands/crawl.js

@@ -0,0 +1,71 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildCrawlCommand = buildCrawlCommand;
+const commander_1 = require("commander");
+const config_1 = require("../config");
+const crawl_1 = require("../lib/crawl");
+const output_1 = require("../lib/output");
+function buildCrawlCommand() {
+    return new commander_1.Command("crawl")
+        .description("Crawl a website through Gologin Web Unlocker and return per-page extracted content.")
+        .argument("<url>", "Root website URL to crawl")
+        .option("--format <format>", "html, markdown, text, or json", "markdown")
+        .option("--limit <count>", "Maximum number of pages to visit", "25")
+        .option("--max-depth <depth>", "Maximum link depth from the root URL", "2")
+        .option("--concurrency <count>", "Number of concurrent requests", "4")
+        .option("--include-subdomains", "Include subdomains inside the crawl scope")
+        .option("--include <patterns>", "Comma-separated URL patterns to include")
+        .option("--exclude <patterns>", "Comma-separated URL patterns to exclude")
+        .option("--ignore-query", "Normalize URLs without query parameters")
+        .option("--sitemap <mode>", "include, only, or skip", "include")
+        .option("--only-main-content", "For html, markdown, or text output, isolate the most readable content block on each page")
+        .option("--strict", "Exit non-zero when any page fails during crawling")
+        .action(async (url, options) => {
+        const config = await (0, config_1.loadConfig)();
+        const apiKey = (0, config_1.requireWebUnlockerKey)(config);
+        const format = normalizeFormat(options.format);
+        const result = await (0, crawl_1.crawlSite)(url, apiKey, format, {
+            limit: normalizePositiveInt(options.limit, 25),
+            maxDepth: normalizeNonNegativeInt(options.maxDepth, 2),
+            concurrency: normalizePositiveInt(options.concurrency, 4),
+            includeSubdomains: Boolean(options.includeSubdomains),
+            includePatterns: splitPatterns(options.include),
+            excludePatterns: splitPatterns(options.exclude),
+            ignoreQueryParameters: Boolean(options.ignoreQuery),
+            sitemapMode: normalizeSitemapMode(options.sitemap),
+            onlyMainContent: Boolean(options.onlyMainContent),
+        });
+        (0, output_1.printJson)(result);
+        if (result.status === "failed" || (options.strict && result.failed > 0)) {
+            process.exitCode = 1;
+        }
+    });
+}
+function splitPatterns(value) {
+    return value
+        ? value
+            .split(",")
+            .map((pattern) => pattern.trim())
+            .filter(Boolean)
+        : [];
+}
+function normalizeSitemapMode(value) {
+    if (value === "include" || value === "only" || value === "skip") {
+        return value;
+    }
+    throw new Error(`Unsupported sitemap mode: ${value}`);
+}
+function normalizeFormat(value) {
+    if (value === "html" || value === "markdown" || value === "text" || value === "json") {
+        return value;
+    }
+    throw new Error(`Unsupported crawl format: ${value}`);
+}
+function normalizePositiveInt(value, fallback) {
+    const parsed = Number(value);
+    return Number.isFinite(parsed) && parsed > 0 ? Math.floor(parsed) : fallback;
+}
+function normalizeNonNegativeInt(value, fallback) {
+    const parsed = Number(value);
+    return Number.isFinite(parsed) && parsed >= 0 ? Math.floor(parsed) : fallback;
+}

package/dist/commands/crawlErrors.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildCrawlErrorsCommand = buildCrawlErrorsCommand;
+const commander_1 = require("commander");
+const config_1 = require("../config");
+const jobRegistry_1 = require("../lib/jobRegistry");
+const output_1 = require("../lib/output");
+function buildCrawlErrorsCommand() {
+    return new commander_1.Command("crawl-errors")
+        .description("Print stderr captured for a detached crawl job.")
+        .argument("<jobId>", "Crawl job identifier")
+        .action(async (jobId) => {
+        const config = await (0, config_1.loadConfig)();
+        const job = await (0, jobRegistry_1.getJob)(config, jobId);
+        if (!job) {
+            throw new Error(`Job ${jobId} not found`);
+        }
+        (0, output_1.printText)(await (0, jobRegistry_1.readJobErrors)(job));
+    });
+}

package/dist/commands/crawlResult.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildCrawlResultCommand = buildCrawlResultCommand;
+const commander_1 = require("commander");
+const config_1 = require("../config");
+const jobRegistry_1 = require("../lib/jobRegistry");
+const output_1 = require("../lib/output");
+function buildCrawlResultCommand() {
+    return new commander_1.Command("crawl-result")
+        .description("Print the stored result of a detached crawl job.")
+        .argument("<jobId>", "Crawl job identifier")
+        .option("--json", "Print structured JSON result when available")
+        .action(async (jobId, options) => {
+        const config = await (0, config_1.loadConfig)();
+        const job = await (0, jobRegistry_1.getJob)(config, jobId);
+        if (!job) {
+            throw new Error(`Job ${jobId} not found`);
+        }
+        const result = await (0, jobRegistry_1.readJobResult)(config, job);
+        if (options.json && result !== undefined) {
+            (0, output_1.printJson)(result);
+            return;
+        }
+        const output = await (0, jobRegistry_1.readJobOutput)(job);
+        (0, output_1.printText)(output || (result !== undefined ? JSON.stringify(result, null, 2) : ""));
+    });
+}

package/dist/commands/crawlStart.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildCrawlStartCommand = buildCrawlStartCommand;
+const commander_1 = require("commander");
+const config_1 = require("../config");
+const jobRegistry_1 = require("../lib/jobRegistry");
+const selfCli_1 = require("../lib/selfCli");
+function buildCrawlStartCommand() {
+    return new commander_1.Command("crawl-start")
+        .description("Start a detached crawl job and return a local job id.")
+        .argument("<url>", "Root website URL to crawl")
+        .option("--format <format>", "html, markdown, text, or json", "markdown")
+        .option("--limit <count>", "Maximum number of pages to visit", "25")
+        .option("--max-depth <depth>", "Maximum link depth from the root URL", "2")
+        .option("--concurrency <count>", "Number of concurrent requests", "4")
+        .option("--include-subdomains", "Include subdomains inside the crawl scope")
+        .option("--include <patterns>", "Comma-separated URL patterns to include")
+        .option("--exclude <patterns>", "Comma-separated URL patterns to exclude")
+        .option("--ignore-query", "Normalize URLs without query parameters")
+        .option("--sitemap <mode>", "include, only, or skip", "include")
+        .option("--only-main-content", "For html, markdown, or text output, isolate the most readable content block on each page")
+        .action(async (url, options) => {
+        const config = await (0, config_1.loadConfig)();
+        (0, config_1.requireWebUnlockerKey)(config);
+        const args = buildCrawlArgs(url, options);
+        const job = await (0, jobRegistry_1.createJob)(config, {
+            kind: "crawl",
+            name: url,
+            cwd: process.cwd(),
+            args
+        });
+        await (0, selfCli_1.spawnDetachedNodeInvocation)("jobRunner", [job.jobId, ...args], {
+            cwd: process.cwd()
+        });
+        process.stdout.write(`${job.jobId}\n`);
+    });
+}
+function buildCrawlArgs(url, options) {
+    const args = ["crawl", url, "--format", options.format, "--limit", options.limit, "--max-depth", options.maxDepth, "--concurrency", options.concurrency, "--sitemap", options.sitemap];
+    if (options.includeSubdomains) {
+        args.push("--include-subdomains");
+    }
+    if (options.include) {
+        args.push("--include", options.include);
+    }
+    if (options.exclude) {
+        args.push("--exclude", options.exclude);
+    }
+    if (options.ignoreQuery) {
+        args.push("--ignore-query");
+    }
+    if (options.onlyMainContent) {
+        args.push("--only-main-content");
+    }
+    return args;
+}

package/dist/commands/crawlStatus.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildCrawlStatusCommand = buildCrawlStatusCommand;
+const commander_1 = require("commander");
+const config_1 = require("../config");
+const jobRegistry_1 = require("../lib/jobRegistry");
+const output_1 = require("../lib/output");
+function buildCrawlStatusCommand() {
+    return new commander_1.Command("crawl-status")
+        .description("Show the status of a detached crawl job.")
+        .argument("<jobId>", "Crawl job identifier")
+        .option("--json", "Print JSON output")
+        .action(async (jobId, options) => {
+        const config = await (0, config_1.loadConfig)();
+        const job = await (0, jobRegistry_1.getJob)(config, jobId);
+        if (!job) {
+            throw new Error(`Job ${jobId} not found`);
+        }
+        if (options.json) {
+            (0, output_1.printJson)(job);
+            return;
+        }
+        (0, output_1.printText)(`job=${job.jobId}\nkind=${job.kind}\nstatus=${job.status}\nname=${job.name}`);
+    });
+}

package/dist/commands/current.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildCurrentCommand = buildCurrentCommand;
+const commander_1 = require("commander");
+const config_1 = require("../config");
+const agentCli_1 = require("../lib/agentCli");
+function buildCurrentCommand() {
+    return new commander_1.Command("current")
+        .description("Show the current daemon-backed browser session.")
+        .action(async () => {
+        const config = await (0, config_1.loadConfig)();
+        await (0, agentCli_1.runAgentCommand)(["current"], config);
+    });
+}

package/dist/commands/dblclick.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildDoubleClickCommand = buildDoubleClickCommand;
+const commander_1 = require("commander");
+const shared_1 = require("./shared");
+function buildDoubleClickCommand() {
+    const command = new commander_1.Command("dblclick")
+        .description("Double-click an element by snapshot ref.")
+        .argument("<ref>", "Snapshot ref, for example e3")
+        .action(async (ref, options) => {
+        await (0, shared_1.runBrowserCommand)(["dblclick", ref], { session: options.session });
+    });
+    return (0, shared_1.addSessionOption)(command);
+}

package/dist/commands/eval.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildEvalCommand = buildEvalCommand;
+const commander_1 = require("commander");
+const shared_1 = require("./shared");
+function buildEvalCommand() {
+    const command = new commander_1.Command("eval")
+        .alias("js")
+        .description("Evaluate a JavaScript expression in the active Cloud Browser tab.")
+        .argument("<expression...>", "JavaScript expression")
+        .option("--json", "Print the evaluated value as JSON")
+        .action(async (expression, options) => {
+        const args = ["eval", expression.join(" ")];
+        if (options.json) {
+            args.push("--json");
+        }
+        await (0, shared_1.runBrowserCommand)(args, { session: options.session });
+    });
+    return (0, shared_1.addSessionOption)(command);
+}

package/dist/commands/extract.js

@@ -0,0 +1,44 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildExtractCommand = buildExtractCommand;
+const fs_1 = require("fs");
+const path_1 = __importDefault(require("path"));
+const commander_1 = require("commander");
+const config_1 = require("../config");
+const extractRunner_1 = require("../lib/extractRunner");
+const output_1 = require("../lib/output");
+const readSource_1 = require("../lib/readSource");
+const shared_1 = require("./shared");
+function buildExtractCommand() {
+    return (0, shared_1.addUnlockerRequestOptions)(new commander_1.Command("extract")
+        .description("Extract structured data from a page using a selector schema.")
+        .argument("<url>", "Target URL")
+        .requiredOption("--schema <path>", "Path to a JSON extraction schema")
+        .option("--output <path>", "Write extracted JSON to a file")
+        .option("--source <source>", "Read source: auto, unlocker, or browser", "auto")
+        .action(async (url, options) => {
+        const config = await (0, config_1.loadConfig)();
+        const source = (0, readSource_1.normalizeReadSourceMode)(options.source, "auto");
+        const apiKey = source === "browser" ? "" : (0, config_1.requireWebUnlockerKey)(config);
+        const schema = await readSchema(path_1.default.resolve(options.schema));
+        const result = await (0, extractRunner_1.extractUrlWithSchema)(url, config, apiKey, schema, {
+            source,
+            request: (0, shared_1.normalizeUnlockerRequestOptions)(options),
+        });
+        if (options.output) {
+            const outputPath = path_1.default.resolve(options.output);
+            await fs_1.promises.mkdir(path_1.default.dirname(outputPath), { recursive: true });
+            await fs_1.promises.writeFile(outputPath, `${JSON.stringify(result.extracted, null, 2)}\n`, "utf8");
+            process.stdout.write(`${outputPath}\n`);
+            return;
+        }
+        (0, output_1.printJson)(result);
+    }));
+}
+async function readSchema(schemaPath) {
+    const raw = await fs_1.promises.readFile(schemaPath, "utf8");
+    return JSON.parse(raw);
+}

package/dist/commands/fill.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildFillCommand = buildFillCommand;
+const commander_1 = require("commander");
+const shared_1 = require("./shared");
+function buildFillCommand() {
+    const command = new commander_1.Command("fill")
+        .description("Fill text into an element by snapshot ref.")
+        .argument("<ref>", "Snapshot ref, for example e2")
+        .argument("<text>", "Text to fill")
+        .action(async (ref, text, options) => {
+        await (0, shared_1.runBrowserCommand)(["fill", ref, text], { session: options.session });
+    });
+    return (0, shared_1.addSessionOption)(command);
+}

package/dist/commands/find.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildFindCommand = buildFindCommand;
+const commander_1 = require("commander");
+const shared_1 = require("./shared");
+function buildFindCommand() {
+    const command = new commander_1.Command("find")
+        .description("Find elements semantically and act on them through the browser session.")
+        .allowUnknownOption(true)
+        .argument("<args...>", "Arguments forwarded to gologin-agent-browser find")
+        .action(async (args, options) => {
+        const finalArgs = ["find", ...args];
+        await (0, shared_1.runBrowserCommand)(finalArgs, { session: options.session });
+    });
+    return (0, shared_1.addSessionOption)(command);
+}

package/dist/commands/focus.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildFocusCommand = buildFocusCommand;
+const commander_1 = require("commander");
+const shared_1 = require("./shared");
+function buildFocusCommand() {
+    const command = new commander_1.Command("focus")
+        .description("Focus an element by snapshot ref.")
+        .argument("<ref>", "Snapshot ref, for example e2")
+        .action(async (ref, options) => {
+        await (0, shared_1.runBrowserCommand)(["focus", ref], { session: options.session });
+    });
+    return (0, shared_1.addSessionOption)(command);
+}

package/dist/commands/forward.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildForwardCommand = buildForwardCommand;
+const commander_1 = require("commander");
+const shared_1 = require("./shared");
+function buildForwardCommand() {
+    const command = new commander_1.Command("forward")
+        .description("Navigate forward in the active Cloud Browser tab history.")
+        .action(async (options) => {
+        await (0, shared_1.runBrowserCommand)(["forward"], { session: options.session });
+    });
+    return (0, shared_1.addSessionOption)(command);
+}

package/dist/commands/get.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildGetCommand = buildGetCommand;
+const commander_1 = require("commander");
+const shared_1 = require("./shared");
+function buildGetCommand() {
+    const command = new commander_1.Command("get")
+        .description("Get text, value, html, title, or url from the current page or a target.")
+        .argument("<kind>", "text, value, html, title, or url")
+        .argument("[target]", "Optional snapshot ref target")
+        .action(async (kind, target, options) => {
+        await (0, shared_1.runBrowserCommand)(target ? ["get", kind, target] : ["get", kind], { session: options.session });
+    });
+    return (0, shared_1.addSessionOption)(command);
+}

package/dist/commands/hover.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildHoverCommand = buildHoverCommand;
+const commander_1 = require("commander");
+const shared_1 = require("./shared");
+function buildHoverCommand() {
+    const command = new commander_1.Command("hover")
+        .description("Hover an element by snapshot ref.")
+        .argument("<ref>", "Snapshot ref, for example e2")
+        .action(async (ref, options) => {
+        await (0, shared_1.runBrowserCommand)(["hover", ref], { session: options.session });
+    });
+    return (0, shared_1.addSessionOption)(command);
+}

package/dist/commands/jobs.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildJobsCommand = buildJobsCommand;
+exports.buildJobCommand = buildJobCommand;
+const commander_1 = require("commander");
+const config_1 = require("../config");
+const jobRegistry_1 = require("../lib/jobRegistry");
+const output_1 = require("../lib/output");
+function buildJobsCommand() {
+    return new commander_1.Command("jobs")
+        .description("List local web-access jobs such as crawl, run, and batch executions.")
+        .option("--json", "Print JSON output")
+        .action(async (options) => {
+        const config = await (0, config_1.loadConfig)();
+        const jobs = await (0, jobRegistry_1.listJobs)(config);
+        if (options.json) {
+            (0, output_1.printJson)(jobs);
+            return;
+        }
+        if (jobs.length === 0) {
+            (0, output_1.printText)("No jobs.");
+            return;
+        }
+        (0, output_1.printText)(jobs
+            .map((job) => `${job.jobId}  ${job.kind}  ${job.status}  ${job.name}`)
+            .join("\n"));
+    });
+}
+function buildJobCommand() {
+    return new commander_1.Command("job")
+        .description("Inspect a specific local web-access job.")
+        .argument("<jobId>", "Job identifier")
+        .option("--json", "Print JSON output")
+        .action(async (jobId, options) => {
+        const config = await (0, config_1.loadConfig)();
+        const job = await (0, jobRegistry_1.getJob)(config, jobId);
+        if (!job) {
+            throw new Error(`Job ${jobId} not found`);
+        }
+        const result = await (0, jobRegistry_1.readJobResult)(config, job);
+        if (options.json) {
+            (0, output_1.printJson)({ ...job, result });
+            return;
+        }
+        (0, output_1.printText)(JSON.stringify({ ...job, result }, null, 2));
+    });
+}

package/dist/commands/map.js

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildMapCommand = buildMapCommand;
+const commander_1 = require("commander");
+const config_1 = require("../config");
+const output_1 = require("../lib/output");
+const crawl_1 = require("../lib/crawl");
+function buildMapCommand() {
+    return new commander_1.Command("map")
+        .description("Discover internal website links through Gologin Web Unlocker.")
+        .argument("<url>", "Root website URL to map")
+        .option("--limit <count>", "Maximum number of pages to visit", "100")
+        .option("--max-depth <depth>", "Maximum link depth from the root URL", "2")
+        .option("--concurrency <count>", "Number of concurrent requests", "4")
+        .option("--include-subdomains", "Include subdomains inside the crawl scope")
+        .option("--include <patterns>", "Comma-separated URL patterns to include")
+        .option("--exclude <patterns>", "Comma-separated URL patterns to exclude")
+        .option("--ignore-query", "Normalize URLs without query parameters")
+        .option("--sitemap <mode>", "include, only, or skip", "include")
+        .option("--strict", "Exit non-zero when any page fails during mapping")
+        .action(async (url, options) => {
+        const config = await (0, config_1.loadConfig)();
+        const apiKey = (0, config_1.requireWebUnlockerKey)(config);
+        const result = await (0, crawl_1.mapSite)(url, apiKey, {
+            limit: normalizePositiveInt(options.limit, 100),
+            maxDepth: normalizeNonNegativeInt(options.maxDepth, 2),
+            concurrency: normalizePositiveInt(options.concurrency, 4),
+            includeSubdomains: Boolean(options.includeSubdomains),
+            includePatterns: splitPatterns(options.include),
+            excludePatterns: splitPatterns(options.exclude),
+            ignoreQueryParameters: Boolean(options.ignoreQuery),
+            sitemapMode: normalizeSitemapMode(options.sitemap),
+        });
+        (0, output_1.printJson)(result);
+        if (result.status === "failed" || (options.strict && result.failed > 0)) {
+            process.exitCode = 1;
+        }
+    });
+}
+function splitPatterns(value) {
+    return value
+        ? value
+            .split(",")
+            .map((pattern) => pattern.trim())
+            .filter(Boolean)
+        : [];
+}
+function normalizeSitemapMode(value) {
+    if (value === "include" || value === "only" || value === "skip") {
+        return value;
+    }
+    throw new Error(`Unsupported sitemap mode: ${value}`);
+}
+function normalizePositiveInt(value, fallback) {
+    const parsed = Number(value);
+    return Number.isFinite(parsed) && parsed > 0 ? Math.floor(parsed) : fallback;
+}
+function normalizeNonNegativeInt(value, fallback) {
+    const parsed = Number(value);
+    return Number.isFinite(parsed) && parsed >= 0 ? Math.floor(parsed) : fallback;
+}

package/dist/commands/open.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildOpenCommand = buildOpenCommand;
+const commander_1 = require("commander");
+const shared_1 = require("./shared");
+function buildOpenCommand() {
+    const command = new commander_1.Command("open")
+        .description("Open a URL in Gologin Cloud Browser and create a daemon-backed session.")
+        .argument("<url>", "URL to open")
+        .option("--idle-timeout-ms <ms>", "Idle timeout for the browser session")
+        .option("--proxy-country <country>", "Request a country-based proxy when supported")
+        .option("--proxy-mode <mode>", "Custom proxy mode: http, socks4, or socks5")
+        .option("--proxy-host <host>", "Custom proxy host")
+        .option("--proxy-port <port>", "Custom proxy port")
+        .option("--proxy-user <username>", "Custom proxy username")
+        .option("--proxy-pass <password>", "Custom proxy password")
+        .action(async (url, options) => {
+        await (0, shared_1.runOpenLikeCommand)(url, options);
+    });
+    (0, shared_1.addProfileOption)(command);
+    return (0, shared_1.addSessionOption)(command);
+}

package/dist/commands/parseDocument.js

@@ -0,0 +1,34 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildParseDocumentCommand = buildParseDocumentCommand;
+const fs_1 = require("fs");
+const path_1 = __importDefault(require("path"));
+const commander_1 = require("commander");
+const document_1 = require("../lib/document");
+const output_1 = require("../lib/output");
+function buildParseDocumentCommand() {
+    return new commander_1.Command("parse-document")
+        .description("Parse PDF, DOCX, XLSX, HTML, or text-like documents from a URL or local path.")
+        .argument("<source>", "Document URL or local file path")
+        .option("--json", "Print structured JSON output")
+        .option("--output <path>", "Write parsed output to a file")
+        .action(async (source, options) => {
+        const parsed = await (0, document_1.parseDocumentSource)(source);
+        if (options.output) {
+            const outputPath = path_1.default.resolve(options.output);
+            await fs_1.promises.mkdir(path_1.default.dirname(outputPath), { recursive: true });
+            const payload = options.json ? JSON.stringify(parsed, null, 2) : parsed.text;
+            await fs_1.promises.writeFile(outputPath, `${payload}\n`, "utf8");
+            process.stdout.write(`${outputPath}\n`);
+            return;
+        }
+        if (options.json) {
+            (0, output_1.printJson)(parsed);
+            return;
+        }
+        (0, output_1.printText)(parsed.text);
+    });
+}

package/dist/commands/pdf.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildPdfCommand = buildPdfCommand;
+const commander_1 = require("commander");
+const shared_1 = require("./shared");
+function buildPdfCommand() {
+    const command = new commander_1.Command("pdf")
+        .description("Save the current page as a PDF.")
+        .argument("<targetPath>", "Where to write the PDF file")
+        .action(async (targetPath, options) => {
+        await (0, shared_1.runBrowserCommand)(["pdf", (0, shared_1.resolveOutputPath)(targetPath)], { session: options.session });
+    });
+    return (0, shared_1.addSessionOption)(command);
+}

package/dist/commands/press.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildPressCommand = buildPressCommand;
+const commander_1 = require("commander");
+const shared_1 = require("./shared");
+function buildPressCommand() {
+    const command = new commander_1.Command("press")
+        .description("Press a keyboard key, optionally against a target ref.")
+        .argument("<key>", "Keyboard key, for example Enter or ArrowDown")
+        .argument("[target]", "Optional snapshot ref target")
+        .action(async (key, target, options) => {
+        await (0, shared_1.runBrowserCommand)(target ? ["press", key, target] : ["press", key], { session: options.session });
+    });
+    return (0, shared_1.addSessionOption)(command);
+}

package/dist/commands/read.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildReadCommand = buildReadCommand;
+const commander_1 = require("commander");
+const config_1 = require("../config");
+const readSource_1 = require("../lib/readSource");
+const output_1 = require("../lib/output");
+const shared_1 = require("./shared");
+function buildReadCommand() {
+    return (0, shared_1.addProfileOption)((0, shared_1.addUnlockerRequestOptions)(new commander_1.Command("read")
+        .description("Read the main content of a docs page or article with automatic fallback to Cloud Browser when needed.")
+        .argument("<url>", "URL to read")
+        .option("--format <format>", "Output format: html, markdown, or text", "text")
+        .option("--source <source>", "Read source: auto, unlocker, or browser", "auto")
+        .action(async (url, options) => {
+        const config = await (0, config_1.loadConfig)();
+        const format = normalizeReadFormat(options.format);
+        const source = (0, readSource_1.normalizeReadSourceMode)(options.source, "auto");
+        const apiKey = source === "browser" ? "" : (0, config_1.requireWebUnlockerKey)(config);
+        const readOptions = {
+            source,
+            profile: options.profile,
+            request: (0, shared_1.normalizeUnlockerRequestOptions)(options),
+        };
+        const result = format === "html"
+            ? await (0, readSource_1.readHtmlContent)(url, config, apiKey, readOptions)
+            : format === "markdown"
+                ? await (0, readSource_1.readMarkdownContent)(url, config, apiKey, readOptions)
+                : await (0, readSource_1.readTextContent)(url, config, apiKey, readOptions);
+        emitReadNotice(result.fallbackAttempted, result.fallbackUsed, result.fallbackReason);
+        (0, output_1.printText)(result.content);
+    })));
+}
+function normalizeReadFormat(value) {
+    if (!value || value === "text" || value === "markdown" || value === "html") {
+        return (value ?? "text");
+    }
+    throw new Error(`Unsupported read format: ${value}`);
+}
+function emitReadNotice(fallbackAttempted, fallbackUsed, fallbackReason) {
+    if (!fallbackAttempted) {
+        return;
+    }
+    if (fallbackUsed) {
+        process.stderr.write(`JS-rendered page detected, retrying with browser. ${fallbackReason ?? ""}\n`);
+        return;
+    }
+    if (fallbackReason) {
+        process.stderr.write(`${fallbackReason}\n`);
+    }
+}