salesprompter-cli 0.1.79 → 0.1.81

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,19 @@ 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.
 
-If LinkedIn rejects the saved session, the command tries a different local extension-synced session once and keeps completed searches. If none works, reconnect the extension or use `--browser-relay-port` with a signed-in browser worker. Rate limits stop the run without switching sessions.
+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.
 
 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 +72,12 @@ 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; use a new output directory for intentionally retrying saved identity misses. `--all` removes the invocation's job-count limit, not LinkedIn pacing or per-function candidate limits. A working LinkedIn session is required; 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 \
+  --resolve-companies --retry-unresolved --all --wait-for-session 300
+```
 
 ```json
 {

package/dist/chrome-browser.js

@@ -0,0 +1,186 @@
+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 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,
+        });
+    }
+    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;
+    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() {
+        browser = await launch(options.visible);
+        page = await browser.newPage();
+        page.on("response", (response) => {
+            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 (!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 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 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 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; await initialization?.catch(() => { }); await browser?.close(); headers = null; identity = undefined; },
+    };
+}

package/dist/cli.js

@@ -16,7 +16,8 @@ import { Command } from "commander";
 import { z } from "zod";
 import { AffiliateCopyReviewSchema, renderAffiliateCopyReview } from "./affiliate-copy.js";
 import { CompanyBriefSchema, planCompanySearches, runCompanyResearch } from "./company-leads.js";
-import { createSessionRecovery } from "./session-recovery.js";
+import { createLazySessionRecovery, waitForFreshSession, isFreshSessionForIdentity } from "./session-recovery.js";
+import { createChromeResearchBrowser } 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.")
@@ -15144,9 +15159,20 @@ program
     .option("--report-only", "Refresh saved research reports without contacting LinkedIn", false)
     .option("--all", "Process all pending company/function searches in this invocation", false)
     .option("--resolve-companies", "Resolve unique exact company names and collect their contacts in the same run", false)
+    .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);
     const jobs = planCompanySearches(brief);
     const maxSearches = options.all ? Number.MAX_SAFE_INTEGER : z.coerce.number().int().min(1).max(10000).parse(options.maxSearches);
@@ -15164,12 +15190,37 @@ 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 config = relay ? null : await readLinkedInDirectLookupConfig();
-    const recoverSession = createSessionRecovery({
-        initial: config,
+    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())
+            return null;
+        return waitForFreshSession({
+            read: readLocalLinkedInExtensionDirectLookupConfig,
+            accept: next => isFreshSessionForIdentity(currentConfig, next),
+            waitMs,
+            onWaiting: () => writeProgress("Waiting for a refreshed Sales Navigator session from the same LinkedIn identity. Reconnect the Salesprompter extension; the pending search is preserved."),
+        });
+    };
+    const recoverSession = createLazySessionRecovery(async () => {
+        if (relay)
+            return null;
+        try {
+            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();
+            if (!currentConfig)
+                throw new Error("No LinkedIn session arrived before the wait expired. Reconnect the extension and rerun with the same --out-dir; saved work is preserved.");
+        }
+        return currentConfig;
+    }, {
         isAuthError: error => error instanceof CliImportCompanySessionError || error instanceof LocalSalesNavigatorHttpError && (error.status === 401 || error.status === 403),
-        refresh: async () => relay || shouldDisableLinkedInDirectLookupAutodiscovery() ? null : readLocalLinkedInExtensionDirectLookupConfig(),
+        refresh,
         sameSession: (a, b) => a?.cookie === b?.cookie && a?.csrfToken === b?.csrfToken,
         beforeRetry: async () => {
             writeProgress("Saved LinkedIn session was rejected; trying the latest extension-synced session once.");
@@ -15178,7 +15229,7 @@ program
     });
     let startedSearches = 0;
     try {
-        const report = await runCompanyResearch({ brief, outDir: path.resolve(options.outDir), scope: `${session.apiBaseUrl}:${orgId}`, maxSearches,
+        const report = await runCompanyResearch({ brief, outDir: path.resolve(options.outDir), scope: `${session.apiBaseUrl}:${orgId}`, maxSearches, retryUnresolved: options.retryUnresolved,
             resolveCompany: !options.resolveCompanies ? undefined : async (company) => {
                 if (startedSearches++ > 0)
                     await delay(randomIntegerBetween(5000, 8000));

package/dist/company-leads.js

@@ -243,7 +243,8 @@ async function runCompanyResearchLocked(input) {
             for (const [index, company] of brief.companies.entries()) {
                 if (performed >= input.maxSearches || resolutionsPerformed >= input.maxSearches)
                     break;
-                if (company.companyId || Object.hasOwn(state.resolutions ?? {}, String(index)))
+                const savedResolution = state.resolutions?.[String(index)];
+                if (company.companyId || (Object.hasOwn(state.resolutions ?? {}, String(index)) && !(input.retryUnresolved && savedResolution === null)))
                     continue;
                 const resolution = await input.resolveCompany(company);
                 resolutionsPerformed++;

package/dist/session-recovery.js

@@ -1,3 +1,34 @@
+export function isFreshSessionForIdentity(current, next) {
+    return current === null || next.identity === current.identity && (next.cookie !== current.cookie || next.csrfToken !== current.csrfToken);
+}
+/** Poll only the configured credential source. No provider requests or identity rotation. */
+export async function waitForFreshSession(options) {
+    const now = options.now ?? Date.now;
+    const sleep = options.sleep ?? (ms => new Promise(resolve => setTimeout(resolve, ms)));
+    const deadline = now() + options.waitMs;
+    let nextNotice = now();
+    while (true) {
+        const value = await options.read();
+        if (value !== null && options.accept(value))
+            return value;
+        const remaining = deadline - now();
+        if (remaining <= 0)
+            return null;
+        if (now() >= nextNotice) {
+            options.onWaiting?.();
+            nextNotice = now() + 30000;
+        }
+        await sleep(Math.min(5000, remaining));
+    }
+}
+/** Delay credential access until collection really needs it (cached runs need none). */
+export function createLazySessionRecovery(load, options) {
+    let runner;
+    return async (collect) => {
+        runner ??= createSessionRecovery({ ...options, initial: await load() });
+        return runner(collect);
+    };
+}
 /** One credential refresh per run; never rotate on rate limits or other failures. */
 export function createSessionRecovery(options) {
     let current = options.initial;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "salesprompter-cli",
-  "version": "0.1.79",
+  "version": "0.1.81",
   "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": {