salesprompter-cli 0.1.80 → 0.1.82

package/README.md

@@ -1,5 +1,7 @@
 # salesprompter-cli
 
+Requires Node.js 22.12 or newer (Node.js 24 LTS recommended). Chrome research also requires an installed Google Chrome.
+
 Salesprompter CLI is a terminal workflow for lead generation, enrichment, scoring, and sync.
 
 It helps operators and agents go from company, market, or product input to qualified outbound-ready leads with a product-facing command surface and machine-readable output.
@@ -48,7 +50,21 @@ Use `--report-only` to refresh saved reports without contacting LinkedIn. The wo
 
 For a manually verified legal-name alias, add `verifiedEmployerAliases: [{ "name": "Exact source employer name", "evidenceUrl": "https://official.example/legal" }]` to that company. The CLI records the evidence link but does not independently verify its contents. Aliases never bypass the numeric current-company ID check and are never inferred from similar names. Changing the brief requires a new output directory; no existing review rows are silently promoted.
 
-LinkedIn credentials are loaded only when a pending request needs them; a completed checkpoint can be reopened without LinkedIn credentials (Salesprompter workspace authentication still applies). If LinkedIn rejects the saved session, the command tries refreshed local extension credentials for the same LinkedIn identity once and keeps completed searches. Add `--wait-for-session 300` to wait up to five minutes for that refresh, with progress notices. The CLI does not log in to LinkedIn for you. If none arrives, reconnect the extension and rerun, or use `--browser-relay-port` with a signed-in browser worker. Rate limits stop the run without switching sessions. Session waiting and browser relay are mutually exclusive.
+For standalone browser research, sign in once to the CLI-owned Chrome profile, then select Chrome:
+
+```bash
+salesprompter browser:connect
+salesprompter leads:at-companies --brief companies.json --out-dir ./research \
+  --resolve-companies --all --browser chrome
+```
+
+`browser:connect` opens a separate Chrome window and waits up to ten minutes for your manual Sales Navigator sign-in (change with `--wait <seconds>`). It confirms a successful native authenticated request, then closes its own browser. Google Chrome must be installed. The private profile lives at `~/.config/salesprompter/chrome-research` (or under `SALESPROMPTER_CONFIG_DIR`). Your everyday Chrome profile stays untouched. The control connection uses a private OS pipe, not a debugging port. No cookies or browser storage are read/exported. The CLI keeps only allowlisted native request headers in memory.
+
+Research runs reuse that profile in background Chrome, execute the GET requests themselves, and close their own browser when finished. No Codex task, relay worker, extension, or manual request polling is needed. A first sign-in, expired login, or security challenge still requires you: rerun `browser:connect`, then repeat the research command with the same output directory. Rate limits stop immediately without switching accounts. `--browser chrome`, `--browser-relay-port`, and `--wait-for-session` are mutually exclusive. Chrome connects lazily, so completed checkpoints and report-only runs never launch it.
+
+The default `--browser session` keeps the extension-credential route. Credentials load only for pending requests; on an auth failure it tries changed credentials for the same identity once. Add `--wait-for-session 300` for a bounded refresh wait. The optional Codex `--browser-relay-port` route still needs its external worker. Salesprompter workspace authentication applies in every mode.
+
+Ctrl+C, SIGTERM and terminal hangup stop Chrome research gracefully: completed searches stay saved, the owned browser closes, and the research lock is released before exit. Repeat the same command to resume only pending work. A forced kill or power loss cannot run cleanup; if a stale lock remains, confirm that its process stopped before removing only `.research-lock` as the CLI error explains.
 
 Create a JSON brief with verified numeric LinkedIn company IDs. Use each subsidiary's own ID; names alone are not an employer match. Missing IDs stay in the coverage report as unresolved.
 
