feat: add AI SDK package tool

[oritwoen]

Right now if you want to use regxa from an AI agent, you end up wrapping the helpers yourself. This adds a regxa/ai export with a single packageTool that handles package info, versions, deps, maintainers, and bulk lookups through the existing helper layer.

README updated with AI usage docs, tests cover the operation routing.

Closes #12

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR introduces a new AI SDK tool integration under the regxa/ai subpath, enabling AI agent runtimes to query package metadata across multiple registries. The implementation includes a unified packageTool supporting operations for package metadata, versions, dependencies, maintainers, and bulk lookups, along with documentation and unit tests.

Changes

Cohort / File(s)	Summary
Documentation README.md	Added AI SDK tool usage documentation with TypeScript examples and installation instructions for ai and zod dependencies.
Package Configuration package.json	Added ./ai export entry, introduced ai and zod as development and peer dependencies marked optional.
Build Configuration build.config.ts	Added ./src/ai.ts to the build bundle input sources for inclusion in the distribution.
AI Tool Implementation src/ai.ts	New module implementing packageTool with discriminated union schema supporting operations (package, versions, dependencies, maintainers, bulk-packages) and dispatching to corresponding registry helper functions.
Test Suite test/unit/ai-tool.test.ts	Comprehensive unit tests for packageTool covering all five operations with mocked helpers and output verification.

Sequence Diagram

sequenceDiagram
    actor Agent as AI Agent
    participant Tool as packageTool
    participant Helpers as Registry Helpers

    Agent->>Tool: execute({ operation, purl, ... })
    activate Tool
    
    alt operation == "package"
        Tool->>Helpers: fetchPackageFromPURL(purl, signal)
    else operation == "versions"
        Tool->>Helpers: fetchVersionsFromPURL(purl, signal)
    else operation == "dependencies"
        Tool->>Helpers: fetchDependenciesFromPURL(purl, signal)
    else operation == "maintainers"
        Tool->>Helpers: fetchMaintainersFromPURL(purl, signal)
    else operation == "bulk-packages"
        Tool->>Helpers: bulkFetchPackages(purls, { concurrency, signal })
        Helpers-->>Tool: Map of results
        Tool->>Tool: Convert Map to Object
    end
    
    Helpers-->>Tool: Result
    deactivate Tool
    Tool-->>Agent: Metadata result

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Suggested labels

enhancement

Poem

🐰 A tool hops into place,
Where agents query with grace,
Packages leap from every source,
npm, PyPI, crates of course!
Unified schemas light the way,
For AI seekers, hip-hip-hooray!

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The pull request title 'feat: add AI SDK package tool' clearly and concisely summarizes the main change of adding an AI SDK entrypoint with a package tool.
Linked Issues check	✅ Passed	All coding requirements from issue #12 are met: regxa/ai subpath added with packageTool export supporting all required operations, README documentation added, and unit tests cover operation dispatch routing.
Out of Scope Changes check	✅ Passed	All changes directly support the linked issue objectives. The build config and package.json changes enable the new AI SDK export, and all code changes implement the specified functionality without extraneous modifications.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Description check	✅ Passed	The pull request description directly addresses the changeset: it explains the addition of a regxa/ai export with packageTool, mentions README updates, and references issue closure.

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

✨ Finishing Touches

• 📝 Generate docstrings (stacked PR)
• 📝 Generate docstrings (commit on current branch)

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch ai-package-tool

---

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

[cubic-dev-ai]

No issues found across 6 files

Architecture diagram

sequenceDiagram
    participant LLM as AI SDK (Model)
    participant Tool as NEW: packageTool (regxa/ai)
    participant Zod as Zod Schema
    participant Helpers as Helpers (regxa/core)
    participant Reg as Registry Adapters (npm/PyPI/etc)

    Note over LLM,Reg: NEW: AI Tool Runtime Flow

    LLM->>Tool: execute(input, context)
    Tool->>Zod: parse(input)
    
    alt Validation Failed
        Zod-->>Tool: ValidationError
        Tool-->>LLM: Throw Error
    else Validation Success
        Zod-->>Tool: Validated Input Object
    end

    Note right of Tool: Dispatch based on input.operation

    alt operation: 'package' | 'versions' | 'dependencies' | 'maintainers'
        Tool->>Helpers: CHANGED: fetch[Type]FromPURL(purl, abortSignal)
        Helpers->>Reg: Request metadata
        Reg-->>Helpers: Raw Registry Data
        Helpers-->>Tool: Formatted Resource
    else operation: 'bulk-packages'
        Tool->>Helpers: NEW: bulkFetchPackages(purls, { concurrency, signal })
        loop For each PURL
            Helpers->>Reg: Concurrent Fetch
            Reg-->>Helpers: Data
        end
        Helpers-->>Tool: Map<PURL, Data>
        Tool->>Tool: Convert Map to Record/Object
    end

    Tool-->>LLM: JSON Result for Model Context

Loading

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 96a8c768d8

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".