Fix unsafe URL error in RAG search links

[afterrburn]

Summary

• Extract documentPathToUrl function to shared utility (src/utils/url.ts)
• Apply URL transformation in askDocsAgentTool to fix "Invalid or potentially unsafe URL" error
• URLs like Get-Started/quickstart.mdx#7-deploy are now properly transformed to /Get-Started/quickstart#7-deploy

Test plan

• Verify RAG search links in AgentPulse no longer show "Invalid or potentially unsafe URL" error
• Verify existing doc-qa API endpoint still works correctly
• Verify clicking on document links navigates to correct pages

🤖 Generated with Claude Code

Summary by CodeRabbit

• Refactor
  • Centralized document URL path conversion logic into a shared utility function to ensure consistency across all documentation retrieval endpoints.
  • Enhanced URL handling to properly normalize file extensions, clean path segments, and preserve anchor links.
  • Improved error handling with fallback responses when documentation retrieval encounters failures.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

📝 Walkthrough

Walkthrough

A new utility function documentPathToUrl centralizes conversion of doc paths to URLs. Two files were refactored to import and use it instead of local implementations. tools.ts adds URL mapping and a fallback error response. tsconfig gains a path alias for the new utility.

Changes

Cohort / File(s)	Summary
New URL utility function doc-agents/src/utils/url.ts	Adds exported `documentPathToUrl(docPath?: string
Agent pulse tool update doc-agents/src/agent/agent_pulse/tools.ts	Imports documentPathToUrl and maps returned documents to include url: documentPathToUrl(doc.url). Adds catch fallback returning { answer: 'Failed to retrieve documentation', documents: [] } and logs the error.
Doc QA route refactor doc-agents/src/api/doc-qa/route.ts	Removes inline documentPathToUrl implementation and replaces its usages with an import from @utils/url.
TypeScript config doc-agents/tsconfig.json	Adds path alias @utils/* → ./src/utils/* to enable importing the new utility.

🚥 Pre-merge checks | ✅ 1

✅ Passed checks (1 passed)

Check name	Status	Explanation
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.}

---

📜 Recent review details

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between ed8907a and bb657b7.

📒 Files selected for processing (1)

• doc-agents/src/utils/url.ts

🚧 Files skipped from review as they are similar to previous changes (1)

• doc-agents/src/utils/url.ts

_{✏️ Tip: You can disable this entire section by setting review_details to false in your review settings.}

Warning

Review ran into problems

🔥 Problems

Git: Failed to clone repository. Please run the @coderabbitai full review command to re-trigger a full review. If the issue persists, set path_filters to include or exclude specific files.

---

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.}

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In `@doc-agents/src/utils/url.ts`:
- Around line 4-10: documentPathToUrl currently calls docPath.replace and will
throw if docPath is null/undefined or not a string; update the function
signature (documentPathToUrl) to accept a nullable type (e.g., string |
undefined) and add a defensive early-return that checks typeof docPath ===
'string' and docPath.trim() !== '' before proceeding; if the check fails, return
an empty string (or a safe default URL) so the subsequent replace and split
logic (the local variables path, basePath, hash) never run on invalid input.

📜 Review details

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between a3736bc and ed8907a.

📒 Files selected for processing (4)

• doc-agents/src/agent/agent_pulse/tools.ts
• doc-agents/src/api/doc-qa/route.ts
• doc-agents/src/utils/url.ts
• doc-agents/tsconfig.json

🧰 Additional context used

📓 Path-based instructions (1)

doc-agents/**/*.{ts,tsx,js,jsx}

📄 CodeRabbit inference engine (doc-agents/AGENTS.md)

Use Bun instead of NodeJS as the JavaScript runtime and TypeScript for all source code

Files:

• doc-agents/src/utils/url.ts
• doc-agents/src/api/doc-qa/route.ts
• doc-agents/src/agent/agent_pulse/tools.ts

🧬 Code graph analysis (1)

doc-agents/src/agent/agent_pulse/tools.ts (1)

doc-agents/src/utils/url.ts (1)

• documentPathToUrl (4-31)

🔇 Additional comments (3)

doc-agents/tsconfig.json (1)

24-25: Confirm @utils/* alias is honored by build/runtime tooling.

TS paths help compile-time resolution only; please verify your Bun/TypeScript build (or bundler) also resolves @utils/* at runtime (e.g., via your usual typecheck/build run).

doc-agents/src/api/doc-qa/route.ts (1)

13-18: Nice reuse of the shared URL normalizer.

This keeps doc-qa responses consistent with other surfaces.

doc-agents/src/agent/agent_pulse/tools.ts (1)

64-70: Consistent URL normalization in tool responses — LGTM.

_{✏️ Tip: You can disable this entire section by setting review_details to false in your review settings.}