package-query 0.1.0__tar.gz

package_query-0.1.0/PKG-INFO

@@ -0,0 +1,181 @@
+Metadata-Version: 2.3
+Name: package-query
+Version: 0.1.0
+Summary: Query latest package versions from PyPI, npm, crates.io, Docker Hub, and GitHub Actions
+Keywords: mcp,pypi,npm,crates.io,docker,github actions
+Author: Henrique
+Author-email: Henrique <henriquemoreira10fk@gmail.com>
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Dist: curl-cffi>=0.14.0
+Requires-Dist: orjson>=3.11.5
+Requires-Dist: pydantic>=2.12.5
+Requires-Dist: fastmcp>=2.14.2 ; extra == 'mcp'
+Requires-Python: >=3.10, <3.15
+Project-URL: Changelog, https://github.com/henrique-coder/package-query/releases
+Project-URL: Documentation, https://github.com/henrique-coder/package-query#readme
+Project-URL: Homepage, https://github.com/henrique-coder/package-query
+Project-URL: Issues, https://github.com/henrique-coder/package-query/issues
+Project-URL: Repository, https://github.com/henrique-coder/package-query.git
+Provides-Extra: mcp
+Description-Content-Type: text/markdown
+
+# package-query
+
+Query the latest package versions from **PyPI**, **npm**, **crates.io**, **Docker Hub**, and **GitHub Actions** — directly from Python or as an MCP server for AI agents.
+
+## Installation
+
+```bash
+# Core library only
+uv pip install package-query
+
+# With MCP server support
+uv pip install "package-query[mcp]"
+```
+
+## Python Usage
+
+```python
+import asyncio
+from package_query import PackageQuery, PackageInfo
+
+async def main():
+    pq = PackageQuery()
+
+    info: PackageInfo = await pq.query("pypi", "requests")
+    print(f"{info.name}=={info.version}")
+
+    info = await pq.query("npm", "express")
+    print(f"{info.name}=={info.version}")
+
+    info = await pq.query("github-actions", "actions/checkout")
+    print(f"{info.name}=={info.version}")
+
+asyncio.run(main())
+```
+
+### Supported Registries
+
+| Registry         | Example Package    |
+| ---------------- | ------------------ |
+| `pypi`           | `requests`         |
+| `npm`            | `express`          |
+| `crates`         | `serde`            |
+| `docker`         | `nginx`            |
+| `github-actions` | `actions/checkout` |
+
+## MCP Server
+
+The MCP server allows AI agents (Claude, Copilot, Cursor, etc.) to query package versions without web search.
+
+### Running the Server
+
+```bash
+# If installed with [mcp] extra
+package-query-mcp
+
+# Or from source
+uv run --extra mcp package-query-mcp
+```
+
+### IDE Configuration
+
+#### VS Code / Cursor
+
+Add to your `settings.json`:
+
+```json
+{
+  "mcp": {
+    "servers": {
+      "package-query": {
+        "command": "uvx",
+        "args": ["--from", "package-query[mcp]", "package-query-mcp"]
+      }
+    }
+  }
+}
+```
+
+Or if installed globally:
+
+```json
+{
+  "mcp": {
+    "servers": {
+      "package-query": {
+        "command": "package-query-mcp"
+      }
+    }
+  }
+}
+```
+
+#### Claude Desktop
+
+Add to `~/.config/Claude/claude_desktop_config.json` (Linux) or equivalent:
+
+```json
+{
+  "mcpServers": {
+    "package-query": {
+      "command": "uvx",
+      "args": ["--from", "package-query[mcp]", "package-query-mcp"]
+    }
+  }
+}
+```
+
+#### Antigravity IDE
+
+Add to `~/.gemini/antigravity/mcp_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "package-query": {
+      "command": "uvx",
+      "args": ["--from", "package-query[mcp]", "package-query-mcp"]
+    }
+  }
+}
+```
+
+### Available Tools
+
+| Tool                  | Description                         |
+| --------------------- | ----------------------------------- |
+| `get_package_version` | Get the latest version of a package |
+
+**Parameters:**
+
+- `registry` (string): One of `pypi`, `npm`, `crates`, `docker`, `github-actions`
+- `package` (string): Package name
+- `include_prerelease` (bool, optional): Include pre-release versions
+
+## Development
+
+```bash
+# Clone and install all dependencies
+git clone https://github.com/henrique-coder/package-query.git
+cd package-query
+uv sync --upgrade --all-groups --all-extras
+just lint
+just format
+```
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