@@ -58,7 +74,7 @@ For a name-only list, the executable end-to-end research mode is:
 salesprompter leads:at-companies --brief companies.json --out-dir ./research --resolve-companies --all
 ```
 
-The CLI first collects prepared IDs, then resolves missing IDs through paginated Account Search and immediately collects their contacts. It accepts only one exact-name identity from a fully read result set of at most 1,000 companies; fuzzy, shared-ID, oversized and ambiguous matches remain unresolved. Resolutions and misses are saved in the workspace-bound checkpoint and `company-resolutions.json`, without editing the input brief. Repeat the command to resume. Add `--retry-unresolved --resolve-companies` to intentionally retry saved identity misses in the same directory without repeating successful resolutions or completed searches. `--all` removes the invocation's job-count limit, not LinkedIn pacing or per-function candidate limits. A working LinkedIn session is required for new requests; the Codex browser relay still requires a connected browser worker when used.
+The CLI first collects prepared IDs, then resolves missing IDs through paginated Account Search and immediately collects their contacts. It accepts only one exact-name identity from a fully read result set of at most 1,000 companies; fuzzy, shared-ID, oversized and ambiguous matches remain unresolved. Resolutions and misses are saved in the workspace-bound checkpoint and `company-resolutions.json`, without editing the input brief. Repeat the command to resume. Add `--retry-unresolved --resolve-companies` to intentionally retry saved identity misses in the same directory without repeating successful resolutions or completed searches. `--all` removes the invocation's job-count limit, not LinkedIn pacing or per-function candidate limits. A working LinkedIn session is required for new requests; use `--browser chrome` to eliminate the external browser-worker dependency.
 
 ```bash
 salesprompter leads:at-companies --brief companies.json --out-dir ./research \

package/dist/chrome-browser.js

