gitpro 0.3.3__tar.gz → 0.4.0__tar.gz

{gitpro-0.3.3 → gitpro-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: gitpro
-Version: 0.3.3
+Version: 0.4.0
 Summary: Per-remote git identities (name, email, SSH key, commit signing) from one TOML file
 Project-URL: Homepage, https://gitpro.dev
 Project-URL: Source, https://github.com/Yantrakar/gitpro
@@ -48,26 +48,38 @@ Install from [PyPI](https://pypi.org/project/gitpro/) with pipx.
 
 ```sh
 pipx install gitpro
-gitpro setup --write
+gitpro setup
 ```
 
-The wizard helps you choose identities, Git hosts and owners, existing SSH keys,
-and optional signing. **No TOML editing is needed for basic setup.** Review the
-configuration before saving; nothing is applied to Git or SSH yet.
-
-```sh
-gitpro plan              # see exactly what would change
-gitpro apply -y          # explicitly apply the reviewed changes
+Setup offers to look through your repos and proposes your identities. Accept,
+edit or answer the questions yourself; **no TOML editing is needed.** One
+preview shows everything, including the commit guard and, with Claude Code, its
+hook and MCP server. One yes applies it all. Setup never changes your repos.
+
+```mermaid
+flowchart LR
+  S["gitpro setup"] --> HC{"Config <br/>exists?"}
+  HC -->|no| L["Read your repos, <br/>SSH config and <br/>editor recents, <br/>if you agree"]
+  L --> Q["Propose <br/>identities; you <br/>accept or edit"]
+  Q --> I
+  HC -->|yes| I["Inspect config, <br/>Git and SSH files, <br/>keys, guard, <br/>agent hook, MCP"]
+  I -->|all current| OK["Nothing <br/>to do"]
+  I -->|something to do| PV["One preview, <br/>each part with <br/>its undo"]
+  PV --> ASK{"Apply <br/>all?"}
+  ASK -->|no| NONE["Nothing <br/>written"]
+  ASK -->|yes| AP["Write it, print <br/>the public keys <br/>to register"]
+  AP --> NX["Next: <br/>gitpro scan"]
 ```
 
-Then, inside a repository:
+Then:
 
 ```sh
-gitpro why               # see the expected identity and anything overriding it
+gitpro why               # inside a repository: the expected identity and anything overriding it
+gitpro scan              # repos that need a fix, with the command for each
 ```
 
-Already have a config? Run `gitpro setup --write` to add another identity without losing
-your existing settings or comments. Prefer editing files? The
+Already have a config? `gitpro setup` brings this machine up to date with it.
+`gitpro setup -n` only shows what is left to do. Prefer editing files? The
 [user guide](docs/guide.md#configuration) covers the full TOML format.
 
 ## What you get
@@ -79,20 +91,17 @@ your existing settings or comments. Prefer editing files? The
 
 Gitpro generates ordinary Git and SSH configuration; it needs no background
 service. Changes can be previewed, existing hand-written files are backed up,
-and key creation or uploads are never part of the setup wizard.
+and key uploads are never part of setup.
 
 ## Using VS Code?
 
-Run **gitpro: Set Up Identities** from the Command Palette to open the same wizard
-in a terminal. The extension also shows the current identity and helps find
-repository-level overrides. [Install the extension](vscode/README.md).
+The extension shows the current identity and helps find repository-level
+overrides. It runs the same commands as the terminal. [Install the extension](vscode/README.md).
 
 ## Go further when you need to
 
-For agents, [the versioned workflow](docs/agent-workflows.md) provides structured
-preflight, identity-scoped execution and durable idempotency for commits, pushes
-and GitHub PRs. Persistent changes use exact proposals, human approval by default,
-optional operator-scoped preauthorization, and recoverable apply. MCP execution is opt-in.
+AI agents get the same answers through the MCP server and the Claude Code hook:
+see [agent workflows](docs/agent-workflows.md).
 
 | I want to… | Start here |
 |---|---|
@@ -103,8 +112,14 @@ optional operator-scoped preauthorization, and recoverable apply. MCP execution
 | Look up a command or undo changes | [Command reference](docs/guide.md#commands) · [Undo](docs/guide.md#undo-everything) |
 | Troubleshoot or contribute | [Troubleshooting](docs/guide.md#troubleshooting) · [Development](docs/guide.md#development) |
 
-The detailed TOML, YAML and command examples live in the guide, not on the
-getting-started path.
+## Problems and questions
+
+Run `gitpro report` to draft an issue with the versions and a redacted
+`gitpro why`; it shows you the draft and opens nothing until you say yes.
+Or open an issue at [github.com/Yantrakar/gitpro/issues](https://github.com/Yantrakar/gitpro/issues).
+Report a security problem privately with `gitpro report --security`, as the
+[security policy](https://github.com/Yantrakar/gitpro/security/policy) describes,
+not in a public issue.
 
 ## License
 

{gitpro-0.3.3 → gitpro-0.4.0}/README.md

@@ -22,26 +22,38 @@ Install from [PyPI](https://pypi.org/project/gitpro/) with pipx.
 
 ```sh
 pipx install gitpro
-gitpro setup --write
+gitpro setup
 ```
 
-The wizard helps you choose identities, Git hosts and owners, existing SSH keys,
-and optional signing. **No TOML editing is needed for basic setup.** Review the
-configuration before saving; nothing is applied to Git or SSH yet.
-
-```sh
-gitpro plan              # see exactly what would change
-gitpro apply -y          # explicitly apply the reviewed changes
+Setup offers to look through your repos and proposes your identities. Accept,
+edit or answer the questions yourself; **no TOML editing is needed.** One
+preview shows everything, including the commit guard and, with Claude Code, its
+hook and MCP server. One yes applies it all. Setup never changes your repos.
+
+```mermaid
+flowchart LR
+  S["gitpro setup"] --> HC{"Config <br/>exists?"}
+  HC -->|no| L["Read your repos, <br/>SSH config and <br/>editor recents, <br/>if you agree"]
+  L --> Q["Propose <br/>identities; you <br/>accept or edit"]
+  Q --> I
+  HC -->|yes| I["Inspect config, <br/>Git and SSH files, <br/>keys, guard, <br/>agent hook, MCP"]
+  I -->|all current| OK["Nothing <br/>to do"]
+  I -->|something to do| PV["One preview, <br/>each part with <br/>its undo"]
+  PV --> ASK{"Apply <br/>all?"}
+  ASK -->|no| NONE["Nothing <br/>written"]
+  ASK -->|yes| AP["Write it, print <br/>the public keys <br/>to register"]
+  AP --> NX["Next: <br/>gitpro scan"]
 ```
 
-Then, inside a repository:
+Then:
 
 ```sh
-gitpro why               # see the expected identity and anything overriding it
+gitpro why               # inside a repository: the expected identity and anything overriding it
+gitpro scan              # repos that need a fix, with the command for each
 ```
 
-Already have a config? Run `gitpro setup --write` to add another identity without losing
-your existing settings or comments. Prefer editing files? The
+Already have a config? `gitpro setup` brings this machine up to date with it.
+`gitpro setup -n` only shows what is left to do. Prefer editing files? The
 [user guide](docs/guide.md#configuration) covers the full TOML format.
 
 ## What you get
@@ -53,20 +65,17 @@ your existing settings or comments. Prefer editing files? The
 
 Gitpro generates ordinary Git and SSH configuration; it needs no background
 service. Changes can be previewed, existing hand-written files are backed up,
-and key creation or uploads are never part of the setup wizard.
+and key uploads are never part of setup.
 
 ## Using VS Code?
 
-Run **gitpro: Set Up Identities** from the Command Palette to open the same wizard
-in a terminal. The extension also shows the current identity and helps find
-repository-level overrides. [Install the extension](vscode/README.md).
+The extension shows the current identity and helps find repository-level
+overrides. It runs the same commands as the terminal. [Install the extension](vscode/README.md).
 
 ## Go further when you need to
 
-For agents, [the versioned workflow](docs/agent-workflows.md) provides structured
-preflight, identity-scoped execution and durable idempotency for commits, pushes
-and GitHub PRs. Persistent changes use exact proposals, human approval by default,
-optional operator-scoped preauthorization, and recoverable apply. MCP execution is opt-in.
+AI agents get the same answers through the MCP server and the Claude Code hook:
+see [agent workflows](docs/agent-workflows.md).
 
 | I want to… | Start here |
 |---|---|
@@ -77,8 +86,14 @@ optional operator-scoped preauthorization, and recoverable apply. MCP execution
 | Look up a command or undo changes | [Command reference](docs/guide.md#commands) · [Undo](docs/guide.md#undo-everything) |
 | Troubleshoot or contribute | [Troubleshooting](docs/guide.md#troubleshooting) · [Development](docs/guide.md#development) |
 
-The detailed TOML, YAML and command examples live in the guide, not on the
-getting-started path.
+## Problems and questions
+
+Run `gitpro report` to draft an issue with the versions and a redacted
+`gitpro why`; it shows you the draft and opens nothing until you say yes.
+Or open an issue at [github.com/Yantrakar/gitpro/issues](https://github.com/Yantrakar/gitpro/issues).
+Report a security problem privately with `gitpro report --security`, as the
+[security policy](https://github.com/Yantrakar/gitpro/security/policy) describes,
+not in a public issue.
 
 ## License
 

{gitpro-0.3.3 → gitpro-0.4.0}/src/gitpro/__init__.py

@@ -1,4 +1,4 @@
 """Per-remote git identities generated from one TOML file (see cli.py)."""
 from __future__ import annotations
 
-__version__ = "0.3.3"
+__version__ = "0.4.0"

{gitpro-0.3.3 → gitpro-0.4.0}/src/gitpro/agents.py

@@ -34,7 +34,7 @@ MAX_SCAN = 1024 * 1024                  # the regex scan reads at most this much
 MAX_FOR = 20                            # `for x in w1 .. wN` with more words: the body is judged once, x unknown
 MAX_VALUE = 4096                        # a longer expanded $VAR value counts as unknown
 ALIAS_TIMEOUT = 3                       # seconds for the `git config --get alias.X` lookup on the hook path
-TRIGGERS = ("override", "pin_stale", "no_identity", "env_override")
+TRIGGERS = ("ambiguous", "override", "pin_stale", "no_identity", "env_override")
 SKIP_ENV = "GITPRO_SKIP"
 BYPASS_HELP = (f"{SKIP_ENV}=1 in the environment the agent starts with turns the check off for that session; "
                "[agents] hook = \"warn\" or \"off\" in the config changes it for good. The deny message never "
@@ -1113,6 +1113,9 @@ class Decision:
     cause: str
     fix: str
     repo: str
+    why: str = ""                        # the denial record's reason code (not `reason`: that is the text below)
+    codes: Tuple[str, ...] = ()          # problem codes of the repo's report
+    action: str = ""                     # the git subcommand or program
 
     @property
     def reason(self) -> str:
@@ -1312,10 +1315,15 @@ def _judge_one(c: Call, rep, cfg, own: set, pushed_to: Optional[str] = None) ->
     top = str(rep.repo)
     what = _what(c)
     commits = c.prog == "git" and c.sub != "push"
+    codes = tuple(p.code for p in rep.problems)
+    action = c.sub if c.prog == "git" else c.prog
+    why = ("no_identity" if exp.email is None else "committer" if c_bad else "author" if a_bad else "problem")
     if exp.email is None:
         from .resolve import redact_url
         url = redact_url(next(iter(rep.effective.remotes.values()), None)) or top
         headline = f"no identity matches this repo ({url}) and [default] has no email"
+    elif any(p.code == "ambiguous" for p in triggers):
+        headline = f"this {what} runs in a repo whose remotes belong to different identities"
     elif c_bad or a_bad:
         email, verb = (committer, "committed") if c_bad else (author, "authored")
         email = email or "(no email)"
@@ -1329,9 +1337,10 @@ def _judge_one(c: Call, rep, cfg, own: set, pushed_to: Optional[str] = None) ->
     if c_bad and c_src == "effective" and pushed_to and not triggers:
         # the repo's other problems were computed for this remote's identity; they would mislead here
         return Decision(headline, f"this repo's commits use {committer or '(no email)'} and {pushed_to} belongs "
-                                  f"to {exp.id or '[default]'}", f"gitpro why {shlex.quote(top)}", top)
+                                  f"to {exp.id or '[default]'}", f"gitpro why {shlex.quote(top)}", top,
+                        "pushed_to", codes, action)
     cause, fix = _cause(c, c_bad, c_src, committer, a_bad, a_src, author, rep, cfg, environ)
-    return Decision(headline, cause, fix, top)
+    return Decision(headline, cause, fix, top, why, codes, action)
 
 
 def _command_text(c: Call, limit: int = 200) -> str:
@@ -1447,6 +1456,7 @@ def _check(args: argparse.Namespace, text: str) -> int:
             sys.stdout.flush()
         print(msg, file=sys.stderr)
         return 0
+    _record_denial(args.agent, d)
     out, rc = adapter.deny(d)
     if out:
         sys.stdout.write(out + "\n")
@@ -1455,6 +1465,11 @@ def _check(args: argparse.Namespace, text: str) -> int:
     return rc
 
 
+def _record_denial(agent: str, d: Decision) -> None:
+    from . import incident              # lazy: stdlib only, but most checks never deny
+    incident.record_denial("agent-check", agent, d.action, d.why, d.codes)
+
+
 def _fail_open(func: Callable[[], int]) -> int:
     try:
         return func()
@@ -1463,9 +1478,18 @@ def _fail_open(func: Callable[[], int]) -> int:
     except _ArgError as e:
         return _fail_open_msg(str(e))
     except Exception as e:                 # fail open: never stop the agent
+        _record_crash(e)
         return _fail_open_msg(str(e) or type(e).__name__)
 
 
+def _record_crash(e: Exception) -> None:
+    try:
+        from . import incident
+        incident.record_crash("agent-check", e)
+    except Exception:                      # noqa: BLE001
+        pass
+
+
 def _fail_open_msg(msg: str) -> int:
     try:
         _warn(msg)
@@ -1790,11 +1814,31 @@ def _edit(args: argparse.Namespace, removing: bool) -> int:
         view.step("added .claude/settings.local.json to .git/info/exclude so it is not committed")
     view.ok(f"removed the gitpro hook from {shown}" if removing else
             f"installed; {title} picks it up on its next session")
-    restores = f"restores from {undo.tilde(res.backup)}" if res.backup else f"removes {shown}"
+    restores = f"restores from {undo.tilde(res.backup)}" if res.backup else f"removes {shown} unless it changed since"
     print(f"↩ undo: sh {undo.tilde(res.undo)}   ({restores})")
     return 0
 
 
+HOOK_AGENTS = ("claude", "cursor", "gemini")
+
+
+def plugin_enabled(home: Path) -> Optional[str]:
+    """The enabled gitpro plugin in ~/.claude/settings.json (it ships the hook and the MCP server), or None."""
+    t = target("claude", "user", home, None)
+    return _plugin(_read_lenient(t.path)) if t.path.is_file() else None
+
+
+def hook_change(agent: str, home: Path) -> Optional[str]:
+    """For gitpro setup: what `agent install --agent AGENT` would do at user scope ("create PATH" or
+    "update PATH"), or None when the hook is in place. ConfigError for a file gitpro must not edit."""
+    from . import undo
+    t = target(agent, "user", home, gitpro_path())
+    obj = _precheck(t.path, t, _snippet(t))
+    if obj is not None and add_hook(copy.deepcopy(obj), t) == obj:
+        return None
+    return f"{'update' if obj is not None else 'create'} {undo.tilde(t.path)}"
+
+
 def install(args: argparse.Namespace) -> int:
     """`gitpro agent install`."""
     return _edit(args, removing=False)

{gitpro-0.3.3 → gitpro-0.4.0}/src/gitpro/args.py

@@ -11,6 +11,8 @@ so both routes accept the same arguments without importing cli.
 from __future__ import annotations
 
 import argparse
+import os
+import re
 import shlex
 import subprocess
 import sys
@@ -41,7 +43,17 @@ def confirm() -> argparse.ArgumentParser:
     return p
 
 
+def dry_run(p: argparse.ArgumentParser) -> None:
+    """-n/--dry-run for a command that already previews without -y (pin, scan, audit; spec 22 R4)."""
+    p.add_argument("-n", "--dry-run", action="store_true", help="show only, change nothing (as without -y)")
+
+
 def preview_only(args: object) -> bool:
+    if getattr(args, "dry_run", False):
+        if getattr(args, "yes", False):
+            from .config import ConfigError
+            raise ConfigError("choose one: -n shows the change, -y makes it")
+        return True
     return not (getattr(args, "yes", False) or getattr(args, "write", False))
 
 
@@ -64,6 +76,40 @@ def fail(msg: str, args: object) -> int:
     return 2
 
 
+_CMD_RE = re.compile(r"^[a-z][a-z0-9-]{0,30}$")
+
+
+def _command_path(args: object) -> str:
+    """The command words of parsed args ("forge similar"), or "gitpro"."""
+    words = [getattr(args, "command", None)]
+    for key, val in sorted(vars(args).items()) if hasattr(args, "__dict__") else []:
+        if key != "command" and key.endswith(("_command", "_action")):
+            words.append(val)
+    return " ".join(w for w in words if isinstance(w, str) and _CMD_RE.match(w)) or "gitpro"
+
+
+def _internal_error(args: object, exc: Exception) -> int:
+    """An unexpected exception: write the crash record, print two lines (the traceback only with
+    GITPRO_DEBUG=1), exit 2."""
+    from . import incident
+    command = _command_path(args)
+    incident.record_crash(command, exc)
+    name = type(exc).__qualname__
+    if not re.match(r"^[A-Za-z_][A-Za-z0-9_.]{0,80}$", name):
+        name = "Exception"
+    if os.environ.get("GITPRO_DEBUG") == "1":
+        import traceback
+        traceback.print_exception(type(exc), exc, exc.__traceback__)
+    if getattr(args, "json", False):
+        from . import jsonout
+        jsonout.error(getattr(args, "command", None) or "gitpro", f"internal error ({name})")
+    else:
+        print(f"✗ internal error ({name}): this is a gitpro bug", file=sys.stderr)
+        print("→ draft a report with: gitpro report --crash", file=sys.stderr)
+    return 2
+
+
+
 def guarded(func: Callable[[argparse.Namespace], int], args: argparse.Namespace) -> int:
     """func(args) with gitpro's error handling: ConfigError, CalledProcessError, OSError and UnicodeError
     become exit 2 through fail(); Ctrl-C / EOF exit 130."""
@@ -80,3 +126,5 @@ def guarded(func: Callable[[argparse.Namespace], int], args: argparse.Namespace)
     except (KeyboardInterrupt, EOFError):
         print(file=sys.stderr)
         return 130
+    except Exception as e:   # noqa: BLE001 - a bug in gitpro: record it, say so, exit 2
+        return _internal_error(args, e)

{gitpro-0.3.3 → gitpro-0.4.0}/src/gitpro/audit.py

@@ -7,6 +7,7 @@ keeping every date; it never runs `rebase`, never touches pushed commits, the in
 """
 from __future__ import annotations
 
+import argparse
 import os
 import re
 import shlex
@@ -18,7 +19,7 @@ from pathlib import Path
 from typing import Dict, List, Optional, Sequence, Set, Tuple
 
 from . import config, jsonout, resolve, trailers, undo
-from .args import capability
+from .args import capability, dry_run, preview_only
 from .config import Config, ConfigError
 
 PROG = "gitpro"
@@ -31,7 +32,7 @@ FORMAT = "%H%x00%an%x00%ae%x00%cn%x00%ce%x00%cI%x00%P%x00%s%x00%(trailers:only,u
 # Options --range may contain besides revisions; anything else (--output=..., say) is refused.
 RANGE_OPTIONS = ("--not", "--all", "--remotes", "--branches", "--tags", "--first-parent", "--no-merges",
                  "--merges", "--since", "--until", "--after", "--before", "--max-count")
-_CAUSES = ("url_form", "override", "pin_stale", "global_override", "not_applied", "env_override")
+_CAUSES = ("ambiguous", "url_form", "override", "pin_stale", "global_override", "not_applied", "env_override")
 
 
 @dataclass
@@ -715,9 +716,11 @@ def _preview(data: dict, exp) -> List[str]:
 
 def cmd_audit(args) -> int:
     as_json = jsonout.wants_json(args)
+    args.rewrite = args.rewrite or getattr(args, "rewrite_flag", False)
     if args.rewrite and getattr(args, "agents", False):
         raise ConfigError("--rewrite needs the author audit; drop --agents")
-    if args.rewrite and as_json and not args.yes:
+    show_only = bool(args.rewrite and args.dry_run and preview_only(args))
+    if args.rewrite and as_json and not args.yes and not show_only:
         raise ConfigError("--json needs -y with --rewrite (there is no terminal to confirm on)")
     home = Path(args.home).expanduser().resolve()
     path, how = config.find(args.config, home)
@@ -746,6 +749,12 @@ def cmd_audit(args) -> int:
         print()
         print("\n".join(_preview(data, exp)))
     n = data["rewrite"]["commits"]
+    if show_only:
+        if as_json:
+            jsonout.emit("audit", dict(_public(data), dry_run=True))
+        else:
+            print(f"Dry run: nothing written. Rewrite the {n} unpushed commit{'s' * (n != 1)} with -y.")
+        return 0 if data["ok"] else 1
     if not _confirm(f"rewrite {n} unpushed commit{'s' * (n != 1)}?", args.yes):
         print("✗ aborted, nothing written")
         return 1
@@ -773,7 +782,7 @@ def cmd_audit(args) -> int:
 def register(sub, common, confirm) -> None:
     sp = sub.add_parser(
         "audit", parents=[common, confirm],
-        help="find commits made as the wrong identity or with an AI agent; fix unpushed ones with --rewrite",
+        help="find commits made as the wrong identity or with an AI agent; fix unpushed ones with --fix",
         description="Audit the history of a repo: commits whose committer (or your own other email as author) is "
                     "not the repo's identity, commits made with an AI agent (Co-Authored-By trailers, bot "
                     "emails) and the [*.trailers] policy. Default: the unpushed commits (as of the last fetch) "
@@ -792,9 +801,11 @@ def register(sub, common, confirm) -> None:
     w = sp.add_mutually_exclusive_group()
     w.add_argument("--agents", action="store_true", help="only the agent / trailer audit")
     w.add_argument("--authors", action="store_true", help="only the wrong-author audit")
-    sp.add_argument("--rewrite", action="store_true",
+    sp.add_argument("--fix", dest="rewrite", action="store_true",
                     help="fix the unpushed wrong-author commits (asks first; writes an undo script)")
+    sp.add_argument("--rewrite", dest="rewrite_flag", action="store_true", help=argparse.SUPPRESS)  # 0.4: --fix
+    dry_run(sp)
     sp.add_argument("--json", action="store_true", help="machine-readable output")
     sp.add_argument("-v", "--verbose", action="store_true", help="list every commit, not the first ten")
     sp.set_defaults(func=cmd_audit)
-    capability("audit", "audit.rewrite", "trailers")
+    capability("audit", "audit.rewrite", "audit.fix", "trailers")