Metadata-Version: 2.4
Name: cartograph-cli
Version: 0.5.11
Summary: Widget library manager for AI agents — CLI
License-Expression: MIT
License-File: LICENSE
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# Cartograph

[![Tests](https://github.com/benteigland11/Cartograph/actions/workflows/test.yml/badge.svg)](https://github.com/benteigland11/Cartograph/actions/workflows/test.yml)
[![PyPI](https://img.shields.io/pypi/v/cartograph-cli?cacheSeconds=60)](https://pypi.org/project/cartograph-cli/)

A reusable code registry for AI agents. Search, install, create, validate, and check in reusable code modules across projects. Only requires Python. Other languages in the repo are native validation scanners for their respective widget types.

## Why Cartograph

AI agents write a lot of code, but it disappears. Each new project starts from scratch, and agents can't naturally reuse logic across codebases without somewhere to put it.

Cartograph came out of a personal frustration. Features that took 10 to 20 hours to polish with AI coding tools would need to be rebuilt almost from scratch when the next project needed them and most of the hardened logic would be gone. Then I built a basic engine, and those same features could be dropped into a new project in minutes.

Those same widgets have now been reused across many projects and have settled into a quiet loop of continuous improvement. Each time a new edge case surfaces, the fix goes back into the library, and every project that installs it going forward starts with that bug already squashed.

## What is a widget?

A widget is a reusable code module with tests, examples, metadata, and declared dependencies. Each widget is self-contained and language-specific.

```
cg/backend_retry_backoff_python/
  widget.json          # metadata, version, dependencies
  src/                 # source code
  tests/               # test files (80%+ coverage required)
  examples/
    example_usage.py   # must run successfully
```

Widget IDs follow `<domain>-<name>-<language>`, for example `backend-retry-backoff-python` or `algorithms-edit-distance-nim`.

When installed into a project, widgets live under `cg/` in your working directory.

## Quick start

```bash
pip install cartograph-cli
```

Set up instructions for your AI agent:

```bash
cartograph setup
```

This auto-detects your agent (Claude, Cursor, Codex, Gemini) and appends Cartograph instructions to the appropriate config file. Use `--print` to preview without writing.

## Example workflow

```bash
# Create a new widget
cartograph create backend-retry-backoff-python --language python --domain backend

# Write your code in cg/backend_retry_backoff_python/src/ and tests/

# Validate it (runs tests, coverage, contamination scanning)
cartograph validate cg/backend_retry_backoff_python

# Check it into your library
cartograph checkin cg/backend_retry_backoff_python --reason "initial implementation"

# Later, in a different project:
cartograph search "retry backoff"
cartograph install backend-retry-backoff-python
```

## Philosophy

This CLI tool is built with agents in mind first. Commands are non-interactive and output JSON so both humans and AI agents can consume them.

We only ship what we can validate. Every widget that enters the library has passed a full pipeline: structure checks, manifest validation, coverage enforcement, contamination scanning, example execution, and versioning. If the pipeline can't run it, it doesn't go in.

Supporting a language means owning its full validation pipeline, not just generating files. We add languages as those pipelines are ready, not before.

## Commands

`<arg>` = required, `[arg]` = optional. All commands run from your project root.

**Find and use widgets**

```
cartograph search <query> [--domain ...] [--language ...]
cartograph inspect <widget_id> [--source] [--reviews] [--version X]
cartograph install <widget_id> [--target .] [--version X]
cartograph uninstall <widget_id> [--target .]
cartograph upgrade <widget_id> [--target .] [--version X]
cartograph status [widget_id] [--target .]
cartograph rate <widget_id> <score 1-5> [--comment "..."]
```

**Create and publish widgets**

```
cartograph create <widget_id> --language <lang> --domain <domain>
cartograph validate [path] [--lib]
cartograph checkin [path] --reason "..." [--bump patch|minor|major] [--publish]
cartograph rollback <widget_id> [--version X] [--reason "..."]
cartograph delete <widget_id> [--confirm]
```

**Cloud registry**

```
cartograph cloud publish [widget_id] [path] [--visibility public|private]
                                            [--governance open|protected]
cartograph cloud unpublish <widget_id> [--confirm]
cartograph cloud sync [--dry-run]
cartograph cloud proposals [widget_id] [--accept] [--reject] [--reason "..."]
```

**Custom validation rules**

```
cartograph rules                                  # list active rules
cartograph rules init --language <lang> [--global] # create from template
cartograph rules reset --language <lang> [--global] # restore default template
```

Rules files run automatically during `cartograph validate`. Per-project rules go in `.cartograph/rules/`, global rules apply to all projects. See the generated template for the full contract.

**Library and configuration**

```
cartograph setup [--agent ...] [--file ...] [--print] [--workflow]
cartograph config [key] [value]
cartograph export [--output file.zip]
cartograph import <file.zip> [--force]
cartograph stats
cartograph doctor
cartograph dashboard
cartograph login [--token X]
cartograph logout
cartograph whoami
```

## Language support

- **Python**: pytest, coverage.py, AST-based contamination scanner
- **JavaScript/TypeScript**: vitest, native JS scanner, React component support
- **Nim**: nimble, std/unittest, native Nim scanner, stdlib-aware import checking

Each language has its own validation engine with native tooling. The contamination scanners are written in the target language itself, not regex.

## Cloud registry

The CLI is built around a local registry on your machine. It also supports an optional cloud registry for sharing widgets across teams or publicly.

The hosted registry is in early development. The local engine is production-ready and does not depend on cloud availability. If the registry is down or unreachable, everything local continues to work.

To point at your own registry instance:

```bash
export CARTOGRAPH_REGISTRY_URL=https://your-registry.example.com
```

`cartograph login` opens a browser-based authentication flow provided by whichever registry you're connected to.

## Development

```bash
pip install -e .
pytest
```

The widget library lives in your platform's user data directory. To override the location, set `WIDGET_LIBRARY_PATH`. When running from source, a `Widget_Library/` directory alongside this repo takes precedence so local edits work without configuration.

Run `cartograph doctor` to check that all language engine dependencies (pytest, coverage, node, npx, vitest, nim, nimble) are installed correctly.
