Metadata-Version: 2.5
Name: doubled-graph
Version: 2.0.1
Summary: MCP facade over CodeGraphContext + GRACE 4 (.grace artifacts): impact, context, drift-detect, migration for LLM-driven codebases.
Project-URL: Homepage, https://github.com/rour/doubled-graph-mcp
Project-URL: Repository, https://github.com/rour/doubled-graph-mcp
Project-URL: Issues, https://github.com/rour/doubled-graph-mcp/issues
Project-URL: Documentation, https://github.com/rour/doubled-graph-mcp/blob/main/docs/SPEC.md
Author: doubled-graph methodology authors
License: MIT
License-File: LICENSE
Keywords: ast,claude,codebase,continue,cursor,graph,llm,mcp
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Code Generators
Classifier: Topic :: Software Development :: Documentation
Requires-Python: >=3.11
Requires-Dist: anyio>=4.15.1
Requires-Dist: codegraphcontext>=0.6.13
Requires-Dist: mcp<2,>=1.30.0
Requires-Dist: pydantic>=2.14.1
Requires-Dist: tree-sitter-language-pack>=1.22.1
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Description-Content-Type: text/markdown

# doubled-graph

MCP-сервер для LLM-агентов, работающих с большими кодовыми базами.

Проблема: агент правит код не зная, кто вызывает функцию и какой у неё контракт — получаем регрессии и тихий дрейф. `doubled-graph` даёт агенту два графа одновременно:

- **Computed graph** — AST-граф реального кода (через CodeGraphContext): кто вызывает что, где определено.
- **Declared graph** — граф из артефактов GRACE 4 (`.grace/`): замысел, контракты, верификация.

Четыре MCP-инструмента:

| Инструмент | Когда |
|---|---|
| `analyze` | построить/обновить граф |
| `impact` | радиус влияния изменений — **до** правки |
| `context` | 360° вид: символ + контракт + вызовы |
| `detect_changes` | дрейф кода от артефактов — **до** коммита |

---

## Установка