@@ -0,0 +1,231 @@
+import { chmod, lstat, mkdir } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { setTimeout as sleep } from "node:timers/promises";
+const ORIGIN = "https://www.linkedin.com";
+const LOGIN_HELP = "Run salesprompter browser:connect, sign in to LinkedIn Sales Navigator in the dedicated Chrome window, then rerun with the same --out-dir. Saved work is preserved.";
+export class ChromeResearchError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+        this.name = "ChromeResearchError";
+    }
+}
+export class ChromeResearchInterruptedError extends Error {
+    signal;
+    constructor(signal) {
+        super("Research interrupted. Completed searches remain saved; rerun with the same --out-dir to resume.");
+        this.signal = signal;
+        this.name = "ChromeResearchInterruptedError";
+    }
+}
+export function validateChromeResearchUrl(value) {
+    const url = new URL(value);
+    if (url.origin !== ORIGIN || url.username || url.password || url.hash ||
+        !/^\/sales-api\/(?:salesApiAccountSearch|salesApiLeadSearch|salesApiCompanies)(?:\/\d+)?$/.test(url.pathname)) {
+        throw new Error("Chrome research only permits LinkedIn Sales Navigator company and people GET requests.");
+    }
+    // Preserve native Rest.li encoding; URLSearchParams can corrupt its syntax.
+    return value;
+}
+/** Only these native request headers enter memory; cookies/storage are never read or exported. */
+export function researchHeaders(headers) {
+    const lower = Object.fromEntries(Object.entries(headers).map(([k, v]) => [k.toLowerCase(), v]));
+    if (!lower["csrf-token"] || !lower["x-li-identity"])
+        return null;
+    return { "csrf-token": lower["csrf-token"], "x-li-identity": lower["x-li-identity"], accept: "*/*", "x-restli-protocol-version": "2.0.0" };
+}
+export function chromeProfileDirectory() {
+    return path.resolve(process.env.SALESPROMPTER_CONFIG_DIR?.trim() || path.join(os.homedir(), ".config", "salesprompter"), "chrome-research");
+}
+/** Launch only a CLI-owned profile and private OS pipe; no debugging port or default-profile attachment. */
+export async function launchResearchChrome(visible = false) {
+    const profile = chromeProfileDirectory();
+    try {
+        if ((await lstat(profile)).isSymbolicLink())
+            throw new Error("The research Chrome profile must not be a symlink.");
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+    await mkdir(profile, { recursive: true, mode: 0o700 });
+    await chmod(profile, 0o700);
+    const { default: puppeteer } = await import("puppeteer-core");
+    try {
+        return await puppeteer.launch({ channel: "chrome", userDataDir: profile, pipe: true, headless: !visible,
+            timeout: 30000, protocolTimeout: 45000, defaultViewport: null,
+            // Let the command unwind its checkpoint/lock finally blocks before exiting.
+            handleSIGINT: false, handleSIGTERM: false, handleSIGHUP: false,
+        });
+    }
+    catch {
+        // Launch errors can contain paths/flags. Never forward raw browser stderr or credential-bearing URLs.
+        throw new ChromeResearchError("Could not start the dedicated research Chrome. Install/update Google Chrome and close any other salesprompter browser:connect or Chrome research run. Your everyday Chrome can stay open.");
+    }
+}
+export function parseChromeResearchResult(result) {
+    if (result.status === 429 || result.status === 999)
+        throw new ChromeResearchError(`LinkedIn returned HTTP ${result.status}. Research stopped; wait for cooldown before resuming the same checkpoint. No session switching or retry was attempted.`, result.status);
+    if (result.redirected || result.status === 401 || result.status === 403)
+        throw new ChromeResearchError(LOGIN_HELP, result.status);
+    if (result.status !== 200)
+        throw new ChromeResearchError(`LinkedIn research failed with HTTP ${result.status}. Saved work is preserved.`, result.status);
+    try {
+        return JSON.parse(result.text);
+    }
+    catch {
+        throw new ChromeResearchError(`LinkedIn did not return research JSON. ${LOGIN_HELP}`);
+    }
+}
+/** Lazy and serial: reopening a completed checkpoint never starts Chrome. */
+export function createChromeResearchBrowser(options = {}, launch = launchResearchChrome) {
+    let browser;
+    let page;
+    let headers = null;
+    let identity;
+    let fatal;
+    let initialization;
+    let closed = false;
+    let busy = false;
+    let browserClosing;
+    const signals = ["SIGINT", "SIGTERM", "SIGHUP"];
+    const signalHandlers = signals.map(signal => () => {
+        if (fatal instanceof ChromeResearchInterruptedError)
+            return;
+        fatal = new ChromeResearchInterruptedError(signal);
+        closed = true;
+        void closeOwnedBrowser().catch(() => { });
+    });
+    function closeOwnedBrowser() {
+        if (browser)
+            browserClosing ??= browser.close();
+        return browserClosing ?? Promise.resolve();
+    }
+    const waitMs = options.loginWaitMs ?? 30000;
+    if (!Number.isFinite(waitMs) || waitMs < 0 || waitMs > 3600000)
+        throw new Error("Chrome login wait must be between 0 and 3600 seconds.");
+    async function initialize() {
+        signals.forEach((signal, index) => process.on(signal, signalHandlers[index]));
+        browser = await launch(options.visible);
+        if (closed) {
+            await closeOwnedBrowser();
+            throw fatal ?? new ChromeResearchError("Research Chrome connection was cancelled.");
+        }
+        page = await browser.newPage();
+        page.on("response", (response) => {
+            if (fatal)
+                return;
+            const url = new URL(response.url());
+            if (url.origin !== ORIGIN)
+                return;
+            if (response.status() === 429 || response.status() === 999) {
+                fatal = new ChromeResearchError(`LinkedIn returned HTTP ${response.status()}. Stop and wait for cooldown before resuming.`, response.status());
+                return;
+            }
+            if (!url.pathname.startsWith("/sales-api/"))
+                return;
+            if (response.status() !== 200)
+                return;
+            const next = researchHeaders(response.request().headers());
+            if (!next)
+                return;
+            if (identity && identity !== next["x-li-identity"]) {
+                fatal = new ChromeResearchError("LinkedIn identity changed during research. Stopped without switching accounts.");
+                return;
+            }
+            identity = next["x-li-identity"];
+            headers = next;
+        });
+        options.onProgress?.(options.visible
+            ? "Sign in to Sales Navigator in the dedicated research Chrome window. The CLI will detect the connection automatically; no extension or browser worker is required."
+            : "Connecting to the saved research Chrome profile (no external browser worker).");
+        try {
+            await page.goto(`${ORIGIN}/sales/search/people`, { waitUntil: "domcontentloaded", timeout: 30000 });
+        }
+        catch {
+            if (closed)
+                throw fatal ?? new ChromeResearchError("Research Chrome connection was cancelled.");
+            if (!browser.connected)
+                throw new ChromeResearchError("Research Chrome closed before connecting.");
+        }
+        const deadline = Date.now() + waitMs;
+        let noticeAt = Date.now() + 30000;
+        while (!headers) {
+            if (closed)
+                throw fatal ?? new ChromeResearchError("Research Chrome connection was cancelled.");
+            if (fatal)
+                throw fatal;
+            if (!browser.connected || page.isClosed())
+                throw new ChromeResearchError("Research Chrome was closed before sign-in completed.");
+            const location = new URL(page.url());
+            const needsLogin = location.origin !== ORIGIN || /\/(?:login|checkpoint|authwall|uas)\b/.test(location.pathname);
+            if ((!options.visible && needsLogin) || Date.now() >= deadline)
+                throw new ChromeResearchError(LOGIN_HELP);
+            if (Date.now() >= noticeAt) {
+                options.onProgress?.("Waiting for Sales Navigator sign-in. Complete any sign-in or security check yourself in the research Chrome window.");
+                noticeAt += 30000;
+            }
+            await sleep(250);
+        }
+        if (fatal)
+            throw fatal;
+        options.onProgress?.("Research Chrome connected. Requests now run directly in the CLI.");
+    }
+    async function ready() {
+        if (closed)
+            throw fatal ?? new Error("Research Chrome is closed.");
+        initialization ??= initialize();
+        await initialization;
+        if (fatal)
+            throw fatal;
+    }
+    return {
+        // Compatibility with the existing request adapter, without opening any listener.
+        port: 0,
+        async connect() { await ready(); return { browser: "chrome", connected: true, workerRequired: false, profile: chromeProfileDirectory() }; },
+        async request(request) {
+            validateChromeResearchUrl(request.url);
+            if (busy)
+                throw new Error("Chrome research is single-worker; concurrent requests are not allowed.");
+            busy = true;
+            try {
+                await ready();
+                if (new URL(page.url()).origin !== ORIGIN)
+                    throw new ChromeResearchError(LOGIN_HELP);
+                // Serialize URL and allowlisted native headers as data, never concatenate raw input into executable code.
+                // Credentials remain browser-managed. Reject redirects to login/challenge pages instead of parsing HTML.
+                const result = await page.evaluate(`(async () => {
+          const response = await fetch(${JSON.stringify(request.url)}, {
+            method: 'GET', credentials: 'include', redirect: 'error',
+            headers: ${JSON.stringify(headers)}, signal: AbortSignal.timeout(30000)
+          });
+          const text = await response.text();
+          if (text.length > 50 * 1024 * 1024) throw new Error('Research response exceeded 50 MB');
+          return {status: response.status, text, redirected: response.redirected, retryAfter: response.headers.get('retry-after')};
+        })()`).catch(() => { throw fatal ?? new ChromeResearchError(`Chrome research request could not complete. ${LOGIN_HELP}`); });
+                const body = parseChromeResearchResult(result);
+                if (fatal)
+                    throw fatal;
+                return { body, retryCount: 0, retryDelayMs: 0 };
+            }
+            finally {
+                busy = false;
+            }
+        },
+        async close() {
+            closed = true;
+            try {
+                await closeOwnedBrowser();
+                await initialization?.catch(() => { });
+                await closeOwnedBrowser();
+            }
+            finally {
+                signals.forEach((signal, index) => process.off(signal, signalHandlers[index]));
+                headers = null;
+                identity = undefined;
+            }
+        },
+    };
+}

package/dist/cli.js

@@ -17,6 +17,7 @@ import { z } from "zod";
 import { AffiliateCopyReviewSchema, renderAffiliateCopyReview } from "./affiliate-copy.js";
 import { CompanyBriefSchema, planCompanySearches, runCompanyResearch } from "./company-leads.js";
 import { createLazySessionRecovery, waitForFreshSession, isFreshSessionForIdentity } from "./session-recovery.js";
+import { createChromeResearchBrowser, ChromeResearchInterruptedError } from "./chrome-browser.js";
 import { clearAuthSession, loginWithBrowserConnect, loginWithDeviceFlow, loginWithToken, readAuthSession, requireAuthSession, shouldBypassAuth, verifySession, writeAuthSession } from "./auth.js";
 import { buildBigQueryLeadLookupSql, executeBigQuerySql, normalizeBigQueryLeadRows, runBigQueryQuery, runBigQueryRows } from "./bigquery.js";
 import { AccountProfileSchema, EnrichedLeadSchema, IcpSchema, LeadSchema, ScoredLeadSchema, SyncTargetSchema } from "./domain.js";
@@ -777,6 +778,7 @@ const helpVisibleCommandNames = new Set([
     "auth:workspace",
     "wizard",
     "auth:whoami",
+    "browser:connect",
     "llm:ready",
     "leads:download",
     "leads:at-companies",
@@ -15135,6 +15137,19 @@ program
     .action(async (options) => {
     printOutput(await runSalesNavigatorPeopleCollectCommand(options));
 });
+program
+    .command("browser:connect")
+    .description("Sign in once to the CLI-owned research Chrome; no external browser worker required.")
+    .option("--wait <seconds>", "Time allowed for manual LinkedIn sign-in", "600")
+    .action(async (options) => {
+    const browser = createChromeResearchBrowser({ visible: true, loginWaitMs: z.coerce.number().int().min(1).max(3600).parse(options.wait) * 1000, onProgress: message => process.stderr.write(`${message}\n`) });
+    try {
+        printOutput({ status: "ok", ...await browser.connect() });
+    }
+    finally {
+        await browser.close();
+    }
+});
 program
     .command("leads:at-companies")
     .description("Find senior contacts at named companies, balanced across functions; export a review shortlist.")
@@ -15147,11 +15162,15 @@ program
     .option("--retry-unresolved", "Retry cached identity misses without discarding completed searches (requires --resolve-companies)", false)
     .option("--wait-for-session <seconds>", "Wait for a refreshed extension session after an auth failure; never retry rate limits", "0")
     .option("--browser-relay-port <number>", "Use the signed-in Codex browser through a loopback relay")
+    .option("--browser <mode>", "Use chrome for CLI-owned browser research, or session for extension credentials", "session")
     .option("--dry-run", "Preview targeting and unresolved companies without network calls", false)
     .action(async (options) => {
+    const browserMode = z.enum(["chrome", "session"]).parse(options.browser);
     if (options.retryUnresolved && !options.resolveCompanies)
         throw new Error("--retry-unresolved requires --resolve-companies.");
     const waitMs = z.coerce.number().int().min(0).max(3600).parse(options.waitForSession) * 1000;
+    if (browserMode === "chrome" && (options.browserRelayPort || waitMs))
+        throw new Error("Use one connection mode: --browser chrome, --browser-relay-port, or --wait-for-session.");
     if (waitMs && options.browserRelayPort)
         throw new Error("--wait-for-session refreshes extension credentials, not a browser relay. Use one connection mode.");
     const brief = await readJsonFile(path.resolve(options.brief), CompanyBriefSchema);
@@ -15171,7 +15190,7 @@ program
         return;
     }
     const port = options.browserRelayPort == null ? null : z.coerce.number().int().min(1).max(65535).parse(options.browserRelayPort);
-    const relay = port == null ? null : await createLocalAccountSearchBrowserRelay(port);
+    const relay = browserMode === "chrome" ? createChromeResearchBrowser({ onProgress: message => process.stderr.write(`${message}\n`) }) : port == null ? null : await createLocalAccountSearchBrowserRelay(port);
     let currentConfig = null;
     const refresh = async () => {
         if (relay || shouldDisableLinkedInDirectLookupAutodiscovery())
@@ -15190,6 +15209,8 @@ program
             currentConfig = await readLinkedInDirectLookupConfig();
         }
         catch (error) {
+            if (!waitMs && error instanceof Error && error.message.startsWith("Missing LinkedIn direct lookup session"))
+                throw new Error("No LinkedIn session is available. Run salesprompter browser:connect, then rerun this command with --browser chrome and the same --out-dir. No external browser worker is needed.");
             if (!waitMs || !(error instanceof Error) || !error.message.startsWith("Missing LinkedIn direct lookup session"))
                 throw error;
             currentConfig = await refresh();
@@ -19542,6 +19563,11 @@ async function closeGlobalHttpDispatcher() {
 }
 main()
     .catch((error) => {
+    if (error instanceof ChromeResearchInterruptedError) {
+        process.stderr.write(runtimeOutputOptions.json ? `${JSON.stringify({ status: "interrupted", message: error.message, signal: error.signal, resumable: true })}\n` : `${error.message}\n`);
+        process.exitCode = error.signal === "SIGINT" ? 130 : error.signal === "SIGTERM" ? 143 : 129;
+        return;
+    }
     if (error instanceof Error &&
         (error.message === "prompt cancelled" || error.message === "readline was closed")) {
         process.exitCode = 130;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "salesprompter-cli",
-  "version": "0.1.80",
+  "version": "0.1.82",
   "description": "Sales workflow CLI for guided lead generation, enrichment, scoring, and sync.",
   "author": "Daniel Sinewe <hello@danielsinewe.com>",
   "type": "module",
@@ -31,7 +31,7 @@
     "vercel-build": "npm run build:docs:site"
   },
   "engines": {
-    "node": ">=20.0.0"
+    "node": ">=22.12.0"
   },
   "publishConfig": {
     "access": "public"
@@ -70,6 +70,7 @@
     "cheerio": "^1.2.0",
     "commander": "^14.0.1",
     "pg": "^8.21.0",
+    "puppeteer-core": "^25.10.0",
     "zod": "^4.1.5"
   },
   "overrides": {