package_query-0.1.0/README.md

@@ -0,0 +1,148 @@
+# package-query
+
+Query the latest package versions from **PyPI**, **npm**, **crates.io**, **Docker Hub**, and **GitHub Actions** — directly from Python or as an MCP server for AI agents.
+
+## Installation
+
+```bash
+# Core library only
+uv pip install package-query
+
+# With MCP server support
+uv pip install "package-query[mcp]"
+```
+
+## Python Usage
+
+```python
+import asyncio
+from package_query import PackageQuery, PackageInfo
+
+async def main():
+    pq = PackageQuery()
+
+    info: PackageInfo = await pq.query("pypi", "requests")
+    print(f"{info.name}=={info.version}")
+
+    info = await pq.query("npm", "express")
+    print(f"{info.name}=={info.version}")
+
+    info = await pq.query("github-actions", "actions/checkout")
+    print(f"{info.name}=={info.version}")
+
+asyncio.run(main())
+```
+
+### Supported Registries
+
+| Registry         | Example Package    |
+| ---------------- | ------------------ |
+| `pypi`           | `requests`         |
+| `npm`            | `express`          |
+| `crates`         | `serde`            |
+| `docker`         | `nginx`            |
+| `github-actions` | `actions/checkout` |
+
+## MCP Server
+
+The MCP server allows AI agents (Claude, Copilot, Cursor, etc.) to query package versions without web search.
+
+### Running the Server
+
+```bash
+# If installed with [mcp] extra
+package-query-mcp
+
+# Or from source
+uv run --extra mcp package-query-mcp
+```
+
+### IDE Configuration
+
+#### VS Code / Cursor
+
+Add to your `settings.json`:
+
+```json
+{
+  "mcp": {
+    "servers": {
+      "package-query": {
+        "command": "uvx",
+        "args": ["--from", "package-query[mcp]", "package-query-mcp"]
+      }
+    }
+  }
+}
+```
+
+Or if installed globally:
+
+```json
+{
+  "mcp": {
+    "servers": {
+      "package-query": {
+        "command": "package-query-mcp"
+      }
+    }
+  }
+}
+```
+
+#### Claude Desktop
+
+Add to `~/.config/Claude/claude_desktop_config.json` (Linux) or equivalent:
+
+```json
+{
+  "mcpServers": {
+    "package-query": {
+      "command": "uvx",
+      "args": ["--from", "package-query[mcp]", "package-query-mcp"]
+    }
+  }
+}
+```
+
+#### Antigravity IDE
+
+Add to `~/.gemini/antigravity/mcp_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "package-query": {
+      "command": "uvx",
+      "args": ["--from", "package-query[mcp]", "package-query-mcp"]
+    }
+  }
+}
+```
+
+### Available Tools
+
+| Tool                  | Description                         |
+| --------------------- | ----------------------------------- |
+| `get_package_version` | Get the latest version of a package |
+
+**Parameters:**
+
+- `registry` (string): One of `pypi`, `npm`, `crates`, `docker`, `github-actions`
+- `package` (string): Package name
+- `include_prerelease` (bool, optional): Include pre-release versions
+
+## Development
+
+```bash
+# Clone and install all dependencies
+git clone https://github.com/henrique-coder/package-query.git
+cd package-query
+uv sync --upgrade --all-groups --all-extras
+just lint
+just format
+```
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

package_query-0.1.0/pyproject.toml

@@ -0,0 +1,108 @@
+[project]
+name = "package-query"
+version = "0.1.0"
+description = "Query latest package versions from PyPI, npm, crates.io, Docker Hub, and GitHub Actions"
+readme = "README.md"
+authors = [
+    { name = "Henrique", email = "henriquemoreira10fk@gmail.com" }
+]
+keywords = ["mcp", "pypi", "npm", "crates.io", "docker", "github actions"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Internet :: WWW/HTTP",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+requires-python = ">=3.10,<3.15"
+dependencies = [
+    "curl-cffi>=0.14.0",
+    "orjson>=3.11.5",
+    "pydantic>=2.12.5",
+]
+
+[project.optional-dependencies]
+mcp = [
+    "fastmcp>=2.14.2"
+]
+
+[dependency-groups]
+dev = [
+    "rich>=14.2.0"
+]
+lint = [
+    "ruff>=0.14.10",
+    "ty>=0.0.9",
+]
+
+[project.urls]
+Homepage = "https://github.com/henrique-coder/package-query"
+Documentation = "https://github.com/henrique-coder/package-query#readme"
+Repository = "https://github.com/henrique-coder/package-query.git"
+Issues = "https://github.com/henrique-coder/package-query/issues"
+Changelog = "https://github.com/henrique-coder/package-query/releases"
+
+[tool.ruff]
+line-length = 120
+indent-width = 4
+
+[tool.ruff.lint]
+select = [
+    "F",      # Pyflakes: unused imports/variables, undefined names
+    "E",      # pycodestyle errors: basic PEP 8 style violations
+    "W",      # pycodestyle warnings: whitespace issues, blank lines
+    "I",      # isort: import sorting and organization
+    "UP",     # pyupgrade: upgrade syntax for newer Python versions
+    "B",      # flake8-bugbear: common bugs and design problems
+    "SIM",    # flake8-simplify: simplify complex code patterns
+    "C4",     # flake8-comprehensions: better list/dict/set comprehensions
+    "PIE",    # flake8-pie: misc. lints (unnecessary pass, duplicate keys)
+    "RUF",    # Ruff-specific: modern Python best practices
+    "PERF",   # Perflint: performance anti-patterns
+    "FURB",   # refurb: modernize legacy Python idioms
+    "PTH",    # flake8-use-pathlib: prefer pathlib over os.path
+    "T20",    # flake8-print: detect leftover print() statements
+    "TCH",    # flake8-type-checking: optimize TYPE_CHECKING imports
+    "PL",     # Pylint: broad set of code quality checks
+    "D205",   # 1 blank line required between docstring and code
+]
+ignore = [
+    "PLR0912",   # Too many branches (complex validation logic is acceptable)
+    "PLR0913",   # Too many arguments in function definition (common in APIs)
+    "PLR2004",   # Magic value used in comparison (too strict for general use)
+]
+fixable = ["ALL"]            # Allow auto-fix for all enabled rules
+dummy-variable-rgx = "^_$"   # Only underscore is considered a dummy variable
+
+[tool.ruff.lint.isort]
+lines-after-imports = 2             # PEP 8: two blank lines after imports
+force-sort-within-sections = true   # Alphabetical order within each section
+split-on-trailing-comma = true      # Trailing comma triggers multi-line format
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"   # Google-style docstrings (Args, Returns, Raises)
+
+[tool.ruff.lint.flake8-quotes]
+docstring-quotes = "double"   # Docstrings must use triple double quotes
+
+[tool.ruff.format]
+quote-style = "double"              # Strings use double quotes (PEP 8 preference)
+indent-style = "space"              # Spaces over tabs (PEP 8)
+line-ending = "lf"                  # Unix-style line endings
+docstring-code-format = true        # Format code examples inside docstrings
+skip-magic-trailing-comma = false   # Preserve trailing commas as formatting hints
+
+[project.scripts]
+package-query-mcp = "package_query.mcp_server:main"
+
+[build-system]
+requires = ["uv_build"]
+build-backend = "uv_build"

package_query-0.1.0/src/package_query/__init__.py

@@ -0,0 +1,5 @@
+from package_query.client import PackageQuery
+from package_query.models import PackageInfo
+
+
+__all__ = ["PackageInfo", "PackageQuery"]

package_query-0.1.0/src/package_query/client.py

@@ -0,0 +1,41 @@
+from typing import Final
+
+from package_query.models import PackageInfo
+from package_query.providers.crates import CratesProvider
+from package_query.providers.dockerhub import DockerHubProvider
+from package_query.providers.github_actions import GitHubActionsProvider
+from package_query.providers.npm import NpmProvider
+from package_query.providers.pypi import PyPIProvider
+
+
+class PackageQuery:
+    REGISTRIES: Final[dict[str, type]] = {
+        "pypi": PyPIProvider,
+        "github-actions": GitHubActionsProvider,
+        "npm": NpmProvider,
+        "crates": CratesProvider,
+        "docker": DockerHubProvider,
+    }
+
+    async def query(
+        self,
+        registry: str,
+        package: str,
+        *,
+        include_prerelease: bool = False,
+        source: str | None = None,
+        fallback: bool = True,
+    ) -> PackageInfo:
+        provider_class = self.REGISTRIES.get(registry.lower())
+        if provider_class is None:
+            supported: str = ", ".join(self.REGISTRIES.keys())
+            raise ValueError(f"Unsupported registry '{registry}'. Supported: {supported}")
+        return await provider_class().get_package_info(
+            package,
+            include_prerelease=include_prerelease,
+            source=source,
+            fallback=fallback,
+        )
+
+    def register(self, name: str, provider: type) -> None:
+        self.REGISTRIES[name.lower()] = provider

package_query-0.1.0/src/package_query/constants.py

@@ -0,0 +1,33 @@
+from re import Pattern, compile
+from typing import Final
+
+
+PYPI_PACKAGE_PATTERN: Final[Pattern[str]] = compile(r"^[a-zA-Z0-9_-]+$")
+GITHUB_REPO_PATTERN: Final[Pattern[str]] = compile(r"^[a-zA-Z0-9](?:[a-zA-Z0-9._-]*[a-zA-Z0-9])?/[a-zA-Z0-9._-]+$")
+NPM_PACKAGE_PATTERN: Final[Pattern[str]] = compile(r"^(@[a-zA-Z0-9_-]+/)?[a-zA-Z0-9._-]+$")
+CRATES_PACKAGE_PATTERN: Final[Pattern[str]] = compile(r"^[a-zA-Z][a-zA-Z0-9_-]*$")
+DOCKER_IMAGE_PATTERN: Final[Pattern[str]] = compile(r"^[a-z0-9_-]+(/[a-z0-9._-]+)?$")
+
+PIWHEELS_BASE_URL: Final[str] = "https://www.piwheels.org/project"
+PYPI_BASE_URL: Final[str] = "https://pypi.org/project"
+GITHUB_API_BASE_URL: Final[str] = "https://api.github.com/repos"
+GITHUB_BASE_URL: Final[str] = "https://github.com"
+NPM_REGISTRY_URL: Final[str] = "https://registry.npmjs.org"
+NPM_BASE_URL: Final[str] = "https://www.npmjs.com/package"
+CRATES_API_URL: Final[str] = "https://crates.io/api/v1/crates"
+CRATES_BASE_URL: Final[str] = "https://crates.io/crates"
+DOCKERHUB_API_URL: Final[str] = "https://hub.docker.com/v2/repositories"
+DOCKERHUB_BASE_URL: Final[str] = "https://hub.docker.com/r"
+
+HTTP_HEADERS: Final[dict[str, str]] = {
+    "User-Agent": "package-query/1.0",
+    "Accept": "application/json",
+}
+
+GITHUB_HEADERS: Final[dict[str, str]] = {
+    "User-Agent": "package-query/1.0",
+    "Accept": "application/vnd.github+json",
+}
+
+MAJOR_VERSION_PATTERN: Final[Pattern[str]] = compile(r"^v(\d+)$")
+SEMVER_PATTERN: Final[Pattern[str]] = compile(r"^v(\d+)\.(\d+)\.(\d+)$")

package_query-0.1.0/src/package_query/exceptions.py

@@ -0,0 +1,10 @@
+class PackageNotFoundError(Exception):
+    pass
+
+
+class InvalidPackageNameError(ValueError):
+    pass
+
+
+class RegistryError(Exception):
+    pass

package_query-0.1.0/src/package_query/http.py

@@ -0,0 +1,13 @@
+from typing import Any
+
+from curl_cffi.requests import AsyncSession
+import orjson
+
+
+async def fetch_json(url: str, headers: dict[str, str]) -> dict[str, Any]:
+    async with AsyncSession() as session:
+        response = await session.get(url, headers=headers)
+    if response.status_code == 404:
+        raise ValueError("Not found")
+    response.raise_for_status()
+    return orjson.loads(response.content)

package_query-0.1.0/src/package_query/mcp_server.py

@@ -0,0 +1,48 @@
+"""
+MCP Server for package-query.
+
+Exposes package version queries to AI agents via Model Context Protocol.
+"""
+
+from fastmcp import FastMCP
+
+from package_query import PackageQuery
+
+
+mcp = FastMCP(
+    "package-query",
+    "Query latest package versions from PyPI, npm, crates.io, Docker Hub, and GitHub Actions",
+)
+
+
+@mcp.tool()
+async def get_package_version(
+    registry: str,
+    package: str,
+    include_prerelease: bool = False,
+) -> str:
+    """
+    Get the latest version of a package from a registry.
+
+    Args:
+        registry: One of: pypi, npm, crates, docker, github-actions
+        package: Package name (e.g. "requests", "express", "nginx", "actions/checkout")
+        include_prerelease: Include pre-release versions if True (default: False)
+
+    Returns:
+        A formatted string with package name, version, and registry URL
+    """
+    pq = PackageQuery()
+    info = await pq.query(registry, package, include_prerelease=include_prerelease)
+    return f"{info.name}=={info.version} ({info.registry_url})"
+
+
+def main() -> None:
+    """
+    Entry point for the MCP server.
+    """
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()

package_query-0.1.0/src/package_query/models.py

@@ -0,0 +1,20 @@
+from typing import Any
+
+from pydantic import BaseModel
+
+
+class PackageInfo(BaseModel):
+    name: str
+    version: str
+    summary: str | None = None
+    released_at: str | None = None
+    is_prerelease: bool = False
+    homepage_url: str | None = None
+    registry_url: str | None = None
+    registry: str | None = None
+    source_used: str | None = None
+    sources_failed: list[str] = []
+    sources_remaining: list[str] = []
+
+    def to_dict(self) -> dict[str, Any]:
+        return self.model_dump()

package_query-0.1.0/src/package_query/providers/__init__.py

@@ -0,0 +1,4 @@
+from package_query.providers.base import PackageProvider
+
+
+__all__ = ["PackageProvider"]

package_query-0.1.0/src/package_query/providers/base.py

@@ -0,0 +1,7 @@
+from typing import Protocol
+
+from package_query.models import PackageInfo
+
+
+class PackageProvider(Protocol):
+    async def get_package_info(self, package: str) -> PackageInfo: ...

package_query-0.1.0/src/package_query/providers/crates.py

@@ -0,0 +1,60 @@
+from typing import Final
+
+from package_query.constants import (
+    CRATES_API_URL,
+    CRATES_BASE_URL,
+    CRATES_PACKAGE_PATTERN,
+    HTTP_HEADERS,
+)
+from package_query.http import fetch_json
+from package_query.models import PackageInfo
+
+
+class CratesProvider:
+    REGISTRY_NAME: Final[str] = "crates"
+    SOURCE_NAME: Final[str] = "crates.io"
+
+    async def get_package_info(
+        self,
+        package: str,
+        *,
+        include_prerelease: bool = False,
+        source: str | None = None,
+        fallback: bool = True,
+    ) -> PackageInfo:
+        if not CRATES_PACKAGE_PATTERN.match(package):
+            raise ValueError(f"Invalid crate name '{package}'")
+
+        url: str = f"{CRATES_API_URL}/{package}"
+        data: dict = await fetch_json(url, HTTP_HEADERS)
+
+        crate: dict = data.get("crate", {})
+        versions: list[dict] = data.get("versions", [])
+
+        version: str = crate.get("max_version", "")
+        released_at: str | None = None
+        is_prerelease: bool = False
+
+        for v in versions:
+            if v.get("num") == version:
+                released_at = v.get("created_at")
+                is_prerelease = v.get("yanked", False)
+                break
+
+        if include_prerelease and versions:
+            version = versions[0].get("num", version)
+            released_at = versions[0].get("created_at")
+
+        return PackageInfo(
+            name=crate.get("name", package),
+            version=version,
+            summary=crate.get("description"),
+            released_at=released_at[:19] + "Z" if released_at else None,
+            is_prerelease=is_prerelease,
+            homepage_url=crate.get("homepage") or f"{CRATES_BASE_URL}/{package}",
+            registry_url=f"{CRATES_BASE_URL}/{package}",
+            registry=self.REGISTRY_NAME,
+            source_used=self.SOURCE_NAME,
+            sources_failed=[],
+            sources_remaining=[],
+        )

package_query-0.1.0/src/package_query/providers/dockerhub.py

@@ -0,0 +1,64 @@
+from typing import Final
+
+from package_query.constants import (
+    DOCKER_IMAGE_PATTERN,
+    DOCKERHUB_API_URL,
+    DOCKERHUB_BASE_URL,
+    HTTP_HEADERS,
+)
+from package_query.http import fetch_json
+from package_query.models import PackageInfo
+
+
+class DockerHubProvider:
+    REGISTRY_NAME: Final[str] = "docker"
+    SOURCE_NAME: Final[str] = "dockerhub"
+
+    async def get_package_info(
+        self,
+        package: str,
+        *,
+        include_prerelease: bool = False,
+        source: str | None = None,
+        fallback: bool = True,
+    ) -> PackageInfo:
+        if "/" not in package:
+            package = f"library/{package}"
+
+        if not DOCKER_IMAGE_PATTERN.match(package):
+            raise ValueError(f"Invalid Docker image name '{package}'")
+
+        namespace, repo = package.split("/", 1)
+        tags_url: str = f"{DOCKERHUB_API_URL}/{namespace}/{repo}/tags?page_size=10"
+        data: dict = await fetch_json(tags_url, HTTP_HEADERS)
+
+        results: list[dict] = data.get("results", [])
+        if not results:
+            raise ValueError(f"Docker image '{package}' has no tags")
+
+        latest_tag: dict | None = None
+        for tag in results:
+            if tag.get("name") == "latest":
+                latest_tag = tag
+                break
+
+        if not latest_tag:
+            latest_tag = results[0]
+
+        version: str = latest_tag.get("name", "latest")
+        last_updated: str | None = latest_tag.get("last_updated")
+        display_name: str = repo if namespace == "library" else package
+
+        return PackageInfo(
+            name=display_name,
+            version=version,
+            summary=None,
+            released_at=last_updated[:19] + "Z" if last_updated else None,
+            is_prerelease=False,
+            homepage_url=f"{DOCKERHUB_BASE_URL}/{package}",
+            registry_url=f"{DOCKERHUB_BASE_URL}/{package}",
+            registry=self.REGISTRY_NAME,
+            source_used=self.SOURCE_NAME,
+            sources_failed=[],
+            sources_remaining=[],
+        )

package_query-0.1.0/src/package_query/providers/github_actions.py

@@ -0,0 +1,93 @@
+from typing import Final
+
+from curl_cffi.requests import AsyncSession
+import orjson
+
+from package_query.constants import (
+    GITHUB_API_BASE_URL,
+    GITHUB_BASE_URL,
+    GITHUB_HEADERS,
+    GITHUB_REPO_PATTERN,
+    MAJOR_VERSION_PATTERN,
+    SEMVER_PATTERN,
+)
+from package_query.models import PackageInfo
+
+
+class GitHubActionsProvider:
+    REGISTRY_NAME: Final[str] = "github-actions"
+    SOURCE_NAME: Final[str] = "github-api"
+
+    async def get_package_info(
+        self,
+        package: str,
+        *,
+        include_prerelease: bool = False,
+        source: str | None = None,
+        fallback: bool = True,
+    ) -> PackageInfo:
+        if not GITHUB_REPO_PATTERN.match(package):
+            raise ValueError(f"Invalid action format '{package}'. Expected 'owner/repo'")
+
+        owner, repo = package.split("/", 1)
+        tags_url: str = f"{GITHUB_API_BASE_URL}/{owner}/{repo}/tags"
+        repo_url: str = f"{GITHUB_API_BASE_URL}/{owner}/{repo}"
+
+        async with AsyncSession() as session:
+            response = await session.get(tags_url, headers=GITHUB_HEADERS)
+
+            if response.status_code == 404:
+                raise ValueError(f"Action '{package}' not found")
+
+            response.raise_for_status()
+            tags: list[dict] = orjson.loads(response.content)
+
+            if not tags:
+                raise ValueError(f"Action '{package}' has no tags")
+
+            major_versions: dict[int, str] = {}
+            latest_semver: tuple[int, int, int] | None = None
+            latest_semver_tag: str | None = None
+
+            for tag in tags:
+                name: str = tag.get("name", "")
+                if major_match := MAJOR_VERSION_PATTERN.match(name):
+                    major_num: int = int(major_match.group(1))
+                    if major_num not in major_versions:
+                        major_versions[major_num] = name
+                elif semver_match := SEMVER_PATTERN.match(name):
+                    version_tuple: tuple[int, int, int] = (
+                        int(semver_match.group(1)),
+                        int(semver_match.group(2)),
+                        int(semver_match.group(3)),
+                    )
+                    if latest_semver is None or version_tuple > latest_semver:
+                        latest_semver, latest_semver_tag = version_tuple, name
+
+            if major_versions:
+                version: str = major_versions[max(major_versions.keys())]
+            elif latest_semver_tag:
+                version = latest_semver_tag
+            else:
+                version = tags[0].get("name", "unknown")
+
+            repo_response = await session.get(repo_url, headers=GITHUB_HEADERS)
+
+        description: str | None = None
+        if repo_response.status_code == 200:
+            repo_data: dict = orjson.loads(repo_response.content)
+            description = repo_data.get("description")
+
+        return PackageInfo(
+            name=package,
+            version=version,
+            summary=description,
+            released_at=None,
+            is_prerelease=False,
+            homepage_url=f"{GITHUB_BASE_URL}/{package}",
+            registry_url=f"{GITHUB_BASE_URL}/{package}",
+            registry=self.REGISTRY_NAME,
+            source_used=self.SOURCE_NAME,
+            sources_failed=[],
+            sources_remaining=[],
+        )

package_query-0.1.0/src/package_query/providers/npm.py

@@ -0,0 +1,52 @@
+from typing import Final
+
+from package_query.constants import (
+    HTTP_HEADERS,
+    NPM_BASE_URL,
+    NPM_PACKAGE_PATTERN,
+    NPM_REGISTRY_URL,
+)
+from package_query.http import fetch_json
+from package_query.models import PackageInfo
+
+
+class NpmProvider:
+    REGISTRY_NAME: Final[str] = "npm"
+    SOURCE_NAME: Final[str] = "npmjs"
+
+    async def get_package_info(
+        self,
+        package: str,
+        *,
+        include_prerelease: bool = False,
+        source: str | None = None,
+        fallback: bool = True,
+    ) -> PackageInfo:
+        if not NPM_PACKAGE_PATTERN.match(package):
+            raise ValueError(f"Invalid npm package name '{package}'")
+
+        url: str = f"{NPM_REGISTRY_URL}/{package}"
+        data: dict = await fetch_json(url, HTTP_HEADERS)
+
+        dist_tags: dict = data.get("dist-tags", {})
+        version: str = dist_tags.get("latest", "")
+
+        if include_prerelease and "next" in dist_tags:
+            version = dist_tags["next"]
+
+        time_data: dict = data.get("time", {})
+        released_at: str | None = time_data.get(version)
+
+        return PackageInfo(
+            name=data.get("name", package),
+            version=version,
+            summary=data.get("description"),
+            released_at=released_at.replace("Z", "").split(".")[0] + "Z" if released_at else None,
+            is_prerelease="next" in dist_tags and version == dist_tags.get("next"),
+            homepage_url=f"{NPM_BASE_URL}/{package}",
+            registry_url=f"{NPM_BASE_URL}/{package}",
+            registry=self.REGISTRY_NAME,
+            source_used=self.SOURCE_NAME,
+            sources_failed=[],
+            sources_remaining=[],
+        )

package_query-0.1.0/src/package_query/providers/pypi.py

@@ -0,0 +1,145 @@
+from datetime import datetime
+from typing import Any, Final
+
+from curl_cffi.requests import AsyncSession
+import orjson
+
+from package_query.constants import HTTP_HEADERS, PYPI_PACKAGE_PATTERN
+from package_query.models import PackageInfo
+
+
+class PyPIPiwheelsSource:
+    NAME: Final[str] = "piwheels"
+    BASE_URL: Final[str] = "https://www.piwheels.org/project"
+
+    async def fetch(self, package: str, include_prerelease: bool = False) -> PackageInfo:
+        url: str = f"{self.BASE_URL}/{package}/json/"
+
+        async with AsyncSession() as session:
+            response = await session.get(url, headers=HTTP_HEADERS)
+
+        if response.status_code == 404:
+            raise ValueError(f"Package '{package}' not found")
+
+        response.raise_for_status()
+        data: dict = orjson.loads(response.content)
+        releases: dict = data.get("releases", {})
+
+        if not releases:
+            raise ValueError(f"Package '{package}' has no releases")
+
+        latest_version: str | None = None
+        latest_released: datetime | None = None
+        is_prerelease: bool = False
+
+        for version, info in releases.items():
+            if info.get("yanked", False):
+                continue
+            released_str: str | None = info.get("released")
+            if not released_str:
+                continue
+            released: datetime = datetime.fromisoformat(released_str.replace(" ", "T"))
+            version_is_prerelease: bool = info.get("prerelease", False)
+
+            if include_prerelease or not version_is_prerelease:
+                if latest_released is None or released > latest_released:
+                    latest_version = version
+                    latest_released = released
+                    is_prerelease = version_is_prerelease
+
+        if latest_version is None:
+            raise ValueError(f"Package '{package}' has no valid releases")
+
+        return PackageInfo(
+            name=data.get("package", package),
+            version=latest_version,
+            summary=data.get("summary"),
+            released_at=latest_released.strftime("%Y-%m-%dT%H:%M:%SZ") if latest_released else None,
+            is_prerelease=is_prerelease,
+            homepage_url=data.get("pypi_url"),
+            registry_url=data.get("pypi_url"),
+        )
+
+
+class PyPIOfficialSource:
+    NAME: Final[str] = "pypi"
+    BASE_URL: Final[str] = "https://pypi.org/pypi"
+
+    async def fetch(self, package: str, include_prerelease: bool = False) -> PackageInfo:
+        url: str = f"{self.BASE_URL}/{package}/json"
+
+        async with AsyncSession() as session:
+            response = await session.get(url, headers=HTTP_HEADERS)
+
+        if response.status_code == 404:
+            raise ValueError(f"Package '{package}' not found")
+
+        response.raise_for_status()
+        data: dict = orjson.loads(response.content)
+
+        info: dict = data.get("info", {})
+        version: str = info.get("version", "")
+        releases: dict[str, list[dict[str, Any]]] = data.get("releases", {})
+
+        released_at: str | None = None
+        if releases.get(version):
+            upload_time: str | None = releases[version][0].get("upload_time_iso_8601")
+            if upload_time:
+                released_at = upload_time[:19] + "Z"
+
+        return PackageInfo(
+            name=info.get("name", package),
+            version=version,
+            summary=info.get("summary"),
+            released_at=released_at,
+            is_prerelease=False,
+            homepage_url=info.get("project_url") or f"https://pypi.org/project/{package}",
+            registry_url=f"https://pypi.org/project/{package}",
+        )
+
+
+class PyPIProvider:
+    REGISTRY_NAME: Final[str] = "pypi"
+    SOURCES: Final[list[type]] = [PyPIPiwheelsSource, PyPIOfficialSource]
+    SOURCE_MAP: Final[dict[str, type]] = {
+        "piwheels": PyPIPiwheelsSource,
+        "pypi": PyPIOfficialSource,
+    }
+
+    async def get_package_info(
+        self,
+        package: str,
+        *,
+        include_prerelease: bool = False,
+        source: str | None = None,
+        fallback: bool = True,
+    ) -> PackageInfo:
+        if not PYPI_PACKAGE_PATTERN.match(package):
+            raise ValueError(f"Invalid package name '{package}'. Use only a-zA-Z0-9_-")
+
+        if source:
+            source_class = self.SOURCE_MAP.get(source.lower())
+            if not source_class:
+                raise ValueError(f"Unknown source '{source}'. Available: {list(self.SOURCE_MAP.keys())}")
+            sources = [source_class] + ([s for s in self.SOURCES if s != source_class] if fallback else [])
+        else:
+            sources = list(self.SOURCES) if fallback else [self.SOURCES[0]]
+
+        sources_failed: list[str] = []
+        last_error: Exception | None = None
+
+        for i, source_class in enumerate(sources):
+            try:
+                result: PackageInfo = await source_class().fetch(package, include_prerelease)
+                result.registry = self.REGISTRY_NAME
+                result.source_used = source_class.NAME
+                result.sources_failed = sources_failed
+                result.sources_remaining = [s.NAME for s in sources[i + 1 :]]
+                return result
+            except Exception as e:
+                sources_failed.append(source_class.NAME)
+                last_error = e
+                if not fallback:
+                    raise
+
+        raise last_error or ValueError(f"Failed to fetch package '{package}'")