selvedge 0.1.0__tar.gz

selvedge-0.1.0/.gitignore

@@ -0,0 +1,33 @@
+# Selvedge database (commit this if you want shared team history, ignore for local-only)
+# .selvedge/
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.venv/
+venv/
+env/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Editor
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Env
+.env
+.env.local

selvedge-0.1.0/CLAUDE.md

@@ -0,0 +1,272 @@
+# Selvedge — CLAUDE.md
+
+> Change tracking for AI-era codebases.
+> The pandas of codebase history — essential infrastructure, not a feature.
+
+---
+
+## What this is
+
+Selvedge is an open-source MCP server that AI coding agents call as they work to log structured change events. It answers questions like:
+
+- "When was `users.stripe_customer_id` added and why?"
+- "What changed in the auth module in the last 30 days?"
+- "Which agent added the payments table and what was the reasoning?"
+
+The core insight: with human-written code, intent leaked into commit messages and PR descriptions. With AI-written code, intent lives in a prompt that evaporates when the session ends. Selvedge captures it before it's gone.
+
+**Positioning:** "What pandas is to data manipulation, Selvedge is to codebase change tracking." Open source core, hosted platform as the business model.
+
+---
+
+## Architecture
+
+```
+selvedge/
+├── selvedge/
+│   ├── __init__.py       version string
+│   ├── models.py         ChangeEvent dataclass, ChangeType + EntityType enums
+│   ├── config.py         DB path resolution (env → walk-up → ~/.selvedge)
+│   ├── storage.py        SelvedgeStorage — SQLite CRUD layer
+│   ├── server.py         FastMCP server — 5 tools exposed to AI agents
+│   └── cli.py            Click + Rich CLI — init, status, diff, blame, history, search, log
+├── tests/
+│   ├── test_storage.py
+│   ├── test_server.py
+│   └── test_cli.py
+├── docs/
+│   └── getting-started.md
+├── pyproject.toml
+├── README.md
+└── CLAUDE.md
+```
+
+### Tech stack
+- **Python 3.10+** — matches pandas positioning (Python-first)
+- **mcp** — official Anthropic MCP Python SDK (FastMCP)
+- **SQLite** — zero-config local storage; WAL mode for concurrency
+- **Click** — CLI framework
+- **Rich** — terminal output formatting
+- **Hatchling** — build backend
+- **pytest** — test runner
+
+---
+
+## Data model
+
+### ChangeEvent
+
+The central entity. Every recorded change is one row in the `events` table.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | TEXT PK | UUID4 |
+| `timestamp` | TEXT | UTC ISO 8601 |
+| `entity_type` | TEXT | column, table, file, function, class, endpoint, dependency, env_var, index, schema, config, other |
+| `entity_path` | TEXT | Dot/slash notation path (see conventions below) |
+| `change_type` | TEXT | add, remove, modify, rename, retype, create, delete, index_add, index_remove, migrate |
+| `diff` | TEXT | The actual change — SQL migration, code diff, or description |
+| `reasoning` | TEXT | Why the change was made — the captured intent |
+| `agent` | TEXT | Which AI agent (claude-code, cursor, copilot, human, etc.) |
+| `session_id` | TEXT | Agent session/conversation ID |
+| `git_commit` | TEXT | Git commit hash this change lands in |
+| `project` | TEXT | Repository/project name |
+| `metadata` | TEXT | JSON blob for extensibility |
+
+### entity_path conventions
+
+```
+users.email           → DB column (table.column)
+users                 → DB table
+src/auth.py::login    → function in file (path::symbol)
+src/auth.py           → file
+api/v1/users          → API route
+deps/stripe           → dependency
+env/STRIPE_SECRET_KEY → environment variable
+```
+
+Prefix queries work everywhere: `users` matches `users`, `users.email`, `users.created_at`.
+
+---
+
+## MCP Server tools
+
+The MCP server (`selvedge/server.py`) exposes these tools to AI agents:
+
+### `log_change`
+Record a change. Call this immediately after making any meaningful change.
+
+**Required:** `entity_path`, `change_type`
+**Optional:** `diff`, `entity_type`, `reasoning`, `agent`, `session_id`, `git_commit`, `project`
+
+### `diff`
+Get change history for an entity or entity prefix. Returns list of events, newest first.
+
+### `blame`
+Get the most recent change to an exact entity path — what, when, who, why.
+
+### `history`
+Filtered history across all entities. Supports `since` (ISO or relative like `7d`, `30d`, `1y`), `entity_path`, `project`, `limit`.
+
+### `search`
+Full-text substring search across `entity_path`, `diff`, `reasoning`, `agent`.
+
+---
+
+## CLI commands
+
+```bash
+selvedge init                              # init .selvedge/ in current dir
+selvedge status                            # summary + recent events
+selvedge diff users.email                  # history for an entity
+selvedge diff users --limit 50             # all users.* columns, 50 entries
+selvedge blame payments.amount             # most recent change + context
+selvedge history                           # all history
+selvedge history --since 7d                # last 7 days
+selvedge history --entity users --since 30d
+selvedge history --project my-api
+selvedge search "billing"                  # full-text search
+selvedge log users.phone add --reasoning "2FA" --agent me  # manual entry
+```
+
+All commands support `--json` for machine-readable output.
+
+---
+
+## DB path resolution
+
+Order of precedence:
+1. `SELVEDGE_DB` environment variable
+2. Walk up from CWD looking for an existing `.selvedge/` directory
+3. `~/.selvedge/selvedge.db` (global fallback)
+
+This means `selvedge init` in a project root locks that project to its own DB.
+The global fallback ensures agents always have somewhere to write even before `init` is run.
+
+---
+
+## Running the MCP server
+
+```bash
+# After pip install
+selvedge-server
+
+# Or directly
+python -m selvedge.server
+```
+
+### Claude Code config (~/.claude/config.json)
+```json
+{
+  "mcpServers": {
+    "selvedge": {
+      "command": "selvedge-server"
+    }
+  }
+}
+```
+
+### With a project-specific DB
+```json
+{
+  "mcpServers": {
+    "selvedge": {
+      "command": "selvedge-server",
+      "env": {
+        "SELVEDGE_DB": "/path/to/your/project/.selvedge/selvedge.db"
+      }
+    }
+  }
+}
+```
+
+---
+
+## System prompt / agent instructions
+
+Add this to your agent's system prompt or CLAUDE.md to activate logging:
+
+```
+You have access to Selvedge (MCP server: selvedge) for change tracking.
+
+Rules:
+- Call selvedge.log_change immediately after adding, modifying, or removing
+  any DB column, table, function, API endpoint, dependency, or env variable.
+- Set `reasoning` to the user's original request or the problem being solved.
+- Set `agent` to "claude-code" (or whichever agent you are).
+- Set `session_id` if you have access to the current session/conversation ID.
+- Set `git_commit` to the commit hash once you know it.
+- Before modifying an entity, call selvedge.diff or selvedge.blame to understand
+  its history and avoid conflicting with past decisions.
+```
+
+---
+
+## Phase plan
+
+### Phase 1 — Core (DONE ✓)
+- [x] MCP server with 5 tools
+- [x] SQLite storage with WAL mode
+- [x] CLI (init, status, diff, blame, history, search, log)
+- [x] PyPI package with entry points
+- [x] Test suite (storage, server, CLI)
+
+### Phase 2 — Integrations
+- [ ] Git hook: auto-link selvedge events to commit hashes at commit time
+  - Post-commit hook reads `git rev-parse HEAD`, backfills `git_commit` on events with empty commit field and matching timestamp window
+- [ ] Migration file parser: ingest Alembic / Liquibase / raw SQL migrations to backfill schema history
+  - Parse migration files, extract column/table ops, write ChangeEvents with `change_type` inferred from SQL
+- [ ] `selvedge import` CLI command for the above parsers
+- [ ] `selvedge export` — dump history as JSON/CSV
+
+### Phase 3 — Team features
+- [ ] PostgreSQL backend option (configurable via `SELVEDGE_BACKEND=postgresql://...`)
+  - Abstract `SelvedgeStorage` behind a protocol/interface so backends are swappable
+  - `storage_sqlite.py` and `storage_pg.py` both implement `StorageBackend`
+- [ ] HTTP REST API layer (FastAPI) — exposes the same 5 operations over HTTP
+- [ ] Auth (API keys) for the HTTP layer
+
+### Phase 4 — Platform (hosted business)
+- [ ] Web dashboard (React + the REST API)
+- [ ] Cross-repo queries
+- [ ] Retention policies
+- [ ] Team/org management
+- [ ] Webhook events (Slack, PagerDuty, etc. on schema changes)
+
+---
+
+## Development setup
+
+```bash
+git clone https://github.com/masondelan/selvedge
+cd selvedge
+pip install -e ".[dev]"
+pytest
+selvedge --version
+```
+
+---
+
+## Code conventions
+
+- **No external dependencies beyond the declared ones.** Keep the install footprint small.
+- **SQLite first, always.** Don't reach for Postgres until Phase 3. SQLite with WAL handles concurrent reads fine.
+- **ChangeEvent is a dataclass, not Pydantic.** Keep the core dependency-free. MCP serialization uses `to_dict()`.
+- **Every public function has a docstring.** The MCP tool docstrings are user-facing — they appear in agent tool listings.
+- **Tests use `tmp_path` fixtures and `SELVEDGE_DB` env var.** Never write to the real DB in tests.
+- **Rich for all terminal output.** No bare `print()` in cli.py.
+- **`--json` flag on every read command.** Machine-readable output is a first-class concern.
+- **Type hints everywhere.** Python 3.10+ syntax (`X | Y`, `list[dict]`, etc.).
+
+---
+
+## Non-goals (Phase 1)
+
+- No web UI
+- No PostgreSQL
+- No authentication
+- No real-time streaming
+- No git integration (Phase 2)
+- No migration file parsing (Phase 2)
+- No multi-user/team features (Phase 3)
+- No LLM calls inside Selvedge itself — reasoning is captured FROM agents, not generated by Selvedge

