cartograph-cli 0.1.0__tar.gz

cartograph_cli-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,30 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  publish:
+    name: Build and publish
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install hatch
+        run: pip install hatch
+
+      - name: Build
+        run: hatch build
+
+      - name: Publish
+        uses: pypa/gh-action-pypi-publish@release/v1

cartograph_cli-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,27 @@
+name: Tests
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+    branches: [master]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: pip install -e . && pip install pytest pytest-cov
+
+      - name: Run tests
+        run: pytest --tb=short -q

cartograph_cli-0.1.0/.gitignore

@@ -0,0 +1,56 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+.Python
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Logs and temp output
+*.log
+*.jsonl
+*.txt
+
+# Test artifacts
+.pytest_cache/
+.coverage
+
+# Widgets installed into this repo for local testing - not part of the package.
+# The cartograph/ dir doubles as the Python package and the default install target
+# when running from source. Real subpackages are re-included below.
+cartograph/*/
+!cartograph/languages/
+!cartograph/scaffolding/
+!cartograph/search/
+
+# Widget_Library - local dev library, seeded on first run, not committed
+Widget_Library/
+
+# Failed / temp
+failed_widgets/
+checkouts/
+
+# Secrets
+.env
+.env.*
+
+# Hidden app dirs
+.agent/
+.cartograph/
+.cartographer/
+.claude/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo

cartograph_cli-0.1.0/CLAUDE.md

@@ -0,0 +1,77 @@
+
+## Cartograph
+
+Cartograph is a widget library manager. Widgets are reusable, self-contained
+code modules with tests, examples, and metadata. When installed into a project
+they live under `cartograph/<widget_id>/`.
+
+Before writing reusable, self-contained logic, search the library first.
+
+### Widget structure
+```
+cartograph/<widget_id>/
+  widget.json          metadata, version, dependencies
+  src/                 source code
+  tests/               test files (80%+ coverage required)
+  examples/            example_usage.* (must run), usage_hint.* (optional)
+```
+
+widget_id format: `<domain>-<name>-<language>` e.g. `backend-retry-backoff-python`
+
+Do not edit installed widget files directly - local edits are overwritten on
+update. Wrap or extend in your own code instead.
+
+### Commands
+`<arg>` = required  `[arg]` = optional  defaults shown where relevant
+
+**Find and use widgets**
+
+    cartograph search <query>
+        [--domain backend|data|ml|security|infra|frontend|universal]
+        [--language python|javascript|nim]
+
+    cartograph inspect <widget_id>
+        [--source]         include source files
+        [--reviews]        include review comments
+        [--all-versions]   list full version history
+        [--version X]      inspect a specific version
+
+    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 "..."] [--target .]
+
+**Create and publish widgets**
+
+    cartograph create <widget_id>
+        --language python|javascript|nim    REQUIRED
+        --domain backend|data|ml|security|infra|frontend|universal  REQUIRED
+        [--name "Display Name"] [--target .]
+
+    cartograph validate [path] [--lib]   path defaults to .
+    cartograph checkin [path]            path defaults to .
+        --reason "what changed and why"  REQUIRED
+        [--bump patch|minor|major]       defaults to minor
+        [--publish]                      also publish to cloud
+
+    cartograph rollback <widget_id> [--version X] [--reason "..."]
+    cartograph delete <widget_id> [--confirm]
+
+**Cloud registry**
+
+    cartograph cloud publish [widget_id] [path]
+        [--lib]                          publish from library by ID
+        [--visibility public|private]    defaults to public
+    cartograph cloud unpublish <widget_id> [--confirm]
+    cartograph cloud sync                reconcile local with cloud
+    cartograph cloud rate <widget_id> <score 1-5> [--comment "..."]
+
+**Library and account**
+
+    cartograph stats
+    cartograph doctor
+    cartograph login [--token X]
+    cartograph logout
+    cartograph whoami
+    cartograph dashboard

cartograph_cli-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,63 @@
+# Note from the Author - Ben Teigland
+
+I am very excited to have you along for this ride! This project was born out of personal frustrations with code quality and portability of AI written code. By trade I am not a CS person, which might be reflected in opinionated decisions made about validation engines. I am trained in Electrical Engineering so a systems focus with simple first is my intention. I will be using AI to review submitted PRs, as admittedly I do not know programming well enough for manual review. However, I will not rely on a single pass. This whole project is based on scrutinizing what the AI lets through, and I intend to do that for reviews.
+
+With that said, I do encourage you to use AI to build our engine. People who understand the philosophy of this tool are highest valued, if you can write the code yourself then that's an added bonus! You will not be rejected if Claude or some other chatbot is a co-author. However, if you submit a large PR it is more likely to be rejected. A large PR with 90% correct code but 10% causing issues will be rejected. You are better submitting it as chunks so get that 90% in.
+
+Thank you for you interest in supporting this project!
+
+--- Ben Teigland
+
+# Contributing to Cartograph
+
+The following guide covers the basic mechanics.
+
+## Getting started
+
+```bash
+git clone https://github.com/benteigland11/Cartograph.git
+cd cartograph
+pip install -e .
+pytest
+```
+
+Run `cartograph doctor` to verify all language engine dependencies are installed if you intend to work with them.
+
+## What to work on
+
+- Check open issues for bugs and feature requests
+- New language engines (see `cartograph/languages/` for the pattern) - Please note this will be heavily reviewed. Each langauge took a few days of trial and error with AI coding to start. Validation is the service.
+- Search improvements (`cartograph/search/`)
+
+## Writing code
+
+- Run `pytest` before submitting. Tests live in `tests/`.
+- No extra dependencies unless absolutely necessary. The core uses only `platformdirs` and `rank-bm25` plus any language files.
+- Keep cloud logic in `cloud.py`. Keep auth logic in `auth.py`. The CLI is in `cli.py`.
+- If you add a new command, update the setup command to reflect the new command reference.
+
+## Adding a language
+
+Supporting a language means owning its full validation pipeline, not just generating files. See `cartograph/languages/base.py` for the interface and `cartograph/languages/python.py` for a complete implementation.
+
+A language engine must:
+- Run tests and report pass/fail
+- Measure code coverage (if applicable. General rule, if it is possible to measure it should be measured and sit at 80%)
+- Execute example files (if applicable. Many languages, like js, won't have executable example files, but if it can be ran it should be)
+- Clean up after itself. No temp files!
+
+If a language engine gets picked up in this repo it will be pushed up to the cloud registry quickly.
+
+## Pull requests
+
+- Keep PRs focused. One feature or fix per PR. Adding support for a new language counts as a single feature if fully put together. We will not accept half written language engines.
+- Include a clear description of what changed and why.
+- If you're adding a new command, include `--help` output in the PR description.
+
+## Cloud registry
+
+The default registry is hosted at the URL configured in `cartograph/auth.py`. You can point to your own registry by setting `CARTOGRAPH_REGISTRY_URL`. The registry API is documented by the endpoints in `cartograph/cloud.py`. We recommend using the default cloud registry to create a network effect and use a custom one for enterprise systems.
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the MIT License.

cartograph_cli-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Cartograph Contributors
+
+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.

cartograph_cli-0.1.0/PKG-INFO

@@ -0,0 +1,125 @@
+Metadata-Version: 2.4
+Name: cartograph-cli
+Version: 0.1.0
+Summary: Widget library manager for AI agents — CLI
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: platformdirs>=4.0.0
+Requires-Dist: rank-bm25>=0.2.2
+Description-Content-Type: text/markdown
+
+# Cartograph
+
+A shared widget library for AI agents. Search, install, create, validate, and check in reusable code across projects.
+
+## 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.
+
+## Philosophy
+
+Something that might take getting used to is this CLI tool is made with agents in mind first. This means things like few interactive CLI commands.
+
+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'll add languages as those pipelines are ready, not before.
+
+Cloud version gets trickier. We ship this engine with the ability to self sign, and you can design the cloud service to accept a self signed or do its own validation. Default is not done in the cloud because that is an expensive operation.
+
+## Quick Start
+
+```bash
+pip install cartograph-cli
+```
+
+Then generate instructions for your AI agent:
+
+```bash
+cartograph setup --agent claude --write
+```
+
+We built in the ability to separate out by agentic service in case some need different guidance.
+
+## Commands
+
+```
+cartograph search <query>
+    [--domain backend|data|ml|security|infra|frontend|universal]
+    [--language python|javascript|nim]
+
+cartograph inspect <widget_id>
+    [--source]           include source files
+    [--reviews]          include review comments
+    [--all-versions]     list full version history
+    [--version X]        inspect a specific historical version
+
+cartograph install <widget_id>   [--target .] [--version X]
+cartograph uninstall <widget_id> [--target .]
+cartograph upgrade <widget_id>   [--target .] [--version X]
+cartograph status [widget_id]    [--target .]   omit widget_id to scan all installed
+cartograph delete <widget_id>    [--confirm]    dry-run without --confirm
+cartograph rollback <widget_id>  [--version X] [--reason "..."]
+
+cartograph create <widget_id>
+    --language python|javascript|nim       REQUIRED
+    --domain backend|data|ml|security|infra|frontend|universal  REQUIRED
+
+cartograph validate [path] [--lib]
+cartograph checkin [path]
+    --reason "what changed and why"       REQUIRED
+    [--bump patch|minor|major]
+    [--publish]                           also publish to cloud
+
+cartograph rate <widget_id> <score 1-5>  [--comment "..."]
+cartograph setup  [--agent claude|codex|gemini|antigravity|cursor]
+                  [--write]
+cartograph stats
+cartograph doctor
+cartograph dashboard
+
+cartograph login   [--token TOKEN]
+cartograph logout
+cartograph whoami
+cartograph cloud publish [widget_id] [path]  [--visibility public|private]
+cartograph cloud unpublish <widget_id> [--confirm]
+cartograph cloud sync
+cartograph cloud rate <widget_id> <score 1-5> [--comment "..."]
+```
+
+## 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) are installed correctly.
+
+## Status
+
+- Python: fully supported (create, validate, test, checkin)
+- JavaScript: fully supported (React components, plain JS, vitest)
+- Nim: fully supported (testament)
+- Search: hybrid BM25 + n-gram (local and cloud)
+- Dashboard: `cartograph dashboard` opens a local web UI for browsing and managing widgets
+
+## Cloud registry
+
+The default registry is hosted by the Cartograph project. To point at your own registry instance, set `CARTOGRAPH_REGISTRY_URL`:
+
+```bash
+export CARTOGRAPH_REGISTRY_URL=https://your-registry.example.com
+```
+
+Authenticate with `cartograph login`, which opens a browser-based OAuth flow. Once authenticated, you can publish widgets. You can still install cloud widgets when not logged in. We encourage you to use the default cloud registry to build up a network effect. Switching the Registry URL would be good use cases for enterprise systems that want this as an internal tool.
+
+## Roadmap
+
+- Continued support for more languages.

cartograph_cli-0.1.0/README.md

@@ -0,0 +1,114 @@
+# Cartograph
+
+A shared widget library for AI agents. Search, install, create, validate, and check in reusable code across projects.
+
+## 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.
+
+## Philosophy
+
+Something that might take getting used to is this CLI tool is made with agents in mind first. This means things like few interactive CLI commands.
+
+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'll add languages as those pipelines are ready, not before.
+
+Cloud version gets trickier. We ship this engine with the ability to self sign, and you can design the cloud service to accept a self signed or do its own validation. Default is not done in the cloud because that is an expensive operation.
+
+## Quick Start
+
+```bash
+pip install cartograph-cli
+```
+
+Then generate instructions for your AI agent:
+
+```bash
+cartograph setup --agent claude --write
+```
+
+We built in the ability to separate out by agentic service in case some need different guidance.
+
+## Commands
+
+```
+cartograph search <query>
+    [--domain backend|data|ml|security|infra|frontend|universal]
+    [--language python|javascript|nim]
+
+cartograph inspect <widget_id>
+    [--source]           include source files
+    [--reviews]          include review comments
+    [--all-versions]     list full version history
+    [--version X]        inspect a specific historical version
+
+cartograph install <widget_id>   [--target .] [--version X]
+cartograph uninstall <widget_id> [--target .]
+cartograph upgrade <widget_id>   [--target .] [--version X]
+cartograph status [widget_id]    [--target .]   omit widget_id to scan all installed
+cartograph delete <widget_id>    [--confirm]    dry-run without --confirm
+cartograph rollback <widget_id>  [--version X] [--reason "..."]
+
+cartograph create <widget_id>
+    --language python|javascript|nim       REQUIRED
+    --domain backend|data|ml|security|infra|frontend|universal  REQUIRED
+
+cartograph validate [path] [--lib]
+cartograph checkin [path]
+    --reason "what changed and why"       REQUIRED
+    [--bump patch|minor|major]
+    [--publish]                           also publish to cloud
+
+cartograph rate <widget_id> <score 1-5>  [--comment "..."]
+cartograph setup  [--agent claude|codex|gemini|antigravity|cursor]
+                  [--write]
+cartograph stats
+cartograph doctor
+cartograph dashboard
+
+cartograph login   [--token TOKEN]
+cartograph logout
+cartograph whoami
+cartograph cloud publish [widget_id] [path]  [--visibility public|private]
+cartograph cloud unpublish <widget_id> [--confirm]
+cartograph cloud sync
+cartograph cloud rate <widget_id> <score 1-5> [--comment "..."]
+```
+
+## 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) are installed correctly.
+
+## Status
+
+- Python: fully supported (create, validate, test, checkin)
+- JavaScript: fully supported (React components, plain JS, vitest)
+- Nim: fully supported (testament)
+- Search: hybrid BM25 + n-gram (local and cloud)
+- Dashboard: `cartograph dashboard` opens a local web UI for browsing and managing widgets
+
+## Cloud registry
+
+The default registry is hosted by the Cartograph project. To point at your own registry instance, set `CARTOGRAPH_REGISTRY_URL`:
+
+```bash
+export CARTOGRAPH_REGISTRY_URL=https://your-registry.example.com
+```
+
+Authenticate with `cartograph login`, which opens a browser-based OAuth flow. Once authenticated, you can publish widgets. You can still install cloud widgets when not logged in. We encourage you to use the default cloud registry to build up a network effect. Switching the Registry URL would be good use cases for enterprise systems that want this as an internal tool.
+
+## Roadmap
+
+- Continued support for more languages.

cartograph_cli-0.1.0/cartograph/__init__.py

@@ -0,0 +1,11 @@
+"""Cartograph - widget library manager for AI agents."""
+
+from importlib.metadata import version as _pkg_version
+
+from .engine import Cartograph, LIBRARY_PATH
+
+try:
+    __version__ = _pkg_version("cartograph-cli")
+except Exception:
+    __version__ = "0.0.0"
+__all__ = ["Cartograph", "LIBRARY_PATH", "__version__"]

cartograph_cli-0.1.0/cartograph/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running as: python -m cartograph"""
+
+from .cli import main
+
+main()