Metadata-Version: 2.4
Name: commiter-cli
Version: 0.3.1
Summary: Commiter CLI — scan repositories and enrich architecture snapshots on commiter.dev
License: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: tree-sitter>=0.21.0
Requires-Dist: tree-sitter-python>=0.21.0
Requires-Dist: tree-sitter-javascript>=0.21.0
Requires-Dist: tree-sitter-typescript>=0.21.0
Requires-Dist: click>=8.0
Requires-Dist: rich>=13.0
Requires-Dist: tomli>=2.0; python_version < "3.11"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Dynamic: license-file

# commiter-cli

Scan a repository, detect the structure (pages, components, API endpoints, DB ops, middleware), and either print it to your terminal or upload an enriched, shareable architecture map to [commiter.dev](https://commiter-three.vercel.app).

```
pipx install commiter-cli
```

Or plain pip:

```
pip install commiter-cli
```

## Quick start

```
commiter .                     # print a structured summary of the repo in your current dir
commiter . --format markdown   # write it to stdout as Markdown, ready to paste in docs
commiter . --format ai         # dump as LLM-ready context (paste into Claude/GPT/etc.)
commiter . --endpoints         # list all detected API endpoints
commiter . --calls users       # list frontend API calls whose URL matches "users"
commiter . --db                # list all detected DB operations
```

## Share an interactive architecture canvas

```
commiter --login               # one-time browser auth against commiter.dev
commiter . --enrich            # upload the scan, get a shareable URL back
```

Unauthenticated uploads work too (same command without `--login`), but they expire after 30 days and don't get workspace-level features like per-node commit history or AI chat over the snapshot.

## Library use

If you want to generate a snapshot programmatically instead of from the terminal, use the public `commiter.lib` module:

```python
from commiter.lib import generate_snapshot

snapshot = generate_snapshot(["./path/to/repo"])
# snapshot is a dict with keys: nodes, edges, fileTree, nodeAnalysis,
# nodeHashes, repoFullNames
```

Only `commiter.lib` is a stable API. Everything else (`commiter.cli`, `commiter.scanner`, `commiter.extractors.*`, ...) is considered internal and may change between releases.

## What's supported today

**Languages** (via tree-sitter): Python, JavaScript, TypeScript, TSX/JSX.

**Frontend frameworks**: Next.js (App Router + Pages Router), React + `fetch` / `axios` call detection.

**Backend frameworks**: Flask, FastAPI, Next.js API routes.

**ORMs / Databases**: Prisma, Supabase client, SQLAlchemy.

**Patterns detected**: routes, middleware, decorators/guards, typed request/response shapes (cross-file + generics), frontend-to-backend call correlation across repos.

**Output formats**: `console`, `markdown`, `json`, `ai` (LLM-ready), `architecture` (the JSON shape that `--enrich` uploads).

## Environment variables

| Variable | Default | Purpose |
|----------|---------|---------|
| `COMMITER_TOKEN` | — | Auth token for `--enrich`. Alternative to `--token` flag or `commiter --login`. |
| `COMMITER_API_URL` | `https://commiter-api.up.railway.app` | Base URL for the backend API. Set this to point the CLI at a local/staging server. |
| `COMMITER_FRONTEND_URL` | `https://commiter-three.vercel.app` | Base URL for the web app (used during `--login` browser OAuth). Set this for local dev. |

## Current limitations

Be aware of these before opening a bug report — several are planned but intentionally not done yet.

- **Framework coverage** is focused on the Next.js + Flask/FastAPI stack. Hono, Elysia, Gin, Echo, Spring Boot, SvelteKit, Nuxt, Astro, Remix are not yet detected. Running the tool on a project built with these will produce partial or empty output.
- **ORMs beyond Prisma / Supabase / SQLAlchemy** (Drizzle, Convex, Firebase, Mongoose, TypeORM) are not yet recognized.
- **Server Actions** (`"use server"` directives in Next.js 14+) are not yet detected — they'll be missed from the endpoint graph.
- **`--diff` is not implemented.** Snapshots are always produced from the current state; there's no "what changed since last scan" yet.
- **`--watch` is not implemented.** Each run is one-shot.
- **Go, Rust, Java, Kotlin, Ruby, PHP, C#, Swift** are not yet parsed beyond manifest-file detection. Tree-sitter grammars exist for these — support is planned but not built.
- **Anonymous AI chat**: chat over a snapshot at commiter.dev currently requires an authenticated session. Public/anonymous snapshot pages can be viewed but not chatted with.
- **No plugin system.** You can't currently write custom adapters for in-house frameworks without forking the package.
- **Large monorepos (1000+ files)** have not been performance-tuned. Scans work but may be slow; tree-sitter parsing dominates runtime.

See [ROADMAP.md](ROADMAP.md) for the full plan and expected release ordering.

## Links

- PyPI: https://pypi.org/project/commiter-cli/
- Canvas / snapshot viewer: https://commiter-three.vercel.app
- Issues and contributions: GitHub repo (see PyPI page)

## License

MIT — see [LICENSE](LICENSE) if present, otherwise treat as MIT.