selvedge-0.1.0/PKG-INFO

@@ -0,0 +1,201 @@
+Metadata-Version: 2.4
+Name: selvedge
+Version: 0.1.0
+Summary: Change tracking for AI-era codebases
+Project-URL: Homepage, https://github.com/masondelan/selvedge
+Project-URL: Repository, https://github.com/masondelan/selvedge
+Project-URL: Issues, https://github.com/masondelan/selvedge/issues
+License: MIT
+Keywords: ai,changelog,codebase,devtools,mcp,tracking
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Version Control
+Requires-Python: >=3.10
+Requires-Dist: click>=8.0.0
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: rich>=13.0.0
+Provides-Extra: dev
+Requires-Dist: hatchling; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Selvedge
+
+**Change tracking for AI-era codebases.**
+
+AI agents write your code now. But when they're done, the *why* disappears — the conversation that prompted the change, the reasoning behind the schema decision, the context that made the diff make sense. Selvedge captures all of it.
+
+```bash
+$ selvedge blame payments.amount
+
+  payments.amount
+  Changed     2025-11-03 14:22:01
+  Type        add
+  Agent       claude-code
+  Commit      a3f9c12
+  Diff        + amount DECIMAL(10,2) NOT NULL DEFAULT 0
+  Reasoning   User requested Stripe billing integration. Added amount column
+              to store transaction totals in cents per Stripe convention.
+```
+
+---
+
+## Install
+
+```bash
+pip install selvedge
+```
+
+## Quickstart
+
+**1. Initialize in your project**
+
+```bash
+cd your-project
+selvedge init
+```
+
+This creates `.selvedge/selvedge.db` in your project root. Commit it to share history with your team, or add `.selvedge/` to `.gitignore` to keep it local.
+
+**2. Add to your Claude Code config**
+
+`~/.claude/config.json`:
+```json
+{
+  "mcpServers": {
+    "selvedge": {
+      "command": "selvedge-server"
+    }
+  }
+}
+```
+
+**3. Tell your agent to use it**
+
+Add to your project's `CLAUDE.md`:
+```
+You have access to Selvedge for change tracking.
+Call selvedge.log_change immediately after adding, modifying, or removing
+any DB column, table, function, API endpoint, dependency, or env variable.
+Set `reasoning` to the user's original request or the problem being solved.
+Set `agent` to "claude-code".
+Before modifying an entity, call selvedge.blame to understand its history.
+```
+
+**4. Start querying**
+
+```bash
+selvedge status                        # recent activity
+selvedge diff users                    # all changes to the users table
+selvedge diff users.email              # changes to a specific column
+selvedge blame payments.amount         # what changed last and why
+selvedge history --since 30d           # last 30 days of changes
+selvedge search "stripe"               # full-text search
+```
+
+---
+
+## How it works
+
+Selvedge runs as an MCP server. AI agents in tools like Claude Code call Selvedge's tools as they work — logging structured change events to a local SQLite database.
+
+Each event records:
+- **What** changed (entity path, change type, diff)
+- **When** (timestamp)
+- **Who** (agent, session ID)
+- **Why** (reasoning — captured from the agent's context in the moment)
+- **Where** (git commit, project)
+
+The diff is git's job. The *why* is Selvedge's.
+
+---
+
+## Entity path conventions
+
+```
+users.email           DB column (table.column)
+users                 DB table
+src/auth.py::login    Function in a file (path::symbol)
+src/auth.py           File
+api/v1/users          API route
+deps/stripe           Dependency
+env/STRIPE_SECRET_KEY Environment variable
+```
+
+---
+
+## MCP tools
+
+When connected as an MCP server, Selvedge exposes:
+
+| Tool | Description |
+|------|-------------|
+| `log_change` | Record a change event |
+| `diff` | History for an entity or entity prefix |
+| `blame` | Most recent change + context for an entity |
+| `history` | Filtered history across all entities |
+| `search` | Full-text search across all events |
+
+---
+
+## CLI reference
+
+```
+selvedge init [--path PATH]               Initialize in project
+selvedge status                           Recent activity summary
+selvedge diff ENTITY [--limit N]          Change history for entity
+selvedge blame ENTITY                     Most recent change + context
+selvedge history [--since SINCE]          Browse all history
+              [--entity ENTITY]
+              [--project PROJECT]
+              [--limit N]
+selvedge search QUERY [--limit N]         Full-text search
+selvedge log ENTITY CHANGE_TYPE           Manually log a change
+             [--diff TEXT]
+             [--reasoning TEXT]
+             [--agent NAME]
+             [--commit HASH]
+             [--project NAME]
+```
+
+All read commands support `--json` for machine-readable output.
+
+**Relative time in `--since`:**
+- `7d` → last 7 days
+- `24h` → last 24 hours
+- `3m` → last 3 months
+- `1y` → last year
+
+---
+
+## Configuration
+
+| Method | Format | Example |
+|--------|--------|---------|
+| Env var | `SELVEDGE_DB=/path/to/db` | Per-session override |
+| Project init | `selvedge init` | Creates `.selvedge/selvedge.db` in CWD |
+| Global fallback | `~/.selvedge/selvedge.db` | Used if no project DB found |
+
+---
+
+## Contributing
+
+```bash
+git clone https://github.com/masondelan/selvedge
+cd selvedge
+pip install -e ".[dev]"
+pytest
+```
+
+See `CLAUDE.md` for architecture details and the phase roadmap.
+
+---
+
+## License
+
+MIT

selvedge-0.1.0/README.md

@@ -0,0 +1,175 @@
+# Selvedge
+
+**Change tracking for AI-era codebases.**
+
+AI agents write your code now. But when they're done, the *why* disappears — the conversation that prompted the change, the reasoning behind the schema decision, the context that made the diff make sense. Selvedge captures all of it.
+
+```bash
+$ selvedge blame payments.amount
+
+  payments.amount
+  Changed     2025-11-03 14:22:01
+  Type        add
+  Agent       claude-code
+  Commit      a3f9c12
+  Diff        + amount DECIMAL(10,2) NOT NULL DEFAULT 0
+  Reasoning   User requested Stripe billing integration. Added amount column
+              to store transaction totals in cents per Stripe convention.
+```
+
+---
+
+## Install
+
+```bash
+pip install selvedge
+```
+
+## Quickstart
+
+**1. Initialize in your project**
+
+```bash
+cd your-project
+selvedge init
+```
+
+This creates `.selvedge/selvedge.db` in your project root. Commit it to share history with your team, or add `.selvedge/` to `.gitignore` to keep it local.
+
+**2. Add to your Claude Code config**
+
+`~/.claude/config.json`:
+```json
+{
+  "mcpServers": {
+    "selvedge": {
+      "command": "selvedge-server"
+    }
+  }
+}
+```
+
+**3. Tell your agent to use it**
+
+Add to your project's `CLAUDE.md`:
+```
+You have access to Selvedge for change tracking.
+Call selvedge.log_change immediately after adding, modifying, or removing
+any DB column, table, function, API endpoint, dependency, or env variable.
+Set `reasoning` to the user's original request or the problem being solved.
+Set `agent` to "claude-code".
+Before modifying an entity, call selvedge.blame to understand its history.
+```
+
+**4. Start querying**
+
+```bash
+selvedge status                        # recent activity
+selvedge diff users                    # all changes to the users table
+selvedge diff users.email              # changes to a specific column
+selvedge blame payments.amount         # what changed last and why
+selvedge history --since 30d           # last 30 days of changes
+selvedge search "stripe"               # full-text search
+```
+
+---
+
+## How it works
+
+Selvedge runs as an MCP server. AI agents in tools like Claude Code call Selvedge's tools as they work — logging structured change events to a local SQLite database.
+
+Each event records:
+- **What** changed (entity path, change type, diff)
+- **When** (timestamp)
+- **Who** (agent, session ID)
+- **Why** (reasoning — captured from the agent's context in the moment)
+- **Where** (git commit, project)
+
+The diff is git's job. The *why* is Selvedge's.
+
+---
+
+## Entity path conventions
+
+```
+users.email           DB column (table.column)
+users                 DB table
+src/auth.py::login    Function in a file (path::symbol)
+src/auth.py           File
+api/v1/users          API route
+deps/stripe           Dependency
+env/STRIPE_SECRET_KEY Environment variable
+```
+
+---
+
+## MCP tools
+
+When connected as an MCP server, Selvedge exposes:
+
+| Tool | Description |
+|------|-------------|
+| `log_change` | Record a change event |
+| `diff` | History for an entity or entity prefix |
+| `blame` | Most recent change + context for an entity |
+| `history` | Filtered history across all entities |
+| `search` | Full-text search across all events |
+
+---
+
+## CLI reference
+
+```
+selvedge init [--path PATH]               Initialize in project
+selvedge status                           Recent activity summary
+selvedge diff ENTITY [--limit N]          Change history for entity
+selvedge blame ENTITY                     Most recent change + context
+selvedge history [--since SINCE]          Browse all history
+              [--entity ENTITY]
+              [--project PROJECT]
+              [--limit N]
+selvedge search QUERY [--limit N]         Full-text search
+selvedge log ENTITY CHANGE_TYPE           Manually log a change
+             [--diff TEXT]
+             [--reasoning TEXT]
+             [--agent NAME]
+             [--commit HASH]
+             [--project NAME]
+```
+
+All read commands support `--json` for machine-readable output.
+
+**Relative time in `--since`:**
+- `7d` → last 7 days
+- `24h` → last 24 hours
+- `3m` → last 3 months
+- `1y` → last year
+
+---
+
+## Configuration
+
+| Method | Format | Example |
+|--------|--------|---------|
+| Env var | `SELVEDGE_DB=/path/to/db` | Per-session override |
+| Project init | `selvedge init` | Creates `.selvedge/selvedge.db` in CWD |
+| Global fallback | `~/.selvedge/selvedge.db` | Used if no project DB found |
+
+---
+
+## Contributing
+
+```bash
+git clone https://github.com/masondelan/selvedge
+cd selvedge
+pip install -e ".[dev]"
+pytest
+```
+
+See `CLAUDE.md` for architecture details and the phase roadmap.
+
+---
+
+## License
+
+MIT