**Требования:** Python 3.11+, Bun ≥ 1.3.14 или Node+tsx (движок `@osovv/grace-cli` 4.2.1),
[pipx](https://pipx.pypa.io/).

`doubled-graph` — CLI-утилита. Рекомендуемый способ — `pipx`: он ставит её в изолированный venv и кладёт бинарь в PATH. Это также обходит PEP 668 (`externally-managed-environment`) на современных Homebrew/Debian/Ubuntu.

### 1. Установить pipx

| OS | Команда |
|---|---|
| macOS | `brew install pipx` |
| Debian / Ubuntu | `sudo apt install pipx` |
| Fedora | `sudo dnf install pipx` |
| Arch | `sudo pacman -S python-pipx` |
| Windows / прочее | `python3 -m pip install --user pipx` |

После установки один раз добавьте pipx-папку в PATH и перезапустите терминал:

```bash
pipx ensurepath
```

### 2. Установить doubled-graph

```bash
pipx install doubled-graph
```

> Уже работаете в своём venv или conda-окружении? Тогда подойдёт обычная установка: `python3 -m pip install doubled-graph`.

---

## Первые шаги

### 1. Онбординг репозитория

```bash
cd your-project
doubled-graph setup
```

Одна команда:
- установит `@osovv/grace-cli@4.2.1` через первый найденный JS-менеджер (`bun` → `npm` → `yarn` → `pnpm`); если Bun отсутствует — поставит `tsx` тем же менеджером и запустит grace под Node. Установленный движок 3.x будет обновлён: он умеет читать только `docs/*.xml`
- подготовит артефакты `.grace`: мигрирует GRACE 3 `docs/*.xml` (копирование, без удаления исходников) или создаст пустой скелет Grace 4, если артефактов нет вовсе
- скопирует `prompts/` и `methodology/` в репозиторий
- запишет 7 наших skills в native-формат для всех известных IDE одновременно (`.claude/skills/`, `.cursor/rules/`, `.continue/rules/`, `.roo/rules/`, `.kilocode/rules/`, `.opencode/rules/` + `opencode.json`, `.windsurfrules`) — мы не знаем, каким клиентом вы пользуетесь
- зарегистрирует MCP-сервер в вашей IDE (Claude Code / Cursor / Continue)
- установит `git post-commit` хук для автообновления графа
- запустит первый полный `analyze`

Посмотреть план без реальных изменений:

```bash
doubled-graph setup --dry-run
```

Явно указать IDE:

```bash
doubled-graph setup --ide claude-code
```

### 2. Подключить MCP вручную (если нужно)

Рекомендуем `doubled-graph setup` — он сам сгенерирует `.mcp.json` с правильными значениями. Это важно: GUI-приложения (Claude Desktop, Cursor, Continue) на macOS стартуют без `~/.local/bin` в PATH, и простая запись `command: "doubled-graph"` у них не работает.

Если нужно прописать руками — используйте абсолютный путь к Python, в который установлен `doubled-graph`:

```bash
# Узнать путь к нужному Python:
doubled-graph --version  # проверить, что бинарь работает
head -1 "$(which doubled-graph)"  # вывести shebang — это и есть нужный python
```

`.mcp.json` в корне репозитория:

```json
{
  "mcpServers": {
    "doubled-graph": {
      "command": "/Users/you/.local/pipx/venvs/doubled-graph/bin/python",
      "args": ["-m", "doubled_graph", "serve"]
    }
  }
}
```

### 3. Инициализация

Введите в ваш ИИ первый промт. Остальные промты он сам подгрузит.

Сценарий 1. Новый проект — `prompts/new-project/00-entry-prompt.md`.

Сценарий 2. Миграция существующего — `prompts/migrate-existing-project/00-entry-prompt.md`.

Сценарий 3. Обновление версии методики (1.9.x → 2.0) — `prompts/upgrade-methodology/00-entry-prompt.md`.

### 4. Проверить, что всё встало

```bash
doubled-graph --version          # 2.0.1
doubled-graph status --repo .    # artifacts.project_kind = grace4, grace_engine.upgrade_required = false
doubled-graph lint --repo .      # summary.errors = 0
doubled-graph migrate check --repo .   # map_pending / placeholders — что осталось заполнить
```

Если `project_kind` = `grace3` — артефакты ещё не перенесены: `doubled-graph setup --repo .`.
Если `upgrade_required` = `true` — движок старее 4.x: `npm install -g @osovv/grace-cli@4.2.1`, затем `setup` повторно.
Если `lint` вернул `markup.module-map-missing` — это содержательная работа, промпт `prompts/upgrade-methodology/01-content-gaps.md`.


---

## Другие команды

```bash
# Диагностика миграции GRACE 3 -> GRACE 4 (ничего не пишет)
doubled-graph migrate check

# Миграция артефактов (legacy docs/*.xml остаются на месте)
doubled-graph migrate apply --dry-run
doubled-graph migrate apply

# Шлюз к движку: линт, модули, файлы, верификации
doubled-graph lint
doubled-graph module show M-AUTH
doubled-graph module health M-AUTH
doubled-graph file show src/auth.py
doubled-graph verify V-M-AUTH
doubled-graph status
doubled-graph --version

# Обновить граф вручную
doubled-graph analyze --mode auto

# 360° контекст символа
doubled-graph context validateUser

# Текущая фаза методологии (migration | post_migration)
doubled-graph phase get
doubled-graph phase set post_migration --reason "migration complete"
```

---

## Удаление

```bash
pipx uninstall doubled-graph
```

(или `python3 -m pip uninstall doubled-graph`, если ставили в venv).

Это снимает сам CLI и Python-зависимости. Артефакты, которые `doubled-graph setup` создал в вашем репозитории, нужно удалить вручную:

- запись `doubled-graph` в `.mcp.json` (Claude Code) / `.cursor/mcp.json` / `.continue/config.json`
- скопированные `prompts/` и `methodology/` — если они больше не нужны
- skill-файлы для IDE: каталоги `.claude/skills/doubled-graph-*/`, `.cursor/rules/doubled-graph-*.mdc`, `.continue/rules/doubled-graph-*.md`, `.roo/rules/doubled-graph-*.md`, `.kilocode/rules/doubled-graph-*.md`, `.opencode/rules/doubled-graph-*.md`, блок между `<!-- doubled-graph-skills:start -->` / `<!-- ... :end -->` в `.windsurfrules`, и запись `.opencode/rules/*.md` в `opencode.json` `instructions`
- git-хук `.git/hooks/post-commit` (проверьте содержимое — там может быть ваша логика поверх нашей)
- локальный кеш графа: `rm -rf .doubled-graph`
- grace-cli (отдельный Bun/Node-пакет 4.x) — через тот менеджер, которым ставился: `bun remove -g @osovv/grace-cli` или `npm uninstall -g @osovv/grace-cli`

---

## Обновление с 1.9.x (GRACE 3 → GRACE 4)

2.0 — ломающий релиз: движок `@osovv/grace-cli` 4.x валидирует только `.grace`
и отказывается читать `docs/*.xml`. Клиенту нужны два шага:

```bash
pipx upgrade doubled-graph   # 1. обновить пакет
cd your-project
doubled-graph setup          # 2. обновить движок и подготовить .grace
```

Что делает `setup`: ставит движок 4.2.1, конвертирует `docs/*.xml` → `.grace`
(модули `M-*`, зависимости, `V-M-*` с командами/сценариями/тест-файлами),
создаёт недостающие обязательные документы, добавляет `LINKS: M-*` в
`MODULE_CONTRACT` (без этого файл не привязан к модулю), приводит `MAP_MODE`
в соответствие с `ROLE`. Legacy `docs/` не изменяются и не удаляются.

Если миграцию не сделать:

| Сценарий | Последствия |
|---|---|
| Остались на 1.9.x | Всё работает по-старому, но без обновлений и поддержки `.grace` |
| Обновили 2.0, `setup` не запускали | `doubled-graph lint` → `project.grace3-detected` (exit 1), MCP `file_show`/`module_show` → `invalid-project`; `impact`/`context`/`detect_changes` продолжают читать legacy `docs/*.xml` с пометкой `deprecated` |
| Мигрировали, но `LINKS` не поправили | lint зелёный, но модули «пустые»: `module show` не показывает файлы, `detect_changes` даёт `code_without_module` на весь код |

Обновление версии методики — отдельный (третий) сценарий, он не требует проходить миграцию
заново: [prompts/upgrade-methodology/00-entry-prompt.md](prompts/upgrade-methodology/00-entry-prompt.md)
(готовый промт для ИИ: статус → `setup` → проверки → закрытие пробелов).

После обновления остаётся только содержательная работа — заполнить пустые
`V-<M>` и `MODULE_MAP` по реальному коду и тестам. Готовый промпт:
[prompts/upgrade-methodology/01-content-gaps.md](prompts/upgrade-methodology/01-content-gaps.md)
— скопируйте текст из блока «Промт» в ИИ-ассистента; он соберёт `map_pending` /
`placeholders`, допишет карты модулей, заполнит верификации командами из
существующих тестов и прогонит финальные проверки. Выдуманные команды запрещены
(иначе «не проверено» станет «проверено»). При желании можно архивировать
`docs/` — отдельным решением.

---

## Документация

- [SPEC.md](docs/SPEC.md) — архитектура, хранилище `.doubled-graph/`
- [TOOLS.md](docs/TOOLS.md) — подробные схемы инструментов
- [HOOKS.md](docs/HOOKS.md) — git и Claude Code хуки
- [CHANGELOG.md](docs/CHANGELOG.md) — история изменений

---

## Лицензия

MIT. Upstream-компоненты (CodeGraphContext, grace-marketplace) — MIT.
