whygit 0.1.0__tar.gz

whygit-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kameswara Sai Srikar Manda
+
+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.

whygit-0.1.0/PKG-INFO

@@ -0,0 +1,226 @@
+Metadata-Version: 2.4
+Name: whygit
+Version: 0.1.0
+Summary: Explains what state your Git repository is in and how to fix it, in plain English. CLI and MCP server; read-only.
+Keywords: git,education,mcp,cli,merge-conflict,beginners
+Author: Kameswara Sai Srikar Manda
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Education
+Classifier: Topic :: Software Development :: Version Control :: Git
+Requires-Dist: mcp>=2.3,<3
+Requires-Python: >=3.10
+Project-URL: Homepage, https://github.com/Srikarmk/whygit
+Project-URL: Source, https://github.com/Srikarmk/whygit
+Project-URL: Issues, https://github.com/Srikarmk/whygit/issues
+Description-Content-Type: text/markdown
+
+# whygit
+
+**What just happened to my Git repository, and how do I fix it?**
+
+whygit looks at a Git repository and tells you, in plain English, what state it is in and
+which commands will get you out of it: a merge conflict, a rebase stopped halfway, a detached
+HEAD, a rejected push, a login GitHub won't accept, a 120 MB CSV that GitHub will refuse.
+Paste it an error message and it explains that too.
+
+It is written for people meeting Git for the first time. Git's own messages are accurate
+but hard to read; whygit turns them into a short explanation and the exact fix.
+
+It only ever **reads** your repository. It never runs the fixes it suggests, so you stay in
+control and learn the commands as you go.
+
+There are two ways to use it, built on the same engine:
+
+- **On the command line**, with no AI tools involved: `whygit`.
+- **As an MCP server**, so an assistant such as Claude Code, Claude Desktop or Cursor gets a
+  reliable diagnosis instead of guessing from `git status`.
+
+## Install
+
+whygit needs Python 3.10 or newer and Git. Pick one:
+
+```
+uv tool install whygit     # with uv (https://docs.astral.sh/uv/)
+pipx install whygit        # with pipx
+uvx whygit                 # run once without installing
+```
+
+This works the same on macOS, Windows and Linux.
+
+## Use it from the terminal
+
+Run it inside your project folder:
+
+```
+whygit                    # what's wrong here, most urgent first
+whygit status             # a plain summary: branch, upstream, what's changed
+whygit explain "fatal: refusing to merge unrelated histories"
+git push 2>&1 | whygit explain -
+```
+
+Options: `--path <folder>` (or `-C`) to look at another folder, `--json` for machine-readable
+output, `--no-color` to turn off colour. Colour is only used in a real terminal and never
+when `NO_COLOR` is set.
+
+Exit codes: `0` nothing blocking, `1` something blocking was found, `2` bad usage (for example
+the folder does not exist), `3` `explain` did not recognise the message.
+
+### Example
+
+```
+$ whygit
+whygit: /Users/sam/ds3500/hw2 (branch main)
+
+[BLOCKING] Merge in progress with conflicts in 1 file
+  Git tried to combine two lines of work, but both changed the same part of these
+  files, so it stopped and is waiting for you to choose what the result should be.
+  Nothing is lost while you decide.
+  Conflicted files:
+    - analysis.py  (both changed)
+  How to fix:
+    Finish the merge:
+      1. Open each file and find the blocks between <<<<<<< and >>>>>>>. The part
+         above ======= is one version, the part below is the other. Keep what you
+         want, and delete the three marker lines.
+      2. git add analysis.py
+         Marks the files as resolved
+      3. git commit --no-edit
+         Records the merge and finishes it
+    Or cancel the merge:
+      1. git merge --abort
+         Puts everything back the way it was before the merge started
+  Learn more: https://git-scm.com/docs/git-merge#_how_to_resolve_conflicts
+
+1 blocking. whygit never runs these commands for you; copy the ones you want.
+```
+
+Commands that can lose work (`git restore`, `git rebase --skip`, `git push --force-with-lease`
+and so on) are always marked with a warning, and a safer option is listed first when one
+exists.
+
+## Use it with an AI assistant (MCP)
+
+`whygit mcp` runs a Model Context Protocol server over stdio with three read-only tools:
+
+| Tool | Use it when | Returns |
+|---|---|---|
+| `diagnose_repo(path=".")` | something seems stuck or broken | every problem found, most urgent first, with explanation and fix |
+| `explain_git_error(error_text, path=None)` | a git command printed an error | what the error means and the fix, using the repository's state if `path` is given |
+| `explain_state(path=".")` | you want a neutral summary | branch, upstream, ahead/behind, remotes, staged and changed files, operations in progress |
+
+Results are small JSON objects. Pass an absolute path: relative paths resolve against the
+server's working directory, which for desktop apps is usually not your project. `~` works.
+
+### Claude Code
+
+```
+claude mcp add --scope user whygit -- uvx whygit mcp
+```
+
+`--scope user` makes it available in every project; leave it out to add it to the current
+project only. Check it with `claude mcp list`.
+
+### Claude Desktop
+
+Open Settings > Developer > Edit Config, and add whygit to
+`claude_desktop_config.json` (on macOS `~/Library/Application Support/Claude/`, on Windows
+`%APPDATA%\Claude\`):
+
+```json
+{
+  "mcpServers": {
+    "whygit": {
+      "command": "uvx",
+      "args": ["whygit", "mcp"]
+    }
+  }
+}
+```
+
+Restart Claude Desktop. If it can't find `uvx`, use the full path that `which uvx` (macOS)
+or `where uvx` (Windows) prints as the `command`.
+
+### Cursor
+
+Add the same block to `~/.cursor/mcp.json` (all projects) or `.cursor/mcp.json` in a project:
+
+```json
+{
+  "mcpServers": {
+    "whygit": {
+      "command": "uvx",
+      "args": ["whygit", "mcp"]
+    }
+  }
+}
+```
+
+If you installed whygit with `uv tool install` or `pipx`, you can use `"command": "whygit"`
+with `"args": ["mcp"]` instead.
+
+## What it recognises
+
+Repository states: merge conflicts (and a merge that is resolved but not committed, including
+leftover `<<<<<<<` markers), a rebase stopped on a conflict or an `edit`, cherry-pick, revert,
+`git am` and bisect in progress, detached HEAD (and commits that no branch points to),
+diverged / behind / ahead of the upstream, no upstream yet (the first `git push -u`), no
+remote, upstream branch deleted, no commits yet, not a repository (including being one folder
+too high, and your home folder), a home folder that was accidentally turned into a
+repository, nested repositories (common with downloaded starter code), files over GitHub's
+100 MB limit (and over 50 MB) staged or in unpushed commits, files that usually hold secrets
+(`.env`, `id_rsa`, `*.pem`, `kaggle.json`, credentials JSON), notebooks with large saved
+outputs, Jupyter notebook conflicts, missing `user.name` / `user.email`, a leftover
+`index.lock`, and folders Git refuses because of "dubious ownership".
+
+Error messages: rejected pushes, "You have divergent branches", "refusing to merge unrelated
+histories", GitHub login failures (passwords no longer work; it explains tokens, SSH and
+`gh auth login`, and never asks for your token), `Permission denied (publickey)`, repository
+not found, 403, "Your local changes would be overwritten", untracked files in the way,
+"not a git repository", "src refspec main does not match any", "pathspec did not match",
+"remote origin already exists", missing upstream, "couldn't find remote ref", GitHub's
+large-file rejection (GH001), "detected dubious ownership", "Please tell me who you are",
+`index.lock` exists, line-ending warnings, network errors, and more. If it doesn't recognise
+a message, it says so and shows what it can see in the repository instead.
+
+## The read-only promise
+
+whygit never changes your repository, and this is enforced in code rather than left to good
+intentions:
+
+- Every Git command goes through a single function that only accepts read-only subcommands
+  (`status`, `rev-parse`, `for-each-ref`, `rev-list`, `diff`, `log`, `ls-files`, `cat-file`,
+  `config --get`, `remote -v`, ...) and refuses anything else, including the writing forms of
+  `config`, `remote` and `symbolic-ref`.
+- It sets `GIT_OPTIONAL_LOCKS=0`, so even `git status` doesn't refresh the index, and turns off
+  external diff programs and the fsmonitor hook.
+- It never runs `git fetch`. Ahead/behind counts are "as of your last fetch", and whygit tells
+  you to run `git fetch` yourself when that matters.
+- The test suite builds each state in a real repository, snapshots every file under `.git`
+  (names, timestamps and contents) before and after diagnosing, and checks nothing changed. It
+  also checks that no other module in the package can start a process or write a file.
+
+Credentials are never printed: a remote address like `https://name:token@github.com/...`
+is shown as `https://***@github.com/...`, in every output.
+
+## Privacy
+
+whygit collects nothing and makes no network calls. It reads your repository on your own
+computer and prints the result. That's all.
+
+## Licence
+
+MIT. Copyright (c) 2026 Kameswara Sai Srikar Manda.

whygit-0.1.0/README.md

@@ -0,0 +1,196 @@
+# whygit
+
+**What just happened to my Git repository, and how do I fix it?**
+
+whygit looks at a Git repository and tells you, in plain English, what state it is in and
+which commands will get you out of it: a merge conflict, a rebase stopped halfway, a detached
+HEAD, a rejected push, a login GitHub won't accept, a 120 MB CSV that GitHub will refuse.
+Paste it an error message and it explains that too.
+
+It is written for people meeting Git for the first time. Git's own messages are accurate
+but hard to read; whygit turns them into a short explanation and the exact fix.
+
+It only ever **reads** your repository. It never runs the fixes it suggests, so you stay in
+control and learn the commands as you go.
+
+There are two ways to use it, built on the same engine:
+
+- **On the command line**, with no AI tools involved: `whygit`.
+- **As an MCP server**, so an assistant such as Claude Code, Claude Desktop or Cursor gets a
+  reliable diagnosis instead of guessing from `git status`.
+
+## Install
+
+whygit needs Python 3.10 or newer and Git. Pick one:
+
+```
+uv tool install whygit     # with uv (https://docs.astral.sh/uv/)
+pipx install whygit        # with pipx
+uvx whygit                 # run once without installing
+```
+
+This works the same on macOS, Windows and Linux.
+
+## Use it from the terminal
+
+Run it inside your project folder:
+
+```
+whygit                    # what's wrong here, most urgent first
+whygit status             # a plain summary: branch, upstream, what's changed
+whygit explain "fatal: refusing to merge unrelated histories"
+git push 2>&1 | whygit explain -
+```
+
+Options: `--path <folder>` (or `-C`) to look at another folder, `--json` for machine-readable
+output, `--no-color` to turn off colour. Colour is only used in a real terminal and never
+when `NO_COLOR` is set.
+
+Exit codes: `0` nothing blocking, `1` something blocking was found, `2` bad usage (for example
+the folder does not exist), `3` `explain` did not recognise the message.
+
+### Example
+
+```
+$ whygit
+whygit: /Users/sam/ds3500/hw2 (branch main)
+
+[BLOCKING] Merge in progress with conflicts in 1 file
+  Git tried to combine two lines of work, but both changed the same part of these
+  files, so it stopped and is waiting for you to choose what the result should be.
+  Nothing is lost while you decide.
+  Conflicted files:
+    - analysis.py  (both changed)
+  How to fix:
+    Finish the merge:
+      1. Open each file and find the blocks between <<<<<<< and >>>>>>>. The part
+         above ======= is one version, the part below is the other. Keep what you
+         want, and delete the three marker lines.
+      2. git add analysis.py
+         Marks the files as resolved
+      3. git commit --no-edit
+         Records the merge and finishes it
+    Or cancel the merge:
+      1. git merge --abort
+         Puts everything back the way it was before the merge started
+  Learn more: https://git-scm.com/docs/git-merge#_how_to_resolve_conflicts
+
+1 blocking. whygit never runs these commands for you; copy the ones you want.
+```
+
+Commands that can lose work (`git restore`, `git rebase --skip`, `git push --force-with-lease`
+and so on) are always marked with a warning, and a safer option is listed first when one
+exists.
+
+## Use it with an AI assistant (MCP)
+
+`whygit mcp` runs a Model Context Protocol server over stdio with three read-only tools:
+
+| Tool | Use it when | Returns |
+|---|---|---|
+| `diagnose_repo(path=".")` | something seems stuck or broken | every problem found, most urgent first, with explanation and fix |
+| `explain_git_error(error_text, path=None)` | a git command printed an error | what the error means and the fix, using the repository's state if `path` is given |
+| `explain_state(path=".")` | you want a neutral summary | branch, upstream, ahead/behind, remotes, staged and changed files, operations in progress |
+
+Results are small JSON objects. Pass an absolute path: relative paths resolve against the
+server's working directory, which for desktop apps is usually not your project. `~` works.
+
+### Claude Code
+
+```
+claude mcp add --scope user whygit -- uvx whygit mcp
+```
+
+`--scope user` makes it available in every project; leave it out to add it to the current
+project only. Check it with `claude mcp list`.
+
+### Claude Desktop
+
+Open Settings > Developer > Edit Config, and add whygit to
+`claude_desktop_config.json` (on macOS `~/Library/Application Support/Claude/`, on Windows
+`%APPDATA%\Claude\`):
+
+```json
+{
+  "mcpServers": {
+    "whygit": {
+      "command": "uvx",
+      "args": ["whygit", "mcp"]
+    }
+  }
+}
+```
+
+Restart Claude Desktop. If it can't find `uvx`, use the full path that `which uvx` (macOS)
+or `where uvx` (Windows) prints as the `command`.
+
+### Cursor
+
+Add the same block to `~/.cursor/mcp.json` (all projects) or `.cursor/mcp.json` in a project:
+
+```json
+{
+  "mcpServers": {
+    "whygit": {
+      "command": "uvx",
+      "args": ["whygit", "mcp"]
+    }
+  }
+}
+```
+
+If you installed whygit with `uv tool install` or `pipx`, you can use `"command": "whygit"`
+with `"args": ["mcp"]` instead.
+
+## What it recognises
+
+Repository states: merge conflicts (and a merge that is resolved but not committed, including
+leftover `<<<<<<<` markers), a rebase stopped on a conflict or an `edit`, cherry-pick, revert,
+`git am` and bisect in progress, detached HEAD (and commits that no branch points to),
+diverged / behind / ahead of the upstream, no upstream yet (the first `git push -u`), no
+remote, upstream branch deleted, no commits yet, not a repository (including being one folder
+too high, and your home folder), a home folder that was accidentally turned into a
+repository, nested repositories (common with downloaded starter code), files over GitHub's
+100 MB limit (and over 50 MB) staged or in unpushed commits, files that usually hold secrets
+(`.env`, `id_rsa`, `*.pem`, `kaggle.json`, credentials JSON), notebooks with large saved
+outputs, Jupyter notebook conflicts, missing `user.name` / `user.email`, a leftover
+`index.lock`, and folders Git refuses because of "dubious ownership".
+
+Error messages: rejected pushes, "You have divergent branches", "refusing to merge unrelated
+histories", GitHub login failures (passwords no longer work; it explains tokens, SSH and
+`gh auth login`, and never asks for your token), `Permission denied (publickey)`, repository
+not found, 403, "Your local changes would be overwritten", untracked files in the way,
+"not a git repository", "src refspec main does not match any", "pathspec did not match",
+"remote origin already exists", missing upstream, "couldn't find remote ref", GitHub's
+large-file rejection (GH001), "detected dubious ownership", "Please tell me who you are",
+`index.lock` exists, line-ending warnings, network errors, and more. If it doesn't recognise
+a message, it says so and shows what it can see in the repository instead.
+
+## The read-only promise
+
+whygit never changes your repository, and this is enforced in code rather than left to good
+intentions:
+
+- Every Git command goes through a single function that only accepts read-only subcommands
+  (`status`, `rev-parse`, `for-each-ref`, `rev-list`, `diff`, `log`, `ls-files`, `cat-file`,
+  `config --get`, `remote -v`, ...) and refuses anything else, including the writing forms of
+  `config`, `remote` and `symbolic-ref`.
+- It sets `GIT_OPTIONAL_LOCKS=0`, so even `git status` doesn't refresh the index, and turns off
+  external diff programs and the fsmonitor hook.
+- It never runs `git fetch`. Ahead/behind counts are "as of your last fetch", and whygit tells
+  you to run `git fetch` yourself when that matters.
+- The test suite builds each state in a real repository, snapshots every file under `.git`
+  (names, timestamps and contents) before and after diagnosing, and checks nothing changed. It
+  also checks that no other module in the package can start a process or write a file.
+
+Credentials are never printed: a remote address like `https://name:token@github.com/...`
+is shown as `https://***@github.com/...`, in every output.
+
+## Privacy
+
+whygit collects nothing and makes no network calls. It reads your repository on your own
+computer and prints the result. That's all.
+
+## Licence
+
+MIT. Copyright (c) 2026 Kameswara Sai Srikar Manda.

whygit-0.1.0/pyproject.toml

@@ -0,0 +1,61 @@
+[project]
+name = "whygit"
+version = "0.1.0"
+description = "Explains what state your Git repository is in and how to fix it, in plain English. CLI and MCP server; read-only."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = [
+    "git",
+    "education",
+    "mcp",
+    "cli",
+    "merge-conflict",
+    "beginners",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Education",
+    "Intended Audience :: Developers",
+    "Operating System :: MacOS",
+    "Operating System :: Microsoft :: Windows",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Education",
+    "Topic :: Software Development :: Version Control :: Git",
+]
+dependencies = ["mcp>=2.3,<3"]
+
+[[project.authors]]
+name = "Kameswara Sai Srikar Manda"
+
+[project.urls]
+Homepage = "https://github.com/Srikarmk/whygit"
+Source = "https://github.com/Srikarmk/whygit"
+Issues = "https://github.com/Srikarmk/whygit/issues"
+
+[project.scripts]
+whygit = "whygit.cli:main"
+
+[dependency-groups]
+dev = [
+    "pytest>=8",
+    "anyio>=4",
+]
+
+[build-system]
+requires = ["uv_build>=0.9,<0.14"]
+build-backend = "uv_build"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 120

whygit-0.1.0/pyproject.toml.orig

@@ -0,0 +1,49 @@
+[project]
+name = "whygit"
+version = "0.1.0"
+description = "Explains what state your Git repository is in and how to fix it, in plain English. CLI and MCP server; read-only."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Kameswara Sai Srikar Manda" }]
+keywords = ["git", "education", "mcp", "cli", "merge-conflict", "beginners"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Education",
+    "Intended Audience :: Developers",
+    "Operating System :: MacOS",
+    "Operating System :: Microsoft :: Windows",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Education",
+    "Topic :: Software Development :: Version Control :: Git",
+]
+dependencies = ["mcp>=2.3,<3"]
+
+[project.urls]
+Homepage = "https://github.com/Srikarmk/whygit"
+Source = "https://github.com/Srikarmk/whygit"
+Issues = "https://github.com/Srikarmk/whygit/issues"
+
+[project.scripts]
+whygit = "whygit.cli:main"
+
+[dependency-groups]
+dev = ["pytest>=8", "anyio>=4"]
+
+[build-system]
+requires = ["uv_build>=0.9,<0.14"]
+build-backend = "uv_build"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 120

whygit-0.1.0/src/whygit/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

whygit-0.1.0/src/whygit/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())

whygit-0.1.0/src/whygit/cli.py

@@ -0,0 +1,109 @@
+"""Command line front end: whygit, whygit status, whygit explain, whygit mcp."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from . import __version__
+from .engine import PathNotFound, diagnose, explain_error, explain_state
+from .render import Style, render_diagnosis, render_explanation, render_state, want_color
+
+EPILOG = """examples:
+  whygit                          explain what's going on in this repository
+  whygit status                   plain summary: branch, upstream, changes
+  whygit explain "fatal: refusing to merge unrelated histories"
+  git push 2>&1 | whygit explain -
+  whygit mcp                      run as an MCP server (for Claude Code, Cursor, Claude Desktop)
+
+whygit only reads your repository. It never runs the fixes it suggests."""
+
+
+def _common(p: argparse.ArgumentParser, suppress: bool) -> None:
+    d = argparse.SUPPRESS if suppress else None
+    p.add_argument(
+        "--path", "-C", default=d if suppress else ".", help="repository folder to look at (default: current folder)"
+    )
+    p.add_argument("--json", action="store_true", default=d if suppress else False, help="print JSON instead of text")
+    p.add_argument("--no-color", action="store_true", default=d if suppress else False, help="never use colour")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="whygit",
+        description="Explains what state your Git repository is in and how to fix it, in plain English.",
+        epilog=EPILOG,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument("--version", action="version", version=f"whygit {__version__}")
+    _common(parser, suppress=False)
+    sub = parser.add_subparsers(dest="command", metavar="command")
+    p = sub.add_parser("diagnose", help="list problems, most urgent first (the default)")
+    _common(p, suppress=True)
+    p = sub.add_parser("status", help="plain summary of the repository")
+    _common(p, suppress=True)
+    p = sub.add_parser("explain", help="explain a git error message ('-' reads it from stdin)")
+    p.add_argument("text", nargs="*", help="the error text, or - to read from stdin")
+    _common(p, suppress=True)
+    sub.add_parser("mcp", help="run the MCP server over stdio")
+    return parser
+
+
+def _setup_stdout() -> None:
+    for stream in (sys.stdout, sys.stderr):
+        try:
+            stream.reconfigure(errors="replace")
+        except (AttributeError, ValueError):
+            pass
+
+
+def main(argv: list[str] | None = None) -> int:
+    _setup_stdout()
+    args = build_parser().parse_args(argv)
+    if args.command == "mcp":
+        from .server import main as server_main
+
+        server_main()
+        return 0
+    style = Style(want_color(force_off=args.no_color or args.json))
+    try:
+        if args.command == "status":
+            res = explain_state(args.path)
+            _emit(res, args.json, lambda r: render_state(r, style))
+            return 0
+        if args.command == "explain":
+            text = " ".join(args.text)
+            if text.strip() in ("", "-"):
+                if sys.stdin is not None and sys.stdin.isatty():
+                    print(
+                        "Paste the error text, then press Ctrl-D (macOS/Linux) or Ctrl-Z then Enter (Windows):",
+                        file=sys.stderr,
+                    )
+                text = sys.stdin.read() if sys.stdin is not None else ""
+            if not text.strip():
+                print("whygit explain: no error text given.", file=sys.stderr)
+                return 2
+            res = explain_error(text, args.path)
+            _emit(res, args.json, lambda r: render_explanation(r, style))
+            return 0 if res.get("recognised") else 3
+        res = diagnose(args.path)
+        _emit(res, args.json, lambda r: render_diagnosis(r, style))
+        return 1 if any(f["severity"] == "blocking" for f in res["findings"]) else 0
+    except PathNotFound as exc:
+        print(
+            f"whygit: the folder {exc} does not exist. Use --path with your project folder, or cd into it first.",
+            file=sys.stderr,
+        )
+        return 2
+
+
+def _emit(res: dict, as_json: bool, render) -> None:
+    if as_json:
+        print(json.dumps(res, indent=2, ensure_ascii=False))
+    else:
+        print(render(res))
+
+
+if __name__ == "__main__":
+    sys.exit(main())