feat: add search command MVP (#26)

* feat: add search command MVP

* test: add search to smoke script

* feat: include location in normalized connection outputs

* feat: add mutualConnections metadata to search results

* docs: record search parser mutual/location learnings

Author: peggyrayzis

README.md

@@ -74,6 +74,31 @@ li connections --of peggyrayzis   # View someone else's connections
 
 Note: `li connections --of ...` depends on LinkedIn search pagination behavior. LinkedIn may cap results (often around ~20) even when more pages are requested.
 
+### Search
+
+```bash
+li search --query "founder"               # Search profiles
+li search --query "founder" -n 10         # Return up to 10
+li search --query "founder" --all         # Request all pages (still capped at 50)
+li search --query "founder" --fast        # Faster fetch mode
+li search --query "founder" --json        # Machine-readable output
+```
+
+Supported flags: `--json`, `--fast`, `-n/--count`, `--all`.
+
+Temporary MVP limit: search results are hard-capped at 50 profiles. `--all` still stops at 50.
+
+MVP JSON output for `li search --query ... --json` uses these top-level keys:
+
+```json
+{
+  "query": "founder",
+  "limitApplied": 50,
+  "connections": [],
+  "paging": {}
+}
+```
+
 ### Invitations
 
 ```bash

docs/MEMORY.md

@@ -8,6 +8,11 @@ Append-only log. Add entries; do not rewrite historical entries except typo fixe
 - Fix: updated URL parsing to normalize no-scheme LinkedIn URLs before route parsing, and added tests for no-scheme supported/unsupported paths.
 - Guardrail: recipient cache warnings now ignore synthetic/non-canonical URNs (for example fixture-style placeholders) and tests use isolated cache paths to prevent cross-run cache contamination.
 
+## 2026-02-27
+- Correction: people-search parsing can misclassify text when social-proof metadata is split across larger result blocks (for example truncated headline fragments or missing mutual-connection signals in short chunks).
+- Fix: increased bounded result-chunk scan length for search stream parsing, tightened candidate filtering for headline/location extraction, and derived `mutualConnections` from social-proof windows nearest mutual text.
+- Guardrail: parser + command tests now pin mutual-connection extraction behavior, and smoke runs verify live search JSON shape remains stable under real payload variants.
+
 ## 2026-02-25
 - Correction: process guidance was fragmented across root markdown files and drifted over time.
 - Fix: consolidated process rules into `AGENTS.md`, moved specification to `docs/SPEC.md`, and started managed freshness checks.

docs/SPEC.md

@@ -1,14 +1,22 @@
 # li Specification
-Last Updated: 2026-02-25
+Last Updated: 2026-02-27
 
 ## Product Goal
 `li` is a Node.js TypeScript CLI for LinkedIn workflows with human-readable output and machine-readable `--json` output.
 
 ## Scope (Current)
-- Read-focused account and network workflows (`whoami`, `check`, `profile`, `connections`, `invites`, `messages`).
+- Read-focused account and network workflows (`whoami`, `check`, `profile`, `connections`, `search`, `invites`, `messages`).
 - Cookie-based authentication via browser/session credentials.
 - Voyager endpoint support and normalization utilities.
 
+## Search Command (MVP)
+- Command: `li search --query <text>`
+- Supported flags: `--json`, `--fast`, `-n/--count`, `--all`
+- Temporary hard cap: maximum 50 profiles per search response.
+- `--all` requests pagination but is still capped at 50 profiles in MVP.
+- JSON output is intentionally minimal in MVP and currently uses top-level keys:
+  `{ query, limitApplied, connections, paging }`.
+
 ## Out Of Scope (Current)
 - Unreviewed write actions that may mutate LinkedIn state by default.
 - Long-lived internal process docs outside `AGENTS.md` + `docs/`.
@@ -28,6 +36,7 @@ Last Updated: 2026-02-25
 ## Known Limitations
 - `connections --of` relies on upstream LinkedIn search pagination behavior that can be account/session capped (often around two pages, ~20 results) even when additional page requests return HTTP 200.
 - `--all` for `connections --of` should be treated as potentially partial under active upstream clamp conditions.
+- `search` is currently limited to a maximum of 50 profiles regardless of requested count or `--all`.
 
 ## Related References
 - Process rules: `AGENTS.md`

scripts/smoke.sh

@@ -6,6 +6,7 @@ cd "$ROOT_DIR"
 
 OTHER_PROFILE_URL="${LI_SMOKE_OTHER_PROFILE_URL:-https://www.linkedin.com/in/mnmagan}"
 COUNT="${LI_SMOKE_COUNT:-3}"
+SEARCH_QUERY="${LI_SMOKE_SEARCH_QUERY:-react developers in san francisco at AI companies}"
 
 run() {
 	echo "==> $*"
@@ -44,6 +45,18 @@ run "${CLI[@]}" profile "https://www.linkedin.com/in/$OWN_USERNAME" --json
 run "${CLI[@]}" connections -n "$COUNT" --json
 run "${CLI[@]}" connections -n "$COUNT" --json --of "$OTHER_PROFILE_URL"
 
+echo "==> ${CLI[*]} search --query \"$SEARCH_QUERY\" -n $COUNT --json"
+SEARCH_JSON="$("${CLI[@]}" search --query "$SEARCH_QUERY" -n "$COUNT" --json)"
+printf "%s" "$SEARCH_JSON" | node -e '
+const fs = require("node:fs");
+const data = JSON.parse(fs.readFileSync(0, "utf8"));
+if (!Object.prototype.hasOwnProperty.call(data, "query")) process.exit(1);
+if (!Object.prototype.hasOwnProperty.call(data, "limitApplied")) process.exit(1);
+if (!Array.isArray(data.connections)) process.exit(1);
+if (!data.paging || typeof data.paging !== "object") process.exit(1);
+console.log(`    query="${data.query}" results=${data.connections.length}`);
+'
+
 echo "==> ${CLI[*]} messages -n $COUNT --json"
 MESSAGES_JSON="$("${CLI[@]}" messages -n "$COUNT" --json)"
 CONVO_ID="$(

src/cli.ts

@@ -16,6 +16,7 @@ import { listInvites } from "./commands/invites.js";
 import { listConversations, readConversation } from "./commands/messages.js";
 import { profile } from "./commands/profile.js";
 import { queryIds } from "./commands/query-ids.js";
+import { search } from "./commands/search.js";
 import { whoami } from "./commands/whoami.js";
 import { type BrowserSource, resolveCredentials } from "./lib/auth.js";
 
@@ -37,6 +38,7 @@ const COMMAND_NAMES = new Set([
 	"whoami",
 	"check",
 	"profile",
+	"search",
 	"connections",
 	"invites",
 	"messages",
@@ -332,6 +334,38 @@ program
 		}
 	});
 
+// ============================================================================
+// search - Search profiles
+// ============================================================================
+program
+	.command("search")
+	.description("Search LinkedIn profiles")
+	.option("--query <text>", "Search query text")
+	.option("--json", "Output as JSON")
+	.option("-n, --count <number>", "Number of profiles to show", "20")
+	.option("--all", "Fetch all available profiles (capped at 50)")
+	.option("--fast", "Faster pacing with adaptive slowdown on rate limits")
+	.action(async (options) => {
+		try {
+			if (!options.query || options.query.trim() === "") {
+				throw new Error("Missing required option: --query <text>");
+			}
+			const globalOpts = program.opts();
+			const credentials = await getCredentials(globalOpts);
+			const output = await search(credentials, {
+				query: options.query,
+				json: options.json,
+				all: options.all,
+				count: Number.parseInt(options.count, 10),
+				fast: options.fast,
+				noProgress: globalOpts.progress === false,
+			});
+			console.log(output);
+		} catch (error) {
+			handleError(error);
+		}
+	});
+
 // ============================================================================
 // connections - List connections
 // ============================================================================