surfx 0.2.0__tar.gz

surfx-0.2.0/.github/workflows/publish.yml

@@ -0,0 +1,56 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tooling
+        run: python -m pip install build twine
+
+      - name: Build sdist and wheel
+        run: python -m build
+
+      - name: Check distribution metadata
+        run: python -m twine check dist/*
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    needs: build
+    environment:
+      name: pypi
+      url: https://pypi.org/project/surfx/
+    permissions:
+      # Required for PyPI Trusted Publishing (OIDC) - no API token needed.
+      id-token: write
+    steps:
+      - name: Download build artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

surfx-0.2.0/.github/workflows/tests.yml

@@ -0,0 +1,59 @@
+name: Tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    name: Test (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install package with dev dependencies
+        run: python -m pip install -e ".[dev]"
+
+      - name: Run tests
+        run: pytest
+
+      - name: Lint with Ruff
+        run: ruff check .
+
+      - name: Check formatting with Ruff
+        run: ruff format --check .
+
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    needs: test
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tooling
+        run: python -m pip install build twine
+
+      - name: Build sdist and wheel
+        run: python -m build
+
+      - name: Check distribution metadata
+        run: python -m twine check dist/*

surfx-0.2.0/.gitignore

@@ -0,0 +1,45 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+dist/
+*.egg-info/
+.eggs/
+wheels/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Testing
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+.tox/
+.ruff_cache/
+
+# Type checkers
+.mypy_cache/
+.pyright/
+
+# Distribution / packaging
+*.egg
+MANIFEST
+
+# Editors
+.vscode/
+.idea/
+*.swp
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Surfx runtime data (never commit local config or cache)
+.surfx-cache.json
+config.toml

surfx-0.2.0/.python-version

@@ -0,0 +1 @@
+3.12

surfx-0.2.0/CHANGELOG.md

@@ -0,0 +1,61 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.0] - 2026-09-03
+
+### Changed
+
+- **Breaking:** replaced the Google Programmable Search (Custom Search
+  JSON API) provider with a new `SearXNGProvider`, backed by
+  [SearXNG](https://docs.searxng.org/), an open-source metasearch engine.
+  Surfx no longer requires an API key or cloud account for search - only
+  the URL of a SearXNG instance.
+- `searxng` is now the default (and only built-in) provider.
+- `surfx doctor` now checks that a SearXNG instance URL is configured and
+  performs a live reachability/JSON-validity check against it, in addition
+  to the existing Python/config/network checks.
+- `SearchResult` gained optional `engine` and `category` fields, populated
+  from SearXNG's per-result metadata (which upstream engine produced a
+  result, and its category) when available. These are included in
+  `--json` output and shown as a small "via <engine>" tag in normal
+  output.
+
+### Removed
+
+- `SURFX_GOOGLE_API_KEY` and `SURFX_GOOGLE_CX` environment variables, and
+  all Google-specific setup steps, are gone. Nothing in Surfx requires a
+  Google Cloud account anymore.
+
+### Added
+
+- `SURFX_SEARXNG_URL` environment variable, and a `searxng_url` config
+  file key (via `surfx config set searxng_url <url>`), to point Surfx at
+  a self-hosted or public SearXNG instance.
+
+### Migration notes
+
+- Unset `SURFX_GOOGLE_API_KEY` / `SURFX_GOOGLE_CX` (they're now ignored)
+  and set `SURFX_SEARXNG_URL` to a SearXNG instance you control or trust.
+  See the README's "What is SearXNG" section for how to get one.
+
+## [0.1.0] - 2026-09-02
+
+### Added
+
+- Initial release of `surfx`.
+- `surfx "query"` search command backed by the Google Programmable Search
+  (Custom Search JSON API) provider.
+- Provider abstraction (`SearchProvider` protocol) so new backends can be
+  added without changing the CLI.
+- Interactive mode (`surfx` with no query) with `/help`, `/clear`, `/exit`,
+  `/quit`.
+- `--limit/-n`, `--provider`, `--json`, `--no-color`, `--open`, `--debug`
+  options.
+- `surfx config` and `surfx config set <key> <value>` for non-secret settings.
+- `surfx doctor` environment/configuration check.
+- Optional, conservative local result cache with short TTL.
+- Full offline test suite with mocked HTTP responses.

surfx-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,61 @@
+# Contributing to Surfx
+
+Thanks for your interest in improving Surfx! Contributions of all sizes are
+welcome, from typo fixes to new search providers.
+
+## Getting set up
+
+```bash
+git clone https://github.com/Sam3360/surfx.git
+cd surfx
+python -m venv .venv
+source .venv/bin/activate  # Windows: .venv\Scripts\activate
+pip install -e ".[dev]"
+```
+
+## Running the test suite
+
+The full test suite runs completely offline - no real SearXNG instance or
+network access is required. All HTTP calls are mocked.
+
+```bash
+pytest
+```
+
+## Linting and formatting
+
+```bash
+ruff check .
+ruff format --check .
+```
+
+Please run both before opening a pull request.
+
+## Adding a new search provider
+
+1. Create `src/surfx/providers/<name>.py` implementing the
+   `SearchProvider` protocol from `src/surfx/providers/base.py`:
+   - `validate_config()` should raise a `surfx.errors.SurfxError` subclass
+     when required configuration is missing.
+   - `search(query, limit)` should return a list of provider-independent
+     `surfx.models.SearchResult` objects, and must never leak the raw
+     provider response format to callers.
+2. Register the provider in `src/surfx/providers/__init__.py`'s
+   `PROVIDERS` mapping.
+3. If your provider needs custom construction arguments, extend
+   `build_provider()` in `src/surfx/services/search.py`.
+4. Add tests that mock all HTTP calls (see `tests/test_searxng.py` for the
+   pattern using `httpx.MockTransport`).
+5. Update the README's provider list.
+
+## Pull requests
+
+- Keep changes focused and include tests.
+- Update `CHANGELOG.md` under an "Unreleased" heading.
+- Describe what you changed and why in the PR description.
+
+## Reporting bugs
+
+Please open a GitHub issue with steps to reproduce, what you expected, and
+what actually happened. For security issues, see `SECURITY.md` instead of
+filing a public issue.

surfx-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sam3360
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

surfx-0.2.0/PKG-INFO

@@ -0,0 +1,290 @@
+Metadata-Version: 2.5
+Name: surfx
+Version: 0.2.0
+Summary: A fast, clean, terminal-first web search CLI powered by SearXNG
+Project-URL: Homepage, https://github.com/Sam3360/surfx
+Project-URL: Repository, https://github.com/Sam3360/surfx
+Project-URL: Issues, https://github.com/Sam3360/surfx/issues
+Project-URL: Changelog, https://github.com/Sam3360/surfx/blob/main/CHANGELOG.md
+Author: Samarth Chugh (Sam3360)
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cli,metasearch,productivity,search,searxng,terminal
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP :: Indexing/Search
+Classifier: Topic :: Utilities
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: rich>=13.7.1
+Requires-Dist: tomli-w>=1.0.0
+Requires-Dist: tomli>=2.0.1; python_version < '3.11'
+Requires-Dist: typer>=0.12.3
+Provides-Extra: dev
+Requires-Dist: build>=1.2.1; extra == 'dev'
+Requires-Dist: pytest-mock>=3.14.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.6.0; extra == 'dev'
+Requires-Dist: twine>=5.1.1; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Surfx
+
+A fast, clean, terminal-first web search CLI for developers and power users.
+
+Search the web without leaving your terminal - powered by
+[SearXNG](https://docs.searxng.org/), an open-source, privacy-respecting
+**metasearch engine**. Surfx queries a SearXNG *instance* over its
+documented JSON API; it does not scrape Google (or any other engine)
+directly, and it never requires you to create an API key or a cloud
+account.
+
+```text
+╭──────────────────────────────────────────╮
+│ Surfx                                     │
+│ Search results for "python asyncio"       │
+╰──────────────────────────────────────────╯
+
+[1] Asyncio — Python documentation
+    https://docs.python.org/3/library/asyncio.html
+    Asyncio is a library to write concurrent code using async/await syntax.
+    via duckduckgo
+
+[2] Async IO in Python: A Complete Walkthrough
+    https://realpython.com/async-io-python/
+    ...
+```
+
+## What is Surfx?
+
+Surfx is a small, well-tested CLI that lets you run real web searches from
+the terminal and get clean, readable, Rich-formatted results (or raw JSON
+for scripting). It's built around a provider abstraction, so the underlying
+search backend can change without touching the CLI itself.
+
+## What is SearXNG, and why does Surfx need an instance URL?
+
+[SearXNG](https://docs.searxng.org/) is open-source software that runs a
+"metasearch" service: it queries a number of upstream search engines on
+your behalf (Google, Bing, DuckDuckGo, and many others, depending on how
+the instance is configured) and returns aggregated results, without
+tracking you. Anyone can run a SearXNG instance, so Surfx needs to know
+*which* instance to talk to - that's the one thing you configure.
+
+You have two options:
+
+1. **Self-host an instance** (recommended for regular use, and the most
+   private option) - see the
+   [SearXNG installation docs](https://docs.searxng.org/admin/installation.html).
+   A basic Docker setup takes a few minutes.
+2. **Use a public instance** that has JSON output enabled - browse
+   [searx.space](https://searx.space) for currently active public
+   instances and their capabilities. Public instances are run by
+   volunteers, can disappear or change their settings at any time, and see
+   the queries you send them - don't rely on one for anything sensitive.
+
+Surfx does **not** ship with a hardcoded default instance: public
+instances are unreliable enough (many disable the JSON API entirely) that
+guessing one for you would just produce confusing failures. Point Surfx at
+an instance you trust instead.
+
+## Installation
+
+```bash
+pip install surfx
+```
+
+Requires Python 3.11+.
+
+## Configure a SearXNG instance
+
+Set the instance URL as an environment variable:
+
+```bash
+export SURFX_SEARXNG_URL="https://your-searxng-instance.example"
+```
+
+Windows PowerShell:
+
+```powershell
+$env:SURFX_SEARXNG_URL="https://your-searxng-instance.example"
+```
+
+Or store it in Surfx's config file instead (see [Configuration](#configuration)):
+
+```bash
+surfx config set searxng_url https://your-searxng-instance.example
+```
+
+Then run:
+
+```bash
+surfx "python httpx tutorial"
+```
+
+No API keys, cloud accounts, or billing are involved - the instance URL is
+the only thing Surfx needs. (No secrets ever end up in the example
+commands above, and Surfx never writes secrets to its config file or
+cache in any case - see [Security](SECURITY.md).)
+
+## Usage
+
+```bash
+# Basic search
+surfx "python asyncio tutorial"
+
+# Control how many results come back (1-50)
+surfx "python asyncio tutorial" --limit 20
+surfx "python asyncio tutorial" -n 20
+
+# Choose a provider explicitly (currently: searxng)
+surfx "python asyncio tutorial" --provider searxng
+
+# Machine-readable output (stdout is valid JSON only; errors go to stderr)
+surfx "python asyncio tutorial" --json
+
+# Disable colors/styling, e.g. for logging pipelines
+surfx "python asyncio tutorial" --no-color
+
+# Open a specific result in your default browser
+surfx "python asyncio tutorial" --open 1
+
+# Skip the "open this?" confirmation prompt
+surfx "python asyncio tutorial" --open 1 --yes
+
+# Show full tracebacks for debugging
+surfx "python asyncio tutorial" --debug
+
+# Check your setup, including that your SearXNG instance is reachable
+surfx doctor
+
+# Inspect configuration
+surfx config
+surfx config set searxng_url https://your-searxng-instance.example
+surfx config set limit 10
+
+surfx --version
+surfx --help
+```
+
+### Interactive mode
+
+Running `surfx` with no query drops you into an interactive search prompt:
+
+```text
+Surfx
+
+Search > python decorators
+
+[1] ...
+[2] ...
+
+Search > machine learning tutorials
+
+[1] ...
+
+Search > /exit
+```
+
+Supported interactive commands: `/help`, `/clear`, `/exit`, `/quit`.
+
+## Configuration
+
+Surfx resolves settings using this precedence, highest first:
+
+```text
+CLI arguments
+    ↓
+environment variables
+    ↓
+config file (~/.config/surfx/config.toml)
+    ↓
+built-in defaults
+```
+
+The config file may contain:
+
+```toml
+provider = "searxng"
+limit = 10
+searxng_url = "https://your-searxng-instance.example"
+```
+
+Secret-shaped values (API keys, tokens, etc.) can never be stored in the
+config file - only environment variables are accepted for those. The
+SearXNG URL isn't a secret, so it may live in either place.
+
+| Environment variable      | Purpose                                   |
+| -------------------------- | ------------------------------------------ |
+| `SURFX_SEARXNG_URL`        | SearXNG instance URL (e.g. `https://...`) |
+| `SURFX_PROVIDER`           | Default provider (`searxng`)              |
+| `SURFX_LIMIT`               | Default result limit (1-50)               |
+| `SURFX_NO_COLOR`            | Disable styled output when truthy         |
+| `SURFX_CACHE_ENABLED`       | Enable the local result cache             |
+| `SURFX_CACHE_TTL_SECONDS`   | Cache entry lifetime in seconds           |
+
+## Architecture
+
+Surfx separates concerns into a few small layers:
+
+- **`providers/`** - one module per search backend, each implementing the
+  `SearchProvider` protocol (`validate_config()`, `search(query, limit)`)
+  and returning provider-independent `SearchResult` objects. The CLI and
+  service layer never see a provider's raw response format. The current
+  implementation is `SearXNGProvider`, which talks to a SearXNG instance's
+  `/search?format=json` endpoint.
+- **`services/search.py`** - orchestrates provider selection, limit
+  validation, and the optional cache.
+- **`services/cache.py`** - a small, conservative, optional local cache
+  (disabled by default, short TTL, never stores credentials).
+- **`cli.py`** - the Typer-based command-line interface and interactive
+  mode.
+- **`terminal.py`** - Rich-based rendering, kept separate from business
+  logic so it's easy to test the rest of the app without a real terminal.
+
+Adding a new provider means adding one file under `providers/` and
+registering it in `providers/__init__.py` - no changes to the CLI
+required. See `CONTRIBUTING.md` for the full walkthrough.
+
+## Development
+
+```bash
+git clone https://github.com/Sam3360/surfx.git
+cd surfx
+python -m venv .venv
+source .venv/bin/activate  # Windows: .venv\Scripts\activate
+pip install -e ".[dev]"
+
+pytest
+ruff check .
+ruff format --check .
+```
+
+The test suite runs entirely offline - all HTTP calls to SearXNG are
+mocked, so no real instance or network access is required.
+
+## Publishing
+
+```bash
+python -m build
+python -m twine check dist/*
+python -m twine upload dist/*
+```
+
+Releases to PyPI are automated via GitHub Actions
+(`.github/workflows/publish.yml`) using
+[PyPI Trusted Publishing](https://docs.pypi.org/trusted-publishers/) (OIDC),
+triggered by pushing a `v*` tag - no long-lived PyPI token is stored in this
+repository.
+
+## License
+
+MIT - see [LICENSE](LICENSE).