@jackwener/opencli 1.7.22 → 1.8.0

package/clis/linkedin/people-search.js

@@ -0,0 +1,262 @@
+/**
+ * LinkedIn people-search via SSR DOM text-slice. Voyager people-search
+ * REST returns HTTP 500 from a web context; LinkedIn renders results
+ * server-side now. One navigation per call consumes one CUL query.
+ */
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { ArgumentError, AuthRequiredError, CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
+
+const LINKEDIN_DOMAIN = 'www.linkedin.com';
+const SEARCH_URL_BASE = 'https://www.linkedin.com/search/results/people/';
+const MAX_LIMIT = 10;
+
+function normalizeWhitespace(value) {
+    return String(value ?? '').replace(/[  ]/g, ' ').replace(/\s+/g, ' ').trim();
+}
+
+function requireStringArg(args, key, label = key) {
+    const value = normalizeWhitespace(args[key]);
+    if (!value) throw new ArgumentError(`${label} is required`);
+    return value;
+}
+
+function parseLimit(value) {
+    if (value === undefined || value === null || value === '') return 5;
+    const limit = Number(value);
+    if (!Number.isInteger(limit) || limit < 1 || limit > MAX_LIMIT) {
+        throw new ArgumentError(`--limit must be an integer between 1 and ${MAX_LIMIT}`);
+    }
+    return limit;
+}
+
+function unwrapEvaluateResult(payload) {
+    if (payload && typeof payload === 'object' && 'data' in payload && 'session' in payload) return payload.data;
+    return payload;
+}
+
+function buildSearchUrl(keywords) {
+    return SEARCH_URL_BASE + '?keywords=' + encodeURIComponent(keywords);
+}
+
+function looksLinkedInAuthWall(value) {
+    const text = normalizeWhitespace(value).toLowerCase();
+    if (!text) return false;
+    return /linkedin\.com\/(?:login|checkpoint|authwall|uas)/i.test(text)
+        || /\b(sign in|log in|join linkedin|captcha|verification required)\b/i.test(text)
+        || /(请登录|登录领英|安全验证)/.test(text);
+}
+
+function normalizeProfileUrl(value) {
+    const raw = normalizeWhitespace(value);
+    if (!raw) return '';
+    try {
+        const parsed = new URL(raw);
+        const host = parsed.hostname.toLowerCase();
+        if (parsed.protocol !== 'https:' || parsed.username || parsed.password || parsed.port) return '';
+        if (host !== 'linkedin.com' && host !== 'www.linkedin.com') return '';
+        const match = parsed.pathname.match(/^\/in\/([^/?#]+)\/?$/);
+        if (!match || !match[1]) return '';
+        return `https://www.linkedin.com/in/${match[1]}/`;
+    } catch {
+        return '';
+    }
+}
+
+function normalizePeopleRows(rows) {
+    if (!Array.isArray(rows)) {
+        throw new CommandExecutionError('LinkedIn people search returned malformed extraction payload: missing rows array');
+    }
+    return rows.map((row, index) => {
+        if (!row || typeof row !== 'object') {
+            throw new CommandExecutionError(`LinkedIn people search returned malformed row at index ${index}`);
+        }
+        const name = normalizeWhitespace(row.name);
+        const profileUrl = normalizeProfileUrl(row.profile_url);
+        if (!name || !profileUrl) {
+            throw new CommandExecutionError(`LinkedIn people search returned row without stable profile identity at index ${index}`);
+        }
+        return {
+            name,
+            headline: normalizeWhitespace(row.headline),
+            location: normalizeWhitespace(row.location),
+            profile_url: profileUrl,
+        };
+    });
+}
+
+function parseNonNegativeCount(value, label) {
+    const count = Number(value);
+    if (!Number.isInteger(count) || count < 0) {
+        throw new CommandExecutionError(`LinkedIn people search returned malformed extraction payload: invalid ${label}`);
+    }
+    return count;
+}
+
+function extractionScript() {
+    // Class-based selectors are dead (LinkedIn rotates hashed class
+    // names on every deploy) and display:contents flattens the DOM
+    // tree so per-card containers don't exist. Read main.innerText
+    // and slice between consecutive person-name lines instead.
+    return String.raw`(() => {
+    if (!/search\/results\/people/.test(window.location.href)) {
+      return { error: 'not on people search page', url: window.location.href };
+    }
+    const main = document.querySelector('main') || document.body;
+    const normalize = (s) => String(s || '').replace(/[\s\u00a0\u202f]+/g, ' ').trim();
+    const skip = (l) => !l
+      || /^Status is/.test(l)
+      || /^(Message|Connect|Follow|View profile|Pending|Remove)$/i.test(l)
+      || /^[•·]\s*(?:1st|2nd|3rd\+?|degree)/i.test(l)
+      || /^[•·]/.test(l)
+      || l.includes('mutual connection')
+      || l.includes('shared connection')
+      || /^Summary:/i.test(l)
+      || /^About this profile/i.test(l);
+
+    const anchors = Array.from(main.querySelectorAll('a[href*="/in/"]'));
+    const personEntries = [];
+    const seenHandles = new Set();
+    for (const a of anchors) {
+      const m = (a.getAttribute('href') || '').match(/\/in\/([^/?#]+)/);
+      if (!m || !m[1]) continue;
+      const profileHandle = m[1];
+      if (seenHandles.has(profileHandle)) continue;
+      const aria = a.querySelector('span[aria-hidden="true"]');
+      let name = normalize(aria ? aria.textContent : a.textContent);
+      name = name.replace(/^Status is (online|offline)\.?\s*/i, '')
+                 .replace(/'?s profile$/i, '')
+                 .replace(/\s*[•·].*$/, '').trim();
+      if (!name) continue;
+      seenHandles.add(profileHandle);
+      personEntries.push({ profileHandle, displayName: name });
+    }
+
+    const lines = (main.innerText || '').split(/\n+/).map(normalize).filter(Boolean);
+
+    // skip() rejects mutual-connection lines, so candidates that only
+    // appear as mutual-connection links inside another card's row
+    // never resolve a name index and get filtered out below.
+    const nameToIndex = new Map();
+    for (const { displayName } of personEntries) {
+      if (nameToIndex.has(displayName)) continue;
+      const match = lines.findIndex((l) =>
+        !skip(l) && (
+          l === displayName
+          || l.startsWith(displayName + ' ')
+          || l.startsWith(displayName + ',')
+          || l.startsWith(displayName + "'")
+        )
+      );
+      if (match >= 0) nameToIndex.set(displayName, match);
+    }
+
+    const resolved = personEntries.filter((p) => nameToIndex.has(p.displayName));
+    const rows = [];
+    for (let i = 0; i < resolved.length; i++) {
+      const { profileHandle, displayName } = resolved[i];
+      const startIdx = nameToIndex.get(displayName);
+      let stopIdx = lines.length;
+      for (let j = i + 1; j < resolved.length; j++) {
+        const otherStart = nameToIndex.get(resolved[j].displayName);
+        if (otherStart != null && otherStart > startIdx) {
+          stopIdx = otherStart;
+          break;
+        }
+      }
+      const slice = lines.slice(startIdx + 1, stopIdx).filter((l) => l !== displayName && !skip(l));
+      rows.push({
+        name: displayName,
+        headline: slice[0] || '',
+        location: slice[1] || '',
+        profile_url: 'https://www.linkedin.com/in/' + profileHandle + '/',
+      });
+    }
+    return {
+      rows,
+      candidate_count: personEntries.length,
+      person_entries_count: personEntries.length,
+      resolved_count: resolved.length,
+    };
+  })()`;
+}
+
+cli({
+    site: 'linkedin',
+    name: 'people-search',
+    access: 'read',
+    description: 'Search standard LinkedIn (not Sales Navigator) for people by keyword. Each invocation consumes against LinkedIn\'s monthly Commercial Use Limit on people search; throttle accordingly.',
+    domain: LINKEDIN_DOMAIN,
+    strategy: Strategy.COOKIE,
+    browser: true,
+    args: [
+        { name: 'keywords', type: 'string', required: true, positional: true, help: 'People search keywords, e.g. "site reliability engineer berlin"' },
+        { name: 'limit', type: 'int', default: 5, help: `Maximum people to return (1-${MAX_LIMIT}); each query counts toward LinkedIn's monthly CUL` },
+    ],
+    columns: ['rank', 'name', 'headline', 'location', 'profile_url'],
+    func: async (page, args) => {
+        if (!page) throw new CommandExecutionError('Browser session required for linkedin people-search');
+        const keywords = requireStringArg(args, 'keywords', '--keywords');
+        const limit = parseLimit(args.limit);
+
+        try {
+            await page.goto(buildSearchUrl(keywords));
+            await page.wait(6);
+        } catch (error) {
+            throw new CommandExecutionError(`LinkedIn people search navigation failed: ${error?.message || error}`);
+        }
+
+        let cookies;
+        try {
+            cookies = await page.getCookies({ url: 'https://www.linkedin.com' });
+        } catch (error) {
+            throw new CommandExecutionError(`LinkedIn cookie lookup failed: ${error?.message || error}`);
+        }
+        if (!Array.isArray(cookies)) {
+            throw new CommandExecutionError('LinkedIn cookie lookup returned malformed payload');
+        }
+        const jsession = cookies.find((c) => c.name === 'JSESSIONID')?.value;
+        if (!jsession) {
+            throw new AuthRequiredError(LINKEDIN_DOMAIN, 'LinkedIn JSESSIONID cookie not found. Please sign in to LinkedIn in the browser.');
+        }
+
+        let result;
+        try {
+            result = unwrapEvaluateResult(await page.evaluate(extractionScript()));
+        } catch (error) {
+            throw new CommandExecutionError(`LinkedIn people search extraction failed: ${error?.message || error}`);
+        }
+        if (result?.error) {
+            if (looksLinkedInAuthWall(`${result.url || ''} ${result.error || ''}`)) {
+                throw new AuthRequiredError(LINKEDIN_DOMAIN, 'LinkedIn people search requires an active signed-in browser session.');
+            }
+            // If LinkedIn redirected away from the search page that
+            // usually means CUL was reached or the account is gated.
+            throw new CommandExecutionError(`LinkedIn redirected away from the search page (${result.error}). Likely Commercial Use Limit reached - the limit resets on the 1st of next month.`);
+        }
+        if (!result || typeof result !== 'object') {
+            throw new CommandExecutionError('LinkedIn people search returned malformed extraction payload');
+        }
+        const candidateCount = parseNonNegativeCount(result.candidate_count, 'candidate_count');
+        parseNonNegativeCount(result.person_entries_count, 'person_entries_count');
+        const resolvedCount = parseNonNegativeCount(result.resolved_count, 'resolved_count');
+        const rows = normalizePeopleRows(result.rows);
+        if (rows.length === 0 && (candidateCount > 0 || resolvedCount > 0)) {
+            throw new CommandExecutionError('LinkedIn people search found profile candidates but could not parse stable result rows');
+        }
+        if (rows.length === 0) {
+            throw new EmptyResultError(`No people found on the rendered page for "${keywords}". The search may have returned zero results, or the DOM markup may have changed.`);
+        }
+        return rows.slice(0, limit).map((p, i) => ({ rank: i + 1, ...p }));
+    },
+});
+
+export const __test__ = {
+    normalizeWhitespace,
+    parseLimit,
+    buildSearchUrl,
+    looksLinkedInAuthWall,
+    normalizeProfileUrl,
+    normalizePeopleRows,
+    parseNonNegativeCount,
+    extractionScript,
+};

package/clis/linkedin/people-search.test.js

@@ -0,0 +1,216 @@
+import { describe, expect, it, vi } from 'vitest';
+import { getRegistry } from '@jackwener/opencli/registry';
+import { ArgumentError, AuthRequiredError, CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
+import './people-search.js';
+
+const {
+    parseLimit,
+    buildSearchUrl,
+    looksLinkedInAuthWall,
+    normalizeProfileUrl,
+    normalizePeopleRows,
+    parseNonNegativeCount,
+    extractionScript,
+} = await import('./people-search.js').then((m) => m.__test__);
+
+function extractionResult(rows, counts = {}) {
+    return {
+        rows,
+        candidate_count: counts.candidate_count ?? rows.length,
+        person_entries_count: counts.person_entries_count ?? counts.candidate_count ?? rows.length,
+        resolved_count: counts.resolved_count ?? rows.length,
+    };
+}
+
+function makePage({
+    evaluateResult,
+    evaluateReject,
+    gotoReject,
+    cookies = [{ name: 'JSESSIONID', value: '"ajax:1234567890"' }],
+} = {}) {
+    return {
+        goto: vi.fn().mockImplementation(() => gotoReject ? Promise.reject(gotoReject) : Promise.resolve(undefined)),
+        wait: vi.fn().mockResolvedValue(undefined),
+        getCookies: vi.fn().mockResolvedValue(cookies),
+        evaluate: vi.fn().mockImplementation(() => evaluateReject ? Promise.reject(evaluateReject) : Promise.resolve(evaluateResult)),
+    };
+}
+
+describe('linkedin people-search command', () => {
+    it('builds the canonical SSR search URL with encoded keywords', () => {
+        expect(buildSearchUrl('site reliability engineer'))
+            .toBe('https://www.linkedin.com/search/results/people/?keywords=site%20reliability%20engineer');
+        expect(buildSearchUrl('hello/world & stuff'))
+            .toBe('https://www.linkedin.com/search/results/people/?keywords=hello%2Fworld%20%26%20stuff');
+    });
+
+    it('validates --limit without silent clamping', () => {
+        expect(parseLimit(undefined)).toBe(5);
+        expect(parseLimit(1)).toBe(1);
+        expect(parseLimit(10)).toBe(10);
+        expect(() => parseLimit(0)).toThrow(ArgumentError);
+        expect(() => parseLimit(11)).toThrow(ArgumentError);
+        expect(() => parseLimit(-1)).toThrow(ArgumentError);
+        expect(() => parseLimit('abc')).toThrow(ArgumentError);
+        expect(() => parseLimit(1.5)).toThrow(ArgumentError);
+    });
+
+    it('extraction script slices main.innerText by person-name boundaries', () => {
+        const s = extractionScript();
+        // Anchor enumeration finds /in/<handle>.
+        expect(s).toContain('a[href*="/in/"]');
+        expect(s).toContain('\\/in\\/([^/?#]+)');
+        // Text-slice approach: split main.innerText and locate names.
+        expect(s).toContain('main.innerText');
+        expect(s).toContain('lines.findIndex');
+        // Mutual-connection anchors are filtered out via the skip()
+        // predicate on the name-line match.
+        expect(s).toContain('mutual connection');
+        // Names dedup'd by handle.
+        expect(s).toContain('seenHandles');
+        // Aria-hidden span as canonical name source.
+        expect(s).toContain('span[aria-hidden="true"]');
+        // Only operates on the people-search page.
+        expect(s).toContain('search\\/results\\/people');
+        expect(s).toContain('candidate_count');
+        expect(s).toContain('resolved_count');
+    });
+
+    it('normalizes only stable LinkedIn profile identities', () => {
+        expect(normalizeProfileUrl('https://www.linkedin.com/in/alice-engineer/?mini=true'))
+            .toBe('https://www.linkedin.com/in/alice-engineer/');
+        expect(normalizeProfileUrl('https://linkedin.com/in/bob-builder')).toBe('https://www.linkedin.com/in/bob-builder/');
+        expect(normalizeProfileUrl('https://evil-linkedin.com/in/bob-builder')).toBe('');
+        expect(normalizeProfileUrl('http://www.linkedin.com/in/bob-builder')).toBe('');
+        expect(normalizeProfileUrl('https://www.linkedin.com/company/opencli')).toBe('');
+    });
+
+    it('detects LinkedIn auth-wall URLs separately from CUL redirects', () => {
+        expect(looksLinkedInAuthWall('https://www.linkedin.com/authwall Sign in to continue')).toBe(true);
+        expect(looksLinkedInAuthWall('https://www.linkedin.com/checkpoint/challenge security verification required')).toBe(true);
+        expect(looksLinkedInAuthWall('https://www.linkedin.com/feed/')).toBe(false);
+    });
+
+    it('rejects malformed extraction rows instead of fabricating success rows', () => {
+        expect(() => normalizePeopleRows({})).toThrow(CommandExecutionError);
+        expect(() => normalizePeopleRows([null])).toThrow(CommandExecutionError);
+        expect(() => normalizePeopleRows([{ name: 'No URL', headline: 'h', location: 'l', profile_url: '' }]))
+            .toThrow(CommandExecutionError);
+        expect(() => normalizePeopleRows([{ name: '', headline: 'h', location: 'l', profile_url: 'https://www.linkedin.com/in/no-name/' }]))
+            .toThrow(CommandExecutionError);
+    });
+
+    it('validates extraction evidence counters', () => {
+        expect(parseNonNegativeCount(0, 'candidate_count')).toBe(0);
+        expect(parseNonNegativeCount(2, 'candidate_count')).toBe(2);
+        expect(() => parseNonNegativeCount(undefined, 'candidate_count')).toThrow(CommandExecutionError);
+        expect(() => parseNonNegativeCount(-1, 'candidate_count')).toThrow(CommandExecutionError);
+        expect(() => parseNonNegativeCount(1.2, 'candidate_count')).toThrow(CommandExecutionError);
+    });
+
+    it('returns ranked rows when the page yields people', async () => {
+        const cmd = getRegistry().get('linkedin/people-search');
+        expect(cmd?.func).toBeTypeOf('function');
+        const page = makePage({
+            evaluateResult: extractionResult([
+                { name: 'Alice Engineer', headline: 'Staff SWE at Acme', location: 'Berlin', profile_url: 'https://www.linkedin.com/in/alice-engineer/' },
+                { name: 'Bob Builder', headline: 'CTO at Globex', location: 'Remote', profile_url: 'https://www.linkedin.com/in/bob-builder/' },
+            ]),
+        });
+        const result = await cmd.func(page, { keywords: 'reinforcement learning', limit: 5 });
+        expect(page.goto).toHaveBeenCalledWith('https://www.linkedin.com/search/results/people/?keywords=reinforcement%20learning');
+        expect(result).toEqual([
+            { rank: 1, name: 'Alice Engineer', headline: 'Staff SWE at Acme', location: 'Berlin', profile_url: 'https://www.linkedin.com/in/alice-engineer/' },
+            { rank: 2, name: 'Bob Builder', headline: 'CTO at Globex', location: 'Remote', profile_url: 'https://www.linkedin.com/in/bob-builder/' },
+        ]);
+    });
+
+    it('slices to --limit when more rows are extracted than requested', async () => {
+        const cmd = getRegistry().get('linkedin/people-search');
+        const page = makePage({
+            evaluateResult: extractionResult(Array.from({ length: 8 }, (_, i) => ({
+                name: `Person ${i}`, headline: 'h', location: 'l', profile_url: `https://www.linkedin.com/in/p${i}/`,
+            }))),
+        });
+        const result = await cmd.func(page, { keywords: 'x', limit: 3 });
+        expect(result).toHaveLength(3);
+        expect(result.map((r) => r.rank)).toEqual([1, 2, 3]);
+    });
+
+    it('throws AuthRequiredError when JSESSIONID cookie is missing', async () => {
+        const cmd = getRegistry().get('linkedin/people-search');
+        const page = makePage({ cookies: [], evaluateResult: extractionResult([]) });
+        await expect(cmd.func(page, { keywords: 'x', limit: 5 })).rejects.toBeInstanceOf(AuthRequiredError);
+    });
+
+    it('treats malformed cookie lookup results as CommandExecutionError', async () => {
+        const cmd = getRegistry().get('linkedin/people-search');
+        const page = makePage({ cookies: null, evaluateResult: extractionResult([]) });
+        await expect(cmd.func(page, { keywords: 'x', limit: 5 })).rejects.toBeInstanceOf(CommandExecutionError);
+    });
+
+    it('treats LinkedIn redirect away from search page as a CUL-flavoured CommandExecutionError', async () => {
+        const cmd = getRegistry().get('linkedin/people-search');
+        const page = makePage({ evaluateResult: { error: 'not on people search page', url: 'https://www.linkedin.com/' } });
+        await expect(cmd.func(page, { keywords: 'x', limit: 5 })).rejects.toBeInstanceOf(CommandExecutionError);
+    });
+
+    it('treats LinkedIn auth-wall redirects as AuthRequiredError', async () => {
+        const cmd = getRegistry().get('linkedin/people-search');
+        const page = makePage({ evaluateResult: { error: 'not on people search page', url: 'https://www.linkedin.com/authwall?trk=people_search' } });
+        await expect(cmd.func(page, { keywords: 'x', limit: 5 })).rejects.toBeInstanceOf(AuthRequiredError);
+    });
+
+    it('wraps browser extraction exceptions as CommandExecutionError', async () => {
+        const cmd = getRegistry().get('linkedin/people-search');
+        const page = makePage({ evaluateReject: new SyntaxError('Unexpected token <') });
+        await expect(cmd.func(page, { keywords: 'x', limit: 5 })).rejects.toBeInstanceOf(CommandExecutionError);
+    });
+
+    it('wraps browser navigation exceptions as CommandExecutionError', async () => {
+        const cmd = getRegistry().get('linkedin/people-search');
+        const page = makePage({ gotoReject: new Error('navigation failed') });
+        await expect(cmd.func(page, { keywords: 'x', limit: 5 })).rejects.toBeInstanceOf(CommandExecutionError);
+    });
+
+    it('throws EmptyResultError when the page rendered zero rows', async () => {
+        const cmd = getRegistry().get('linkedin/people-search');
+        const page = makePage({ evaluateResult: extractionResult([]) });
+        await expect(cmd.func(page, { keywords: 'x', limit: 5 })).rejects.toBeInstanceOf(EmptyResultError);
+    });
+
+    it('treats profile candidates without stable parsed rows as parser drift', async () => {
+        const cmd = getRegistry().get('linkedin/people-search');
+        const page = makePage({
+            evaluateResult: extractionResult([], {
+                candidate_count: 1,
+                person_entries_count: 1,
+                resolved_count: 0,
+            }),
+        });
+        await expect(cmd.func(page, { keywords: 'x', limit: 5 })).rejects.toBeInstanceOf(CommandExecutionError);
+    });
+
+    it('treats missing rows array as parser drift, not empty results', async () => {
+        const cmd = getRegistry().get('linkedin/people-search');
+        const page = makePage({ evaluateResult: {} });
+        await expect(cmd.func(page, { keywords: 'x', limit: 5 })).rejects.toBeInstanceOf(CommandExecutionError);
+    });
+
+    it('rejects empty keywords with ArgumentError before navigation', async () => {
+        const cmd = getRegistry().get('linkedin/people-search');
+        const page = makePage({ evaluateResult: extractionResult([]) });
+        await expect(cmd.func(page, { keywords: '   ', limit: 5 })).rejects.toBeInstanceOf(ArgumentError);
+        expect(page.goto).not.toHaveBeenCalled();
+    });
+
+    it('registers with the expected columns and arg shape', () => {
+        const cmd = getRegistry().get('linkedin/people-search');
+        expect(cmd?.columns).toEqual(['rank', 'name', 'headline', 'location', 'profile_url']);
+        expect(cmd?.access).toBe('read');
+        expect(cmd?.browser).toBe(true);
+        const keywordsArg = cmd?.args?.find((a) => a.name === 'keywords');
+        expect(keywordsArg?.positional).toBe(true);
+        expect(keywordsArg?.required).toBe(true);
+    });
+});