Metadata-Version: 2.4
Name: secchi
Version: 0.1.2
Summary: Beautiful TUI dashboard to monitor packages across PyPI, crates.io, and npm
Author: Kannan Kalidasan
Maintainer: kannandreams
License: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: mcp>=2.0
Requires-Dist: packaging>=24.0
Requires-Dist: pydantic>=2.0
Requires-Dist: textual-plotext>=1.0
Requires-Dist: textual>=8.0
Requires-Dist: tomli-w>=1.0
Description-Content-Type: text/markdown

<table>
  <tr>
    <td><img src="https://raw.githubusercontent.com/kannandreams/secchi/main/assets/secchi-logo.png" alt="Secchi logo" width="110"></td>
    <td>
      <h1>secchi</h1>
      <p><strong>Open Source Package Intelligence</strong></p>
    </td>
  </tr>
</table>

[![PyPI version](https://img.shields.io/pypi/v/secchi.svg)](https://pypi.org/project/secchi/)
[![PyPI license](https://img.shields.io/pypi/l/secchi.svg)](https://pypi.org/project/secchi/)
[![Latest release](https://img.shields.io/github/v/release/kannandreams/secchi?display_name=tag)](https://github.com/kannandreams/secchi/releases)
[![CI](https://github.com/kannandreams/secchi/actions/workflows/ci.yml/badge.svg)](https://github.com/kannandreams/secchi/actions/workflows/ci.yml)

Secchi lets you explore, compare, monitor, and report on package health,
adoption, dependencies, releases, and ecosystem signals from your terminal.

CI publishes the XML and HTML coverage reports as a GitHub Actions artifact;
open the workflow run and download `coverage-python-3.12` to inspect the full
report. The latest `main` coverage report is also published at
[`kannandreams.github.io/secchi/coverage/`](https://kannandreams.github.io/secchi/coverage/)
after GitHub Pages is enabled for the repository.

![secchi TUI dashboard](https://raw.githubusercontent.com/kannandreams/secchi/main/assets/secchi-v0.1.0-demo-1.gif)

## Supported Ecosystems

<table>
  <tr>
    <td align="center"><img src="https://cdn.simpleicons.org/python" alt="Python" width="28"><br><strong>PyPI</strong><br><small>Python</small></td>
    <td align="center"><img src="https://cdn.simpleicons.org/javascript" alt="JavaScript" width="28"><br><strong>npm</strong><br><small>JavaScript</small></td>
    <td align="center"><img src="https://cdn.simpleicons.org/rust" alt="Rust" width="28"><br><strong>crates.io</strong><br><small>Rust</small></td>
    <td align="center"><img src="https://cdn.simpleicons.org/homebrew" alt="Homebrew" width="28"><br><strong>Homebrew</strong><br><small>Formulae</small></td>
    <td align="center"><img src="https://cdn.simpleicons.org/go" alt="Go" width="28"><br><strong>Go Modules</strong><br><small>Go</small></td>
    <td align="center"><img src="https://cdn.simpleicons.org/r" alt="R" width="28"><br><strong>CRAN</strong><br><small>R</small></td>
  </tr>
</table>

## Capabilities

| Type | Capability | What it helps with | Status |
| --- | --- | --- | :---: |
| Explore | Direct package lookup | Quickly inspect any package from the terminal | ✅ |
| Explore | Interactive dashboard | Explore health, adoption, releases, and dependencies | ✅ |
| Explore | Workspace monitoring | Monitor configured projects and registry sources | ✅ |
| Explore | Cross-registry search | Find packages across supported ecosystems | ✅ |
| Explore | Health and adoption signals | Understand project momentum and maintenance quality | ✅ |
| Explore | Package comparison | Rank package choices with health, adoption, and confidence evidence | ✅ |
| Report | JSON reports | Use package intelligence in scripts and automation | ✅ |
| Report | Markdown reports | Share readable reports in GitHub, Notion, or documentation | ✅ |
| Report | HTML reports | Generate standalone reports for teams and stakeholders | ✅ |
| Report | Project-wide reports | Combine registry sources for one monitored project | ✅ |
| Automate | Package health checks | Fail workflows when package standards are not met | 🚧 |
| Automate | Workspace policy checks | Evaluate every configured project against policies | ⏳ |
| Automate | GitHub Actions integration | Run Secchi automatically in CI | ⏳ |
| Integrate | Python SDK | Use Secchi from Python applications and scripts | ⏳ |
| Integrate | MCP Server | Let AI assistants query package intelligence | ✅ |
| Explore | Ecosystem adapters | Support PyPI, npm, crates.io, Homebrew, Go Modules, and CRAN | ✅ |

## Install

Recommended installation methods:

```bash
uv tool install secchi
```

```bash
pipx install secchi
```

```bash
pip install secchi
```

## Quick Start

Scaffold a config file interactively:

```bash
secchi init
```

Launch the dashboard for a project:

```bash
secchi -p tuffcli
secchi --project opencode
```

Explore a package directly, without a configuration file:

```bash
secchi show duckdb
secchi dashboard duckdb
secchi search duckdb
secchi compare pypi:duckdb pypi:polars
secchi compare pypi:duckdb pypi:polars --format json
secchi report duckdb --format html --output duckdb-report.html
secchi report --config secchi.toml --project duckdb --format html
secchi check duckdb --min-health 80 --require-ci
```

Run the MCP server for local AI-agent integrations:

```bash
secchi mcp
# or
secchi-mcp
```

The server communicates over standard input/output and exposes tools for
package inspection, cross-registry search, configured project reports, and
health policy checks. It reuses the same cached intelligence pipeline as the
CLI, dashboard, and report commands.

## Use Secchi with MCP

Secchi can be added to an MCP-compatible coding agent or desktop client as a
local stdio server. If `secchi` is installed as a tool, use:

```json
{
  "mcpServers": {
    "secchi": {
      "command": "secchi-mcp"
    }
  }
}
```

When running from a source checkout with uv, point the client at the project:

```json
{
  "mcpServers": {
    "secchi": {
      "command": "uv",
      "args": [
        "run",
        "--project",
        "/path/to/secchi",
        "secchi-mcp"
      ]
    }
  }
}
```

The exact configuration file location depends on the MCP client. After the
server is added, the agent can use these tools:

| MCP tool | Use it for |
| --- | --- |
| `inspect_package` | Inspect health, adoption, releases, dependencies, and repository signals |
| `search_packages` | Find matching packages across PyPI, npm, crates.io, Homebrew, Go Modules, and CRAN |
| `inspect_project` | Read a configured project from `secchi.toml` and summarize all its package sources |
| `check_package` | Evaluate minimum health and repository CI policies |
| `compare_packages` | Rank two or more package choices with recommendations, confidence, and evidence |

Package inspection uses Secchi's local cache by default. Ask the agent to
refresh the data when current registry information is required. The MCP server
is read-only: it does not modify packages, repositories, or configuration.
Successful package results may include signal warnings when an optional source
is unavailable; those warnings are preserved instead of turning the package
into a failed result.

Reports are written to the current directory by default. Use `--output` to
choose a file path, or `--output -` to print the report to stdout.

See [DuckDB report examples](examples/reports/README.md) for package and
project exports in JSON, Markdown, and HTML.

JSON reports declare a `schema` and `schema_version` so automation can reject
or migrate incompatible output deliberately. Secchi's local package cache uses
the same versioned-envelope approach and continues to read legacy unversioned
cache entries while writing the current schema for new data.

The serialized boundaries are validated with Pydantic models while the internal
application remains dataclass-based. This keeps the service and TUI lightweight
while giving cache files, reports, and MCP responses explicit contracts. Future
schema changes can be introduced as migrations instead of relying on every
renderer and consumer to handle new fields independently.

`search`, `show`, `dashboard`, and `report` use the same data collection and scoring
pipeline. Add `--registry` with `pypi`, `crates.io`, `npm`, `homebrew`, `go`, or
`cran` when a package name needs an explicit ecosystem.

`compare` is an advisory decision aid for agents and engineers choosing between
dependencies. It reports `Recommended`, `Acceptable`, `Use with caution`, or
`Avoid`, along with the evidence and unknown signals behind the result. Use
explicit `registry:name` references when comparing packages across ecosystems.
Secchi does not install, upgrade, remove, or approve a dependency automatically.

List available projects:

```bash
secchi --list
```

## Config

Secchi looks for config in this order:

1. `--config` / `-c` path
2. `./secchi.toml`
3. `./.secchi.toml`
4. `~/.config/secchi/config.toml`

Example `secchi.toml`:

```toml
[projects.duckdb]
title = "DuckDB"
description = "DuckDB — embeddable analytical database"
favorite = true
repository = "https://github.com/duckdb/duckdb"
packages = [
    { name = "duckdb", registry = "pypi" },
    { name = "duckdb", registry = "npm" },
]
```

`favorite` belongs to the project, which makes workspace navigation clear when
one project contains several registry variants of the same package. Existing
package-level `favorite` entries remain supported for compatibility.

## Optional Spotlight Feed

The dashboard can show a small, curated Spotlight card from Secchi's public
feed. Spotlight is cached locally and can be disabled completely when you do
not want Secchi to request the feed.

```bash
SECCHI_DISABLE_SPOTLIGHT=1 secchi dashboard duckdb
```

When this variable is set to `1`, `true`, `yes`, or `on`, Secchi does not read
or fetch Spotlight data and removes the card from the dashboard.

## CLI Options

```
secchi dashboard [package]              Launch the TUI (workspace when omitted)
secchi show <package>                   Print a concise intelligence summary
secchi search <package>                 Search packages across supported registries
secchi report <package> --format <type> Generate json, html, or md output
secchi compare <package> <package>      Rank package choices; add --format json for agents
secchi check <package>                 Evaluate health and CI policies for automation
secchi --project <name>                 Backwards-compatible project dashboard
secchi --list                           List projects in config
secchi init                             Interactively create secchi.toml
```

## Development

Live reload during development:

```bash
uv run textual run --dev src/secchi/dev.py -- -p tuffcli
```

Press `ctrl+r` to manually reload the dashboard without exiting.

## Project Information

- [Contributing](CONTRIBUTING.md)
- [Changelog](CHANGELOG.md)

## License

Apache 2.0
