cg-code-graph 0.11.0__tar.gz → 0.13.0__tar.gz

cg_code_graph-0.13.0/PKG-INFO

@@ -0,0 +1,84 @@
+Metadata-Version: 2.4
+Name: cg-code-graph
+Version: 0.13.0
+Summary: cg: a code graph of routes, calls, data access and platform boundaries for agents and humans (CLI + MCP server)
+Author: cyberchronos00
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/cyberchronos00/code-graph
+Project-URL: Changelog, https://github.com/cyberchronos00/code-graph/blob/main/CHANGELOG.md
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp>=2.2
+Requires-Dist: pyyaml>=6
+Requires-Dist: protobuf>=4.21
+Requires-Dist: tree-sitter>=0.23
+Requires-Dist: tree-sitter-rust>=0.23
+Requires-Dist: tree-sitter-c>=0.23
+Requires-Dist: tree-sitter-cpp>=0.23
+Requires-Dist: tree-sitter-kotlin>=1.0
+Requires-Dist: tree-sitter-swift<0.7.4,>=0.6
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Dynamic: license-file
+
+# code-graph
+
+**A deterministic dependency graph for Laravel, Django, FastAPI, Flask, NestJS, Next.js, Express, Nuxt, Flutter, Rust, C and C++ codebases, so you (and your AI agent) can see everything a change touches before you make it.**
+
+Ask "what depends on this table, connection, config key or method?" and get every caller, route, command and page that reaches it, each hop backed by `file:line` evidence. It runs locally on your source files. Answers are exact, deterministic and reproducible: the graph is built from parsers and the type checker, with no LLM in the graph. BloodHound-style: you walk real paths instead of grepping names.
+
+> **Status:** beta. Laravel (PHP), Django, FastAPI / Starlette and Flask (Python), TypeScript/JavaScript (Nuxt/Vue, NestJS, Next.js, Express/Fastify/Koa/Hono), Flutter (Dart), Rust, C and C++ are supported natively; other languages can be imported through SCIP.
+
+## Documentation
+
+**[code-graph docs](https://code-graph.cyberchronos00.workers.dev/)** — install, CLI, MCP, architecture, schema, languages and limitations.
+
+## Install
+
+`cg` is a user-level tool (no sudo, no checkout). The PyPI package is [`cg-code-graph`](https://pypi.org/project/cg-code-graph/); the commands are `cg` and `cg-mcp`.
+
+```bash
+pipx install cg-code-graph    # or: uv tool install cg-code-graph
+#   or the script (also installs exact-mode tools with --with c,rust,...):
+#     curl -fsSL https://raw.githubusercontent.com/cyberchronos00/code-graph/main/install.sh | sh
+#   or the latest commit: uv tool install git+https://github.com/cyberchronos00/code-graph
+cg doctor                     # what indexes exact / heuristic on this machine
+```
+
+Update with `uv tool upgrade cg-code-graph`, `pipx upgrade cg-code-graph` or `install.sh --update`. Caches live under `~/.cache/codegraph`; `cg clean` removes them. Windows, options and per-language toolchains: [install](https://code-graph.cyberchronos00.workers.dev/).
+
+## Quickstart
+
+Clone the repo for the bundled sample apps (a Laravel API and a Nuxt web app). Python 3.11+. PHP 8.2+ and Composer for the Laravel sample; Node.js 20+ for the TypeScript samples.
+
+```bash
+git clone https://github.com/cyberchronos00/code-graph.git && cd code-graph
+mkdir -p out
+cg index examples/bookstore-api --name bookstore-api --gates examples/bookstore.gates.json --db out/api.db
+cg index examples/bookstore-web --name bookstore-web --db out/web.db
+cg link --backend out/api.db --frontend out/web.db \
+        --backend-name bookstore-api --frontend-name bookstore-web --db out/graph.db
+
+cg reaches connection:warehouse table:warehouse_stock --db out/graph.db
+cg impact StockService::reserve --db out/graph.db
+cg path page:/reports/:id table:orders --db out/graph.db
+cg plan check preorders --plans-dir examples/plans --db out/graph.db
+```
+
+A workspace `.cg.yaml` can list several apps, including checkouts outside that directory, and `cg index` builds one combined graph. `cg link --repo` merges graphs you already indexed. Other samples in `examples/` (Nest, Next, Express, Django, Flutter, Rust, C, C++) index the same way. Queries, MCP (`cg-mcp --db out/graph.db`) and `cg serve` are in the [docs](https://code-graph.cyberchronos00.workers.dev/).
+
+## Preview
+
+[![cg visual view: the graph around the warehouse connection, a selected node with its evidence paths and source, then the planned-change overlay for the preorders plan](docs/media/cg-view-preview.gif)](docs/media/cg-view-demo.mp4)
+
+[![Terminal demo: cg indexes the bundled Laravel and Nuxt sample apps, links them, then runs reaches, path, impact and plan check](docs/media/cg-terminal-demo.gif)](docs/media/cg-terminal-demo.mp4)
+
+More recordings (setup, visual view, agent over MCP): [docs/media/](docs/media).
+
+## Links
+
+- [Documentation](https://code-graph.cyberchronos00.workers.dev/)
+- [PyPI: cg-code-graph](https://pypi.org/project/cg-code-graph/)
+- [GitHub releases](https://github.com/cyberchronos00/code-graph/releases)
+- [Changelog](CHANGELOG.md) · [Contributing](CONTRIBUTING.md) · [Security](SECURITY.md) · [License: MIT](LICENSE)

cg_code_graph-0.13.0/README.md

@@ -0,0 +1,60 @@
+# code-graph
+
+**A deterministic dependency graph for Laravel, Django, FastAPI, Flask, NestJS, Next.js, Express, Nuxt, Flutter, Rust, C and C++ codebases, so you (and your AI agent) can see everything a change touches before you make it.**
+
+Ask "what depends on this table, connection, config key or method?" and get every caller, route, command and page that reaches it, each hop backed by `file:line` evidence. It runs locally on your source files. Answers are exact, deterministic and reproducible: the graph is built from parsers and the type checker, with no LLM in the graph. BloodHound-style: you walk real paths instead of grepping names.
+
+> **Status:** beta. Laravel (PHP), Django, FastAPI / Starlette and Flask (Python), TypeScript/JavaScript (Nuxt/Vue, NestJS, Next.js, Express/Fastify/Koa/Hono), Flutter (Dart), Rust, C and C++ are supported natively; other languages can be imported through SCIP.
+
+## Documentation
+
+**[code-graph docs](https://code-graph.cyberchronos00.workers.dev/)** — install, CLI, MCP, architecture, schema, languages and limitations.
+
+## Install
+
+`cg` is a user-level tool (no sudo, no checkout). The PyPI package is [`cg-code-graph`](https://pypi.org/project/cg-code-graph/); the commands are `cg` and `cg-mcp`.
+
+```bash
+pipx install cg-code-graph    # or: uv tool install cg-code-graph
+#   or the script (also installs exact-mode tools with --with c,rust,...):
+#     curl -fsSL https://raw.githubusercontent.com/cyberchronos00/code-graph/main/install.sh | sh
+#   or the latest commit: uv tool install git+https://github.com/cyberchronos00/code-graph
+cg doctor                     # what indexes exact / heuristic on this machine
+```
+
+Update with `uv tool upgrade cg-code-graph`, `pipx upgrade cg-code-graph` or `install.sh --update`. Caches live under `~/.cache/codegraph`; `cg clean` removes them. Windows, options and per-language toolchains: [install](https://code-graph.cyberchronos00.workers.dev/).
+
+## Quickstart
+
+Clone the repo for the bundled sample apps (a Laravel API and a Nuxt web app). Python 3.11+. PHP 8.2+ and Composer for the Laravel sample; Node.js 20+ for the TypeScript samples.
+
+```bash
+git clone https://github.com/cyberchronos00/code-graph.git && cd code-graph
+mkdir -p out
+cg index examples/bookstore-api --name bookstore-api --gates examples/bookstore.gates.json --db out/api.db
+cg index examples/bookstore-web --name bookstore-web --db out/web.db
+cg link --backend out/api.db --frontend out/web.db \
+        --backend-name bookstore-api --frontend-name bookstore-web --db out/graph.db
+
+cg reaches connection:warehouse table:warehouse_stock --db out/graph.db
+cg impact StockService::reserve --db out/graph.db
+cg path page:/reports/:id table:orders --db out/graph.db
+cg plan check preorders --plans-dir examples/plans --db out/graph.db
+```
+
+A workspace `.cg.yaml` can list several apps, including checkouts outside that directory, and `cg index` builds one combined graph. `cg link --repo` merges graphs you already indexed. Other samples in `examples/` (Nest, Next, Express, Django, Flutter, Rust, C, C++) index the same way. Queries, MCP (`cg-mcp --db out/graph.db`) and `cg serve` are in the [docs](https://code-graph.cyberchronos00.workers.dev/).
+
+## Preview
+
+[![cg visual view: the graph around the warehouse connection, a selected node with its evidence paths and source, then the planned-change overlay for the preorders plan](docs/media/cg-view-preview.gif)](docs/media/cg-view-demo.mp4)
+
+[![Terminal demo: cg indexes the bundled Laravel and Nuxt sample apps, links them, then runs reaches, path, impact and plan check](docs/media/cg-terminal-demo.gif)](docs/media/cg-terminal-demo.mp4)
+
+More recordings (setup, visual view, agent over MCP): [docs/media/](docs/media).
+
+## Links
+
+- [Documentation](https://code-graph.cyberchronos00.workers.dev/)
+- [PyPI: cg-code-graph](https://pypi.org/project/cg-code-graph/)
+- [GitHub releases](https://github.com/cyberchronos00/code-graph/releases)
+- [Changelog](CHANGELOG.md) · [Contributing](CONTRIBUTING.md) · [Security](SECURITY.md) · [License: MIT](LICENSE)

cg_code_graph-0.13.0/cg_code_graph.egg-info/PKG-INFO

@@ -0,0 +1,84 @@
+Metadata-Version: 2.4
+Name: cg-code-graph
+Version: 0.13.0
+Summary: cg: a code graph of routes, calls, data access and platform boundaries for agents and humans (CLI + MCP server)
+Author: cyberchronos00
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/cyberchronos00/code-graph
+Project-URL: Changelog, https://github.com/cyberchronos00/code-graph/blob/main/CHANGELOG.md
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp>=2.2
+Requires-Dist: pyyaml>=6
+Requires-Dist: protobuf>=4.21
+Requires-Dist: tree-sitter>=0.23
+Requires-Dist: tree-sitter-rust>=0.23
+Requires-Dist: tree-sitter-c>=0.23
+Requires-Dist: tree-sitter-cpp>=0.23
+Requires-Dist: tree-sitter-kotlin>=1.0
+Requires-Dist: tree-sitter-swift<0.7.4,>=0.6
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Dynamic: license-file
+
+# code-graph
+
+**A deterministic dependency graph for Laravel, Django, FastAPI, Flask, NestJS, Next.js, Express, Nuxt, Flutter, Rust, C and C++ codebases, so you (and your AI agent) can see everything a change touches before you make it.**
+
+Ask "what depends on this table, connection, config key or method?" and get every caller, route, command and page that reaches it, each hop backed by `file:line` evidence. It runs locally on your source files. Answers are exact, deterministic and reproducible: the graph is built from parsers and the type checker, with no LLM in the graph. BloodHound-style: you walk real paths instead of grepping names.
+
+> **Status:** beta. Laravel (PHP), Django, FastAPI / Starlette and Flask (Python), TypeScript/JavaScript (Nuxt/Vue, NestJS, Next.js, Express/Fastify/Koa/Hono), Flutter (Dart), Rust, C and C++ are supported natively; other languages can be imported through SCIP.
+
+## Documentation
+
+**[code-graph docs](https://code-graph.cyberchronos00.workers.dev/)** — install, CLI, MCP, architecture, schema, languages and limitations.
+
+## Install
+
+`cg` is a user-level tool (no sudo, no checkout). The PyPI package is [`cg-code-graph`](https://pypi.org/project/cg-code-graph/); the commands are `cg` and `cg-mcp`.
+
+```bash
+pipx install cg-code-graph    # or: uv tool install cg-code-graph
+#   or the script (also installs exact-mode tools with --with c,rust,...):
+#     curl -fsSL https://raw.githubusercontent.com/cyberchronos00/code-graph/main/install.sh | sh
+#   or the latest commit: uv tool install git+https://github.com/cyberchronos00/code-graph
+cg doctor                     # what indexes exact / heuristic on this machine
+```
+
+Update with `uv tool upgrade cg-code-graph`, `pipx upgrade cg-code-graph` or `install.sh --update`. Caches live under `~/.cache/codegraph`; `cg clean` removes them. Windows, options and per-language toolchains: [install](https://code-graph.cyberchronos00.workers.dev/).
+
+## Quickstart
+
+Clone the repo for the bundled sample apps (a Laravel API and a Nuxt web app). Python 3.11+. PHP 8.2+ and Composer for the Laravel sample; Node.js 20+ for the TypeScript samples.
+
+```bash
+git clone https://github.com/cyberchronos00/code-graph.git && cd code-graph
+mkdir -p out
+cg index examples/bookstore-api --name bookstore-api --gates examples/bookstore.gates.json --db out/api.db
+cg index examples/bookstore-web --name bookstore-web --db out/web.db
+cg link --backend out/api.db --frontend out/web.db \
+        --backend-name bookstore-api --frontend-name bookstore-web --db out/graph.db
+
+cg reaches connection:warehouse table:warehouse_stock --db out/graph.db
+cg impact StockService::reserve --db out/graph.db
+cg path page:/reports/:id table:orders --db out/graph.db
+cg plan check preorders --plans-dir examples/plans --db out/graph.db
+```
+
+A workspace `.cg.yaml` can list several apps, including checkouts outside that directory, and `cg index` builds one combined graph. `cg link --repo` merges graphs you already indexed. Other samples in `examples/` (Nest, Next, Express, Django, Flutter, Rust, C, C++) index the same way. Queries, MCP (`cg-mcp --db out/graph.db`) and `cg serve` are in the [docs](https://code-graph.cyberchronos00.workers.dev/).
+
+## Preview
+
+[![cg visual view: the graph around the warehouse connection, a selected node with its evidence paths and source, then the planned-change overlay for the preorders plan](docs/media/cg-view-preview.gif)](docs/media/cg-view-demo.mp4)
+
+[![Terminal demo: cg indexes the bundled Laravel and Nuxt sample apps, links them, then runs reaches, path, impact and plan check](docs/media/cg-terminal-demo.gif)](docs/media/cg-terminal-demo.mp4)
+
+More recordings (setup, visual view, agent over MCP): [docs/media/](docs/media).
+
+## Links
+
+- [Documentation](https://code-graph.cyberchronos00.workers.dev/)
+- [PyPI: cg-code-graph](https://pypi.org/project/cg-code-graph/)
+- [GitHub releases](https://github.com/cyberchronos00/code-graph/releases)
+- [Changelog](CHANGELOG.md) · [Contributing](CONTRIBUTING.md) · [Security](SECURITY.md) · [License: MIT](LICENSE)

{cg_code_graph-0.11.0 → cg_code_graph-0.13.0}/cg_code_graph.egg-info/SOURCES.txt

@@ -9,19 +9,29 @@ cg_code_graph.egg-info/entry_points.txt
 cg_code_graph.egg-info/requires.txt
 cg_code_graph.egg-info/top_level.txt
 codegraph/__init__.py
+codegraph/agent_rules.py
+codegraph/agents.py
 codegraph/aitools.py
+codegraph/android_ipc.py
+codegraph/apple_ipc.py
 codegraph/apps.py
 codegraph/blindspots.py
 codegraph/bridges.py
+codegraph/brokers.py
 codegraph/cli.py
 codegraph/concepts.py
 codegraph/config.py
 codegraph/coverage.py
+codegraph/dart_isolates.py
 codegraph/doctor.py
 codegraph/external.py
+codegraph/graphql.py
 codegraph/indexer.py
+codegraph/jobs.py
 codegraph/link.py
 codegraph/lint_async.py
+codegraph/local_ipc.py
+codegraph/local_sockets.py
 codegraph/mcp_server.py
 codegraph/parity.py
 codegraph/parity_structure.py
@@ -32,13 +42,18 @@ codegraph/platforms.py
 codegraph/process_runs.py
 codegraph/query.py
 codegraph/realtime.py
+codegraph/realtime_events.py
+codegraph/realtime_native.py
+codegraph/realtime_ws.py
 codegraph/roundtrip.py
 codegraph/routes.py
 codegraph/rpc.py
+codegraph/sdk_systems.py
 codegraph/sockets.py
 codegraph/starters.py
 codegraph/tests_index.py
 codegraph/udp_apps.py
+codegraph/webhooks.py
 codegraph/xcode.py
 codegraph/core/__init__.py
 codegraph/core/cache.py
@@ -96,6 +111,7 @@ codegraph/plugins/nextjs/plugin.py
 codegraph/plugins/nuxt/__init__.py
 codegraph/plugins/nuxt/plugin.py
 codegraph/plugins/php/__init__.py
+codegraph/plugins/php/external.py
 codegraph/plugins/php/gating.py
 codegraph/plugins/php/plugin.py
 codegraph/plugins/php/strings.py
@@ -134,6 +150,7 @@ codegraph/plugins/swift/packages.py
 codegraph/plugins/swift/plugin.py
 codegraph/plugins/ts/__init__.py
 codegraph/plugins/ts/baseurl.py
+codegraph/plugins/ts/nav.py
 codegraph/plugins/ts/plugin.py
 codegraph/plugins/ts/extractor/extract.mjs
 codegraph/plugins/ts/extractor/fw.mjs
@@ -179,9 +196,14 @@ codegraph/viz/static/vendor/layout-base.js
 codegraph/viz/tools/package-lock.json
 codegraph/viz/tools/package.json
 codegraph/viz/tools/shoot.mjs
+tests/test_agents_install.py
+tests/test_agents_md.py
 tests/test_ai_tools.py
+tests/test_android_ipc.py
+tests/test_apple_ipc.py
 tests/test_bridges.py
 tests/test_bridges_pigeon_monorepo.py
+tests/test_brokers.py
 tests/test_cache_clean.py
 tests/test_cache_invalidation.py
 tests/test_channels_tests.py
@@ -190,15 +212,20 @@ tests/test_completeness.py
 tests/test_config_extras.py
 tests/test_coverage.py
 tests/test_coverage_ts_hint.py
+tests/test_dart_isolates.py
 tests/test_dispatch_interfaces.py
 tests/test_django_flutter.py
+tests/test_docs_links.py
 tests/test_enum_constants.py
 tests/test_external.py
 tests/test_gating.py
 tests/test_generated.py
+tests/test_graphql.py
 tests/test_impact_overrides.py
 tests/test_index_isolation.py
 tests/test_inherited_overrides.py
+tests/test_jobs.py
+tests/test_js_refs.py
 tests/test_kotlin.py
 tests/test_kotlin_binding.py
 tests/test_kotlin_exact.py
@@ -207,23 +234,29 @@ tests/test_kotlin_mixed.py
 tests/test_kotlin_nav_consts.py
 tests/test_kotlin_props.py
 tests/test_laravel_determinism.py
+tests/test_laravel_resources.py
 tests/test_lint_async.py
+tests/test_local_ipc.py
+tests/test_local_sockets.py
 tests/test_mcp.py
 tests/test_mcp_index.py
 tests/test_native_cfamily.py
 tests/test_native_concurrency.py
 tests/test_native_rust.py
+tests/test_nuxt_import_dirs.py
 tests/test_nuxt_rootsrc.py
 tests/test_packaging.py
 tests/test_parity.py
 tests/test_parity_structure.py
 tests/test_php_props.py
+tests/test_plain_js.py
 tests/test_plans.py
 tests/test_platform_gaps.py
 tests/test_platform_type_variants.py
 tests/test_platforms.py
 tests/test_platforms_apple.py
 tests/test_presets_config.py
+tests/test_process_ipc.py
 tests/test_process_runs.py
 tests/test_protocols.py
 tests/test_python_app_tests_module.py
@@ -238,10 +271,15 @@ tests/test_python_tests.py
 tests/test_python_web_hosts.py
 tests/test_python_web_routes.py
 tests/test_python_web_routes_more.py
+tests/test_realtime.py
+tests/test_realtime_native.py
 tests/test_roundtrip.py
+tests/test_route_tables.py
 tests/test_routes_search_explain.py
 tests/test_rpc.py
 tests/test_scip_health.py
+tests/test_sdk_external.py
+tests/test_snippet.py
 tests/test_sockets.py
 tests/test_starters_budget.py
 tests/test_swift.py
@@ -264,4 +302,8 @@ tests/test_ts_file_specs.py
 tests/test_ts_frameworks.py
 tests/test_ts_nuxt.py
 tests/test_values.py
-tests/test_viz.py
+tests/test_viz.py
+tests/test_vue_nav.py
+tests/test_webhooks.py
+tests/test_websockets.py
+tests/test_workspace_link.py

{cg_code_graph-0.11.0 → cg_code_graph-0.13.0}/codegraph/__init__.py

@@ -1,2 +1,2 @@
 """code-graph: deterministic code knowledge graph (beta)."""
-__version__ = "0.11.0"
+__version__ = "0.13.0"

cg_code_graph-0.13.0/codegraph/agent_rules.py

@@ -0,0 +1,57 @@
+"""Canonical "how to read this codebase with cg" guidance.
+
+Single source for this repo's AGENTS.md and for the blocks that `cg agents` installs into a
+project's AGENTS.md / CLAUDE.md / Cursor rules, so the wording never drifts. TEXT is the body;
+wrap it between BEGIN_MARK and END_MARK to get a block that can be replaced in place."""
+
+BEGIN_MARK = "<!-- BEGIN cg agent rules (managed by `cg agents`; edit cg, not here) -->"
+END_MARK = "<!-- END cg agent rules -->"
+
+TEXT = """\
+# Reading this codebase with cg
+
+This repository ships `cg`, a code-graph tool. Read the code by symbol through the index
+instead of opening whole files.
+
+## Build the index first
+    pip install -e . -q                     # make `cg` this checkout's version
+    cg index . --db out/graph.db --name repo
+There is no incremental index: re-run `cg index` after large changes.
+
+## Find code (get file:line; avoid ls / cat / broad grep)
+    cg search <name> --db out/graph.db        # nodes by name or FQN substring
+    cg impact <symbol> --db out/graph.db      # callers up to entry points (reverse)
+    cg downstream <symbol> --db out/graph.db  # what the symbol calls and reaches (forward)
+    cg node <symbol> --db out/graph.db        # one node's location, kind and edges
+`<symbol>` is a name, an FQN, `Class.method`, or a node id. Ambiguous names list candidates.
+
+## Read source (never cat a whole file; never more than ~200 lines at once)
+    cg snippet <symbol> --db out/graph.db                 # just that symbol's source, numbered
+    cg snippet <symbol> --db out/graph.db --context 5     # a few lines around it
+    sed -n '120,180p' path/to/file                      # a plain line range when needed
+`cg snippet` prints a `path:start-end` header then the body; `--max-lines` caps long bodies.
+
+## Follow an edge only when your change reaches it
+Use `cg impact` and `cg downstream` to decide whether a caller or callee matters before
+opening it. Chase a dependency only if your edit changes what crosses that edge.
+
+## After editing, re-query instead of rereading
+Re-run `cg index`, then `cg snippet` or `cg impact` on the changed spot to confirm the new
+shape, rather than reopening files.
+
+## Keep output small
+Pipe long output through `head` or `tail`:
+    cg impact <symbol> --db out/graph.db | head -n 40
+While iterating, run one file: `pytest -q -x tests/test_x.py`.
+Run the full suite once at the end: `pytest -q 2>&1 | tail -n 30`.
+"""
+
+
+def document() -> str:
+    """The repo-root AGENTS.md content (TEXT, newline-terminated)."""
+    return TEXT
+
+
+def block() -> str:
+    """The marked block `cg agents` writes into a project file; replaced in place on re-run."""
+    return BEGIN_MARK + "\n" + TEXT + END_MARK + "\n"

cg_code_graph-0.13.0/codegraph/agents.py

@@ -0,0 +1,150 @@
+"""`cg agents`: opt-in install of the cg usage guidance (and the cg MCP server entry) into a
+project's AGENTS.md / CLAUDE.md / Cursor rules. It only ever writes a clearly marked block and
+never writes silently: every run previews the exact changes and asks before writing (--dry-run
+previews without writing, --yes skips the prompt). Re-running replaces the block in place; remove
+deletes it and restores the surrounding bytes. MCP changes touch only the `cg` server entry."""
+from __future__ import annotations
+
+import difflib
+import json
+import re
+from pathlib import Path
+
+from . import agent_rules as AR
+
+# project guidance files `cg agents` can manage, by --target key
+TARGETS = {"agents": "AGENTS.md", "claude": "CLAUDE.md", "cursor": ".cursor/rules/cg.mdc"}
+DEFAULT_MCP_FILE = ".cursor/mcp.json"
+MCP_ENTRY = {"command": "cg-mcp", "args": ["--db", "out/graph.db"]}
+
+_CORE = re.compile(re.escape(AR.BEGIN_MARK) + r".*?" + re.escape(AR.END_MARK), re.S)
+
+
+def _core_text() -> str:
+    """The managed block without a trailing newline (BEGIN … END)."""
+    return AR.block().rstrip("\n")
+
+
+def plan_text(path: Path, remove: bool) -> dict:
+    """Decide the new content of one guidance file. action: insert | update | remove | noop.
+    Everything outside the marked block is preserved; a re-run replaces the block in place and
+    remove restores the bytes the matching insert added (for newline-terminated files)."""
+    old = path.read_text(encoding="utf-8") if path.exists() else ""
+    m = _CORE.search(old)
+    core = _core_text()
+    if remove:
+        if not m:
+            return {"path": str(path), "kind": "text", "action": "noop", "old": old, "new": old}
+        s, e = m.start(), m.end()
+        while e < len(old) and old[e] == "\n":          # drop the block's trailing newlines
+            e += 1
+        j = s
+        while j > 0 and old[j - 1] == "\n":             # drop separator newlines before it
+            j -= 1
+        s = j + 1 if j > 0 else 0                        # but keep one newline after real content
+        new = old[:s] + old[e:]
+        return {"path": str(path), "kind": "text", "action": "remove", "old": old, "new": new}
+    if m:
+        new = old[:m.start()] + core + old[m.end():]
+        return {"path": str(path), "kind": "text", "action": "update", "old": old, "new": new}
+    if not old:
+        new = core + "\n"
+    elif old.endswith("\n\n"):
+        new = old + core + "\n"
+    elif old.endswith("\n"):
+        new = old + "\n" + core + "\n"
+    else:
+        new = old + "\n\n" + core + "\n"
+    return {"path": str(path), "kind": "text", "action": "insert", "old": old, "new": new}
+
+
+def plan_mcp(path: Path, remove: bool) -> dict:
+    """Add / update / remove only the `cg` entry under mcpServers; every other entry and key is
+    kept. Returns action noop when there is nothing to change, or error when the file is not JSON."""
+    old = path.read_text(encoding="utf-8") if path.exists() else ""
+    if old.strip():
+        try:
+            data = json.loads(old)
+        except ValueError as ex:
+            return {"path": str(path), "kind": "mcp", "action": "error", "old": old, "new": old,
+                    "error": f"not valid JSON ({ex}); left unchanged"}
+    else:
+        data = {}
+    if not isinstance(data, dict):
+        return {"path": str(path), "kind": "mcp", "action": "error", "old": old, "new": old,
+                "error": "top level is not a JSON object; left unchanged"}
+    servers = data.get("mcpServers")
+    if not isinstance(servers, dict):
+        servers = {}
+    if remove:
+        if "cg" not in servers:
+            return {"path": str(path), "kind": "mcp", "action": "noop", "old": old, "new": old}
+        servers = {k: v for k, v in servers.items() if k != "cg"}
+        action = "remove"
+    else:
+        action = "update" if "cg" in servers else "insert"
+        servers = {**servers, "cg": MCP_ENTRY}
+    data = {**data, "mcpServers": servers}
+    new = json.dumps(data, indent=2) + "\n"
+    return {"path": str(path), "kind": "mcp", "action": action, "old": old, "new": new}
+
+
+def preview(plan: dict) -> str:
+    """A unified diff of one plan (the exact proposed change), or a one-line note for noop/error."""
+    if plan["action"] == "noop":
+        return f"{plan['path']}: no change (block not present)" if plan["kind"] == "text" \
+            else f"{plan['path']}: no change (no cg entry)"
+    if plan["action"] == "error":
+        return f"{plan['path']}: {plan['error']}"
+    diff = difflib.unified_diff(plan["old"].splitlines(True), plan["new"].splitlines(True),
+                                fromfile=plan["path"], tofile=plan["path"], n=1)
+    body = "".join(diff).rstrip("\n")
+    return f"{plan['path']}  [{plan['action']}]\n{body}"
+
+
+def build_plans(root: Path, targets: list[str], mcp: bool, mcp_file: str | None, remove: bool) -> list[dict]:
+    plans = [plan_text(root / TARGETS[t], remove) for t in targets]
+    if mcp:
+        plans.append(plan_mcp(Path(mcp_file) if mcp_file else root / DEFAULT_MCP_FILE, remove))
+    return plans
+
+
+def run(action: str, root: str = ".", targets: list[str] | None = None, all_targets: bool = False,
+        mcp: bool = False, mcp_file: str | None = None, dry_run: bool = False, assume_yes: bool = False,
+        input_fn=input, out=print) -> int:
+    """Entry point for the CLI. action: install | update | remove | show. Returns a process exit code."""
+    rootp = Path(root)
+    remove = action == "remove"
+    if all_targets:
+        sel = list(TARGETS)
+    elif targets:
+        sel = targets
+    else:                                   # default: the guidance files that already exist
+        sel = [t for t, f in TARGETS.items() if (rootp / f).exists()]
+    if not sel and not mcp:
+        out("nothing selected: pass --target agents|claude|cursor (repeatable), --all, or --mcp "
+            "(none of AGENTS.md / CLAUDE.md / .cursor/rules/cg.mdc exist here)")
+        return 2
+    plans = build_plans(rootp, sel, mcp, mcp_file, remove)
+    for p in plans:
+        out(preview(p))
+    if any(p["action"] == "error" for p in plans):
+        return 2
+    changing = [p for p in plans if p["action"] not in ("noop",)]
+    if action == "show" or dry_run:
+        out("(dry run: nothing written)" if dry_run else "(show: nothing written)")
+        return 0
+    if not changing:
+        out("nothing to do")
+        return 0
+    if not assume_yes:
+        resp = input_fn(f"apply {len(changing)} change(s)? [y/N] ")
+        if (resp or "").strip().lower() not in ("y", "yes"):
+            out("aborted; nothing written")
+            return 1
+    for p in changing:
+        fp = Path(p["path"])
+        fp.parent.mkdir(parents=True, exist_ok=True)
+        fp.write_text(p["new"], encoding="utf-8")
+        out(f"wrote {p['path']} ({p['action']})")
+    return 0