feat(search): expose page to match the API

[Kikobeats]

Summary

• The Google provider now paginates with page instead of start (api@7acc621 / src/providers/google.js)
• buildUrl forwards page when it is greater than 1
• CLI --page, MCP page, and docs match that contract

Test plan

• microlink search "the matrix" --page 2 returns the second results page
• microlink search --help lists --page
• await microlink.search('q', { page: 2 }) hits ?page=2
• First page still omits the page query param

Made with Cursor

Summary by CodeRabbit

• New Features

  • Added support for selecting a specific search results page with the page option.
  • Page selection is available across the search API, CLI, and MCP tool.
  • Added CLI usage examples for retrieving later result pages.

• Documentation

  • Updated search and pagination documentation to explain direct page selection and continued navigation with .next().
  • Documented the default starting page and valid page usage.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 58a577f6-d65c-476e-b63e-eab44f0c0fd5

📥 Commits

Reviewing files that changed from the base of the PR and between 2cc8f3c and 9854d3e.

📒 Files selected for processing (9)

• README.md
• packages/core/bin/help.js
• packages/core/test/cli.mjs
• packages/mcp/src/schemas.js
• packages/mcp/src/tools/search.js
• packages/search/docs/README.md
• packages/search/src/index.d.ts
• packages/search/src/index.js
• packages/search/test/build-url.js

Included review availability: Your plan provides up to 1 included review per hour; 0 remain after this review.

---

📝 Walkthrough

Walkthrough

Search now supports selecting a result page. The option is validated in the MCP schema, serialized into search URLs, exposed in CLI and MCP help, documented, and covered by tests.

Changes

Search pagination

Layer / File(s)	Summary
Search URL pagination packages/search/src/index.d.ts, packages/search/src/index.js, packages/search/test/build-url.js	buildUrl accepts page and adds it to URLs when greater than 1. The search client passes the configured page. Tests cover default, first, and later pages.
Pagination interface exposure packages/mcp/src/schemas.js, packages/mcp/src/tools/search.js, packages/core/bin/help.js, packages/core/test/cli.mjs	The MCP schema validates an optional positive integer page. MCP and CLI help describe the option, and CLI tests verify the --page flag.
Pagination documentation README.md, packages/search/docs/README.md	Documentation describes direct page selection and chaining with .next().

Estimated code review effort: 2 (Simple) | ~10 minutes

Merge Risk: ⚪ Minimal · up to 9854d

This PR aligns search pagination across the API, CLI, MCP interface, and documentation; no actionable merge-blocking risk remains beyond normal checks and review.

Sequence Diagram(s)

sequenceDiagram
  participant SearchClient
  participant buildUrl
  participant SearchRequest
  SearchClient->>buildUrl: pass page option
  buildUrl->>SearchRequest: add page query parameter when page > 1

Loading

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 1 functions across 7 files. (2 skipped: 2 …	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: exposing the search API's page parameter across the search implementation and interfaces.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

Full details: Docstring Coverage

Explanation

Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 1 functions across 7 files. (2 skipped: 2 unsupported.)

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/search-page

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coveralls]

Coverage Report for CI Build 32818281580

Warning

No base build found for commit 2cc8f3c on master.
Coverage changes can't be calculated without a base build.
If a base build is processing, this comment will update automatically when it completes.

Coverage: 76.298%

Details

• Patch coverage: 5 of 5 lines across 3 files are fully covered (100%).

Uncovered Changes

No uncovered changes found.

Coverage Regressions

Requires a base build to compare against. How to fix this →

---

Coverage Stats

Relevant Lines:	4711
Covered Lines:	3599
Line Coverage:	76.4%
Relevant Branches:	719
Covered Branches:	544
Branch Coverage:	75.66%
Branches in Coverage %:	Yes
Coverage Strength:	13.77 hits per line

---

💛 - Coveralls