Improve package action search results

[kentcdodds]

Summary

• Surface compact matched package action recipes in search results, including exact import snippets for top matching exports.
• Keep broad package searches flexible by only attaching action matches when export-level terms match the query.
• Clarify that createAuthenticatedFetch must be awaited before using the returned fetch wrapper.
• Address CodeRabbit and Bugbot feedback by precomputing package query tokens, prioritizing matched action guidance, and reusing package action helpers.
• Rebased on latest main.

Testing

• npm test -- search.node.test.ts search-format.node.test.ts
• npm run format:check
• npm run typecheck
• npm run lint
• npm run test
• npm run build

  

Summary by CodeRabbit

• New Features

  • Package search now highlights "best action" summaries with import snippets for matched functions.
  • Enhanced query recognition for operation-related keywords (add, create, update, schedule).

• Documentation

  • Clarified asynchronous behavior of authentication initialization with usage example.

• Tests

  • Added test coverage for action-aware package search results and import guidance generation.

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR introduces package action-aware search matching to Kody's MCP search pipeline. It adds types for matched package actions, computes action matches from package export metadata scored against query tokens, formats results with "Best action" import guidance, and expands task lexicon term recognition for operate queries.

Changes

Package Action Matching in Search

Layer / File(s)	Summary
Type Definitions and Contracts packages/worker/src/mcp/tools/search-format.ts	Adds new exported PackageActionMatch type with action subpath, function variants, scoring, and matched terms. Updates SearchMatch union's package variant to include optional actionMatches array.
Search Result Formatting packages/worker/src/mcp/tools/search-format.ts	Introduces helpers to build action-specific import statements (default vs named exports). Formats "Best action" markdown segment using primary non-default function. Transforms actionMatches into structured output with per-function usage strings and action-level scores.
Search Matching and Scoring packages/worker/src/mcp/tools/search.ts	Computes action matches from package exports by scoring meaningful query tokens against export metadata. Generates action-specific import guidance using matched function name. Boosts package candidate lexical score by top action match score. Integrates computed actionMatches into package candidate results.
Query Understanding Enhancement packages/worker/src/mcp/tools/understand-search-query.ts	Extends taskLexicon.operate to recognize add, create, update, and schedule terms, refining operate task classification.
Tests and Documentation packages/worker/src/mcp/tools/search.node.test.ts, packages/worker/src/mcp/tools/search-format.node.test.ts, docs/use/execute.md	Updates test helper to capture optional function metadata (name, description, types). Verifies high-confidence action matches produce import { function } from package guidance. Confirms broad queries fall back to generic search guidance with empty actionMatches. Tests markdown formatting of "Best action" segments. Clarifies createAuthenticatedFetch requires await before use.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~22 minutes

Possibly related PRs

• kentcdodds/kody#246: Modifies shared MCP search modules (search-format.ts, search.ts, understand-search-query.ts) and overlaps in toSlimStructuredMatches and search guidance logic.
• kentcdodds/kody#383: Modifies search-format.ts to refactor buildPackageImportSpecifier helper used in this PR's action-specific import generation.
• kentcdodds/kody#272: Changes how package candidates and guidance are produced in search.ts alongside this PR's action matching integration.

Poem

🐰 A rabbit hops through package exports fine,
Finding functions in each action's design,
Best action picked, import statement clear,
Guidance whispered: "Use this function here!"
Search now smarter—by scoring and deed,
The rabbit brings exactly what you need. ✨

🚥 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%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'Improve package action search results' directly summarizes the main change across all modified files: enhancing search functionality to surface matched package action recipes with import snippets.
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.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch cursor/search-action-results-06f1

---

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 and usage tips.}

[github-actions]

🔎 Preview deployed: https://kody-pr-412.kentcdodds.workers.dev

Worker: kody-pr-412
D1: kody-pr-412-db
KV: kody-pr-412-oauth-kv

Mocks:

• ai: https://kody-pr-412-mock-ai.kentcdodds.workers.dev/__mocks (kody-pr-412-mock-ai)
• cloudflare: https://kody-pr-412-mock-cloudflare.kentcdodds.workers.dev/__mocks (kody-pr-412-mock-cloudflare)

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

packages/worker/src/mcp/tools/search.ts (1)

927-930: ⚡ Quick win

Avoid recomputing query tokens per package row.

extractMeaningfulSearchTokens(input.query) is invariant per query, but it runs once per package row. Precompute it once before the map to reduce repeated tokenization on larger package sets.

♻️ Suggested diff

 function buildPackageCandidates(input: {
 	query: string
 	rows: Array<PackageSearchRow>
 	queryEmbedding: ReadonlyArray<number>
 }): Array<SearchCandidate> {
+	const meaningfulTokens = extractMeaningfulSearchTokens(input.query)
 	return input.rows
 		.map((entry) => {
 			const exports = Array.isArray(entry.projection.exports)
 				? entry.projection.exports
 				: []
@@
 			const actionMatches = buildPackageActionMatches({
 				query: input.query,
-				meaningfulTokens: extractMeaningfulSearchTokens(input.query),
+				meaningfulTokens,
 				exports,
 			})

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/worker/src/mcp/tools/search.ts` around lines 927 - 930,
extractMeaningfulSearchTokens(input.query) is being recomputed for every package
row; precompute it once before iterating packages and reuse the result inside
the map that calls buildPackageActionMatches. Specifically, call
extractMeaningfulSearchTokens(input.query) into a variable (e.g.,
meaningfulTokens) outside the loop/array.map, then pass that variable to
buildPackageActionMatches instead of calling the function inline so
actionMatches is created using the precomputed meaningfulTokens together with
input.query and exports.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@packages/worker/src/mcp/tools/search-format.ts`:
- Around line 647-651: The nextStep construction currently prefers opening the
app when match.hasApp even if an action-specific usage
(primaryAction/primaryActionFunction) exists; change the conditional order so
nextStep first checks for primaryAction && primaryActionFunction and uses `Use
${primaryActionFunction.usage}; inspect search({ entity:
"${match.kodyId}:package" }) only if you need more exports.`, then fall back to
match.hasApp with `Open the app with open_generated_ui({ kody_id:
"${match.kodyId}" }) or inspect package detail...`, and finally the
package-inspect/import fallback using `Inspect package detail... import from
"${buildPackageImportSpecifier(match.name, '.')}".` Apply the same reorder to
the analogous block around the other occurrence (lines ~660-663) so
action-prioritized usage always wins over hasApp.

---

Nitpick comments:
In `@packages/worker/src/mcp/tools/search.ts`:
- Around line 927-930: extractMeaningfulSearchTokens(input.query) is being
recomputed for every package row; precompute it once before iterating packages
and reuse the result inside the map that calls buildPackageActionMatches.
Specifically, call extractMeaningfulSearchTokens(input.query) into a variable
(e.g., meaningfulTokens) outside the loop/array.map, then pass that variable to
buildPackageActionMatches instead of calling the function inline so
actionMatches is created using the precomputed meaningfulTokens together with
input.query and exports.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 764cb75d-2bda-4b4d-9657-4d548109c126

📥 Commits

Reviewing files that changed from the base of the PR and between 1c23974 and 1cfc32f.

📒 Files selected for processing (6)

• docs/use/execute.md
• packages/worker/src/mcp/tools/search-format.node.test.ts
• packages/worker/src/mcp/tools/search-format.ts
• packages/worker/src/mcp/tools/search.node.test.ts
• packages/worker/src/mcp/tools/search.ts
• packages/worker/src/mcp/tools/understand-search-query.ts

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 005623a. Configure here.}