# Stargraph

Evidence-first analytics over your GitHub stars: every capability claim is backed
by a source URL, an evidence-record hash, and a confidence score, so an agent can
verify a signal instead of trusting it. There is no LLM in the scoring path: a
weighted composite you can read in one file (`src/scoring.ts`) computes the
rankings, and the same functions back both a CLI and an MCP stdio server.

Stargraph syncs starred repositories into a local SQLite ledger, extracts
evidence-backed capabilities from metadata, docs, and manifests, computes
similarity lenses, and answers questions about the resulting graph.

V1 intentionally avoids cloning repositories by default. GitHub is the source of
truth, SQLite is canonical local state, and graph/cluster/search outputs are
rebuildable projections.

## Quick Start

Requirements: Node >= 22.5 (uses the built-in `node:sqlite` module), zero runtime
dependencies.

```bash
npm install
npm run build
# --limit caps how many stars are fetched; --deep-limit caps how many get the
# full metadata/docs/manifest pass (default 25). Set both to deep-analyze all 50.
GITHUB_TOKEN="$GITHUB_TOKEN" node dist/src/cli.js sync --limit 50 --deep-limit 50 --json
node dist/src/cli.js search "local-first agent memory tools" --json
node dist/src/cli.js similar owner/repo --json
node dist/src/cli.js explain owner/repo --json
node dist/src/cli.js serve
```

By default data is stored under `~/.stargraph`. Use `--data-dir ./data` or
`--db ./data/stargraph.sqlite` for a project-local ledger.

## Commands

- `sync`: fetch starred repos and, for the first `--deep-limit` of them
  (default 25), their metadata, docs/manifests, releases, issues, PRs, topics,
  and languages, plus optional local star-list imports. `--limit` caps how many
  starred repos are fetched; raise `--deep-limit` to deep-analyze more of them.
- `search "<use case>"`: rank repos by useful + robust fit.
- `similar owner/repo`: compare repos across functional, architecture,
  dependency, maintenance, portability, risk, and docs-language lenses.
- `explain owner/repo`: show capabilities, dependencies, health, risk, and
  evidence.
- `clusters`: group repos into high-signal functional/tooling clusters.
- `query "<question>"`: a keyword query router that dispatches to search,
  similar, explain, or clusters based on keywords and an `owner/repo` pattern in
  the question (it does not parse natural language).
- `build-graph`: write a Kuzu-compatible CSV/Cypher projection.
- `serve`: expose MCP tools over stdio.

## Star Lists

GitHub's documented REST starring API exposes starred repositories and
`starred_at`. V1 stores lists as first-class data, but imports them from a local
JSON file until GitHub exposes a stable public lists endpoint.

```json
{
  "lists": [
    {
      "name": "agent memory",
      "description": "Repos related to local-first memory",
      "repos": ["owner/name", "other/repo"]
    }
  ]
}
```

Import during sync with:

```bash
node dist/src/cli.js sync --lists-file ./lists.json --json
```

## Authentication

The GitHub token is read only from the `GITHUB_TOKEN` or `GH_TOKEN` environment
variable, or from an explicit `--token` flag. Nothing is written back to disk.

## Design

- GitHub is the source of truth. Stargraph never mutates upstream state; it only
  reads.
- SQLite is canonical local state. The ledger is the single place durable data
  lives.
- Graph, cluster, and search outputs are rebuildable projections derived from the
  ledger, so they can be regenerated at any time.
- Raw API snapshots are retained for auditability, which lets a capability claim
  be traced back to the exact response it came from.
- Scoring is code, not an LLM. Similarity and ranking are a weighted composite
  computed by the functions in `src/scoring.ts`, and the CLI and MCP server call
  the same code. Given a fixed ledger snapshot and a fixed clock the output is
  deterministic; the personal-relevance score includes a recency term derived
  from `starred_at` versus the current time, so that component moves as time
  passes, and result envelopes are stamped with a `last_analyzed_at` timestamp.

## Limitations

- macOS and Linux are the tested platforms; Windows is untested.
- Requires Node >= 22.5 because it depends on the built-in `node:sqlite` module,
  which is not available on older Node versions.
- GitHub does not expose a stable public endpoint for star lists, so lists are
  imported from a local JSON file rather than synced automatically.
- V1 does not clone repositories, so analysis is limited to metadata, docs,
  manifests, and other data reachable through the GitHub REST API.

## License

MIT. See [LICENSE](LICENSE).