gitpro 0.4.5__tar.gz → 0.4.6__tar.gz

{gitpro-0.4.5 → gitpro-0.4.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: gitpro
-Version: 0.4.5
+Version: 0.4.6
 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

{gitpro-0.4.5 → gitpro-0.4.6}/pyproject.toml

@@ -42,8 +42,11 @@ pattern = '\A(?P<version>\d+\.\d+\.\d+)'
 [tool.hatch.build.targets.wheel]
 packages = ["src/gitpro"]
 
+[tool.hatch.build.targets.wheel.force-include]
+"skills/gitpro/SKILL.md" = "gitpro/skill/SKILL.md"   # the one source of the skill; setup -n compares copies to it
+
 [tool.hatch.build.targets.sdist]
-include = ["/src/gitpro", "/README.md", "/LICENSE"]
+include = ["/src/gitpro", "/skills/gitpro/SKILL.md", "/README.md", "/LICENSE"]
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]

gitpro-0.4.6/skills/gitpro/SKILL.md

@@ -0,0 +1,359 @@
+---
+name: gitpro
+description: Set up and manage which git name, email, SSH key and commit signing each repo uses, chosen by the repo's remote URL, with the gitpro CLI. Use when the user wants separate work/personal git identities, a second GitHub or GitLab account, commit signing per account, asks why a commit has the wrong email, commits from a dev container, or before committing, pushing or opening a pull request for the user.
+license: MIT
+---
+
+# gitpro
+
+`gitpro` turns one TOML file into plain git and ssh config. Git then
+picks the identity for each repo from its remote URL. Nothing of the tool runs
+while git runs, unless the user installed the optional guard hooks.
+
+Docs: https://github.com/Yantrakar/gitpro/blob/main/docs/guide.md
+
+## Rules
+
+- **Never run `setup`, `uninstall`, `scan --fix`, `pin`, `clone` or `audit --fix`
+  without the user's explicit yes in this conversation.** Run `gitpro setup -n`
+  first, show the user what it says is still to do, and only after they
+  confirm run `gitpro setup -y`. Without a terminal, `setup` needs `-y` or `-n`
+  when there is something to change or to ask.
+- Edit only the TOML config. The files it generates (`~/.gitconfig-identities`,
+  `~/.gitconfig-<id>`, `~/.ssh/config.d/git-identities`, the marked blocks in
+  `~/.gitconfig` and `~/.ssh/config`) are overwritten on every `setup`.
+- Never read, print or copy private SSH keys. Public keys (`.pub`) are fine.
+- `gitpro setup` sets up the whole machine (config, SSH keys, Git and SSH
+  files, the guard, the hook and MCP server of the agents it covers, and the
+  gitpro skill copies that already exist) after one yes. It
+  offers to look through the user's repos and proposes identities from them
+  (it never reads private keys, shell history or forge accounts). The user runs
+  it in their terminal: the first run asks questions, and new keys ask for a
+  passphrase. Don't run it yourself without their explicit yes.
+- Don't invent owners, hosts or emails. Ask the user, or read them from the
+  remote URLs of their repos (`git remote -v`), or let `gitpro setup` find
+  them.
+- Before any `git commit`, `git push` or `gh pr create` for the user, follow
+  "Before you commit, push or open a pull request" below.
+- Never run `setup`, `guard install --repo`, `audit --fix`, `keys --upload` or
+  `clone` without an explicit yes. Always show the dry run first: `setup -n`,
+  `guard status`, `audit`, `clone --dry-run`. These commands ask on a
+  terminal and you have none, so pass `-y` only after the user said yes.
+- `devcontainer.json`, `.mcp.json` and `.claude/settings.json` are team
+  files. gitpro prints what to add; edit them only when the user owns the
+  repo and asks for it.
+- Never pass `--online`, `--history` or `--send-repo-names` unless the user
+  asks. Before an online command, tell the user what its first `online:` line
+  (or its "needs the network" message) says will be sent.
+- When gitpro crashes (`✗ internal error (…): this is a gitpro bug`) or blocks
+  a commit or push the user thinks it should not, offer `gitpro report`
+  (`--crash`, `--denial`; `--security` for a vulnerability). Show the user
+  `gitpro report --print` and never open or file it without their yes in
+  this conversation.
+- `gitpro env` prints the commands that fetch tokens, never the tokens. Do
+  not try to obtain token values, and never read `gh`/`glab` config files,
+  `.netrc` or `.git-credentials`.
+- Use `--json` when you need to read a result; plain output when you show it
+  to the user. With `--json`, a writing command also needs `-y`; without it,
+  `scan --fix --json` only previews, like `-n`.
+- A `***` in a URL gitpro prints is a password, token or secret query value
+  that it masked on purpose. The masking is for display only: do not try to
+  recover the value or paste the masked URL into a git command.
+- Commands and MCP tools marked deprecated still work in 0.4.x and are removed
+  in 0.5.0. Use their replacements (see the end of the Commands section).
+  `GITPRO_NO_DEPRECATION=1` silences the deprecation line.
+
+## Before you commit, push or open a pull request
+
+1. When you may need to commit, push or open a PR, run `gitpro --version`
+   early, before the work is done.
+2. If gitpro is missing, ask the user before installing it (`pipx install
+   gitpro`). If nobody can answer, record "blocked: gitpro missing" as a
+   blocker, keep doing the work that needs no commit, and do not write a done
+   or finish marker while a commit is blocked.
+3. Before each commit, run `gitpro why --json` in the repo (or call the `why`
+   MCP tool) with the real `--author`, `--committer` and `--message` you will
+   use. Read the repo's `problems` and `commit.problems`. Exit code 0 alone is
+   not a pass: `why` exits 0 for a wrong committer. An error or a missing
+   field is not a pass.
+4. `commit.would_block` is the agent hook's verdict (`[agents].hook`).
+   `commit.guard_would_block` is the Git guard's (`[guard].on_mismatch`). Stop
+   on a problem or on either being true, and show the user the `fix`.
+5. A repo with no remote still uses gitpro's `[default]` identity.
+6. Commit without gitpro only if all of these hold: the operator said so for
+   that repo, the repo has no remote, git's author and committer are the
+   identity the operator named, and you log it in the run log. Do not use an
+   environment variable for it.
+7. Push and PR always fail closed. `why` checks the identity, not the push
+   target, the account or the outgoing commits. If gitpro is missing or
+   `why` fails, do not push or open the PR.
+8. Never use `--no-verify`, `GITPRO_SKIP`, or turn off signing, unless the
+   user says so in this conversation.
+
+Needs Linux or macOS, git 2.36+, Python 3.9+, OpenSSH. gitpro is on PyPI.
+`gitpro --version --json` lists `capabilities`; check for one there (for
+example `why` or `mcp`) instead of comparing version numbers.
+
+## The config
+
+Path: `-c PATH`, else `$GITPRO_CONFIG`, else
+`~/.config/gitpro.toml`. `gitpro setup` finds the user's identities in their repos (or asks), writes
+the config and can add identities while preserving an existing config. The
+example config uses placeholder emails and hosts (`*.example`, `example.com`)
+that gitpro refuses until they are replaced.
+
+```toml
+[default]                          # repos no identity matches (all keys optional)
+name = "Jane Doe"
+email = "jane@personal.dev"
+ssh_key = "~/.ssh/id_ed25519"
+ssh_hosts = ["github.com"]         # ssh always uses ssh_key for these hosts
+sign = true                        # SSH-sign commits and tags
+
+[[identity]]
+id = "work-github"                 # short name; settings go to ~/.gitconfig-<id>
+name = "Jane Doe"
+email = "jane.doe@employer.com"
+host = "github.com"
+owners = ["janedoe-employer", "employer-org"]   # exact case, as in the remote URL
+ssh_key = "~/.ssh/id_ed25519_work"
+ssh_alias = "github-work"          # ssh Host that offers only ssh_key
+```
+
+- `id`, `name`, `email`, `host` are required for an identity.
+- `owners`: GitHub users/orgs or GitLab groups/subgroups from the URL path,
+  case-sensitive. Omit to match every repo on `host`.
+- A repo matches when any remote matches. Git applies the includes in file
+  order, so for one remote the later identity wins. When two remotes match
+  different identities, `why` and `scan` report the repo as ambiguous until
+  the user pins one (`gitpro pin --remote R`).
+- Two accounts on the same host need separate `ssh_key`s. Give the extra one an
+  `ssh_alias`, otherwise ssh can fall back to the default key and sign in as
+  the default account.
+- Other identity keys: `rewrite` (default true), `rewrite_https`, `ssh_user`,
+  `ssh_port`, `sign`, `file`, `gh_account`, `glab_account`, `clone_dir`,
+  `policy`, a `trailers` table (`co_authored_by`, `forbid_emails`), and extra
+  git settings under `[default.git.<section>]` / `[identity.git.<section>]`.
+- Optional tables: `[scan]` (`roots`, `exclude`, `stale_days`), `[guard]`
+  (`hooks`, `on_mismatch`, `chain_to`), `[clone]` (`dir`, `layout`),
+  `[forge]` (`online`, `similar`), `[agents]` (`hook`, `bot_emails`),
+  `[policy]` (`files`). The user guide's configuration section explains each.
+- Unknown keys are errors. Read the error message and fix the TOML.
+
+## Workflow for a change
+
+1. Read the config. Make the smallest edit that does what the user asked, with
+   their permission to edit configuration. Or let `gitpro setup --add PATH`
+   (run by the user) learn identities from their repos.
+2. `gitpro setup -n`. Show what it says is still to do and any `⚠` warning lines.
+3. On the user's yes: `gitpro setup -y`.
+4. If keys were added: `gitpro keys` prints each public key and the
+   account to register it with (twice on GitHub with `sign`: as an
+   authentication key and as a signing key). Test with `ssh -T git@<alias>`.
+5. Verify in a repo: `gitpro why <dir>`.
+
+## Other workflows
+
+- **"The repo commits as the wrong person"**: `gitpro why` → show its `→`
+  fix and run it on the user's yes → `gitpro why` again until it says
+  `✓ identity matches`. If the repo has two remotes for two identities, `why`
+  and `scan` say so; the user chooses with `gitpro pin --remote R`. If history
+  is already wrong: `gitpro audit` → show the list → on the user's yes,
+  `gitpro audit --fix -y` (it rewrites only unpushed commits, needs a clean
+  working tree and prints an `↩ undo:` line; tell the user to fetch first,
+  since "pushed" means as of the last fetch).
+- **"Set up a new machine"**: the user runs `pipx install gitpro` and
+  `gitpro setup` in their terminal (it offers to find their identities in
+  their repos) → `gitpro scan` (repos that need a fix) → `gitpro auth` (online:
+  say so first) if they want the forge checks.
+- **"Lost work before wiping or moving a machine"**: `gitpro scan --lost`
+  (offline, read-only). Suggest a `git fetch` first so "unpushed" is current.
+- **"Make the agent safe"**: `gitpro setup -n` shows which hooks and MCP
+  servers are in place, per agent (`agents` in `--json`). gitpro adds a hook
+  for Claude Code, Cursor and Gemini CLI, and an MCP server for those plus
+  Claude Desktop, GitHub Copilot CLI and opencode. For Codex it has
+  neither: `setup --agent codex` says so and `setup -n` exits 1. The Git
+  guard still checks its commits. Copilot CLI gets the MCP server only. "Installed"
+  means gitpro's entry is in the agent's config file, not that the agent
+  loaded it. Recommend the gitpro plugin (it brings the hook and the MCP
+  server) or `gitpro setup --agent claude`. The hook never grants anything; it
+  only denies with a reason.
+- **"The gitpro skill is out of date"**: `gitpro setup -n` lists installed
+  copies of this skill (`~/.claude/skills/gitpro`, `~/.copilot/skills/gitpro`,
+  `~/.agents/skills/gitpro`; links to one file count once) that differ from
+  the one in this gitpro. `gitpro setup -y`, after the user's yes, updates
+  those copies with a backup. It never creates a copy.
+- **"Clone a repo"**: `gitpro clone --dry-run <url>` → show the plan → on
+  the user's yes, `gitpro clone <url> -y`.
+- **"Our team has rules"**: `gitpro team`, then the `gitpro check --policy
+  FILE` command it ends with (or `gitpro check --repo <dir>` for one repo)
+  for the details, and `gitpro policy show` for the rules. `gitpro why`
+  also shows a repo's policy problems. Plain `gitpro check` does not look at
+  policies.
+- **"Set up the policy check in CI"**: GitHub, the Action in the user guide (`uses:
+  Yantrakar/gitpro@<ref>` with `fetch-depth: 0`); GitLab, the guide's
+  job. In CI, gitpro reads a policy file in the repo, and its
+  `allowed_signers`, as they are at the range base, so a pull request cannot
+  loosen the policy that judges it. A policy change in the PR takes effect
+  only once it is merged. Keep the range base on a protected branch (the
+  Action's default is), and recommend CODEOWNERS on `.gitpro-policy.toml`
+  and `allowed_signers`. These are team files: show the snippet and let the
+  user add it.
+
+## What `why` shows
+
+`gitpro why` prints the remotes, the identity the repo should use and why, the
+effective name and email, the SSH key and signing, and a `→` fix for most
+problems (a few, such as a policy that cannot be loaded, have a diagnostic and
+no fix). The text shows one origin per setting; `why --json` has a `settings`
+object with the `value`, `origin` and `scope` of each. `--committer EMAIL`,
+`--author EMAIL` and `--message TEXT` with `--json` fill the `commit` object:
+`problems`, `would_block` and `guard_would_block`. `why` exits 1 when the repo
+itself has a problem, and 2 on an error (with `--json`, an object with `error`).
+
+## Commands
+
+Every command has `--help`. `gitpro --help` lists `setup`, `why`, `scan`, `pin`,
+`clone`, `audit`, `env` and `uninstall`, then a "more" group.
+
+The same flags mean the same everywhere: `-y` does not ask,
+`--json` prints one JSON object, `-v` adds detail, a `PATH` names the repo or
+folder, `-c PATH` the config. `setup -n` shows only; `setup` asks once on a terminal. `pin`,
+`scan --fix` and `audit --fix` show a preview without `-y` (with `--json`,
+`scan --fix` previews unless `-y` is there). A preview never grants approval.
+
+| command | writes? | needs yes? | network |
+|---|---|---|---|
+| `why`, `prompt`, `completion`, `scan`, `scan --roots`, `scan --lost`, `audit`, `keys`, `keys --health`, `guard status`, `guard test`, `policy show`, `policy lint`, `team`, `env`, `setup -n`, `clone --dry-run` | no | no | no (`--online` is opt-in where present: ask first) |
+| `report` | no | **yes**, to open the form or send; `-y` answers it | with `--online` (`gh`): say so |
+| `guard check`, `agent-check`, `mcp` | no; git hooks, the agent hook and the MCP client call these | do not run them yourself | no |
+| `auth`, `forge repos`, `forge forks`, `forge email` | no | no, but say it goes online | **yes**, say so |
+| `setup` | yes: config, keys, Git and SSH files, guard, agents; previews first | **yes**, user runs it in their terminal; `-y` only after their yes | no |
+| `scan --fix`, `pin`, `pin --remove`, `uninstall`, `guard install --repo`, `guard uninstall`, `agent uninstall`, `mcp uninstall`, `audit --fix` | yes | **yes**, then `-y` | no |
+| `clone` | yes: a new directory | **yes**, then `-y` | yes: `git clone` |
+| `keys --upload`, `forge similar` | adds keys to the account / sends repo names | **yes** + `--online` (+ `--send-repo-names`) | **yes** |
+
+Deprecated in 0.4.0, removed in 0.5.0. They behave as in 0.3.4, print a line on
+stderr and are hidden from `--help`:
+
+| command | writes? | needs yes? | use instead |
+|---|---|---|---|
+| `init` | yes (deprecated): creates the example config | **yes**, then `-y` | `gitpro setup` |
+| `apply` | yes (deprecated) | **yes**, then `-y` | `gitpro setup -y` |
+| `unpin` | yes (deprecated) | **yes**, then `-y` | `gitpro pin --remove` |
+| `audit --rewrite` | yes (deprecated) | **yes**, then `-y` | `gitpro audit --fix` |
+| `guard install` | yes (deprecated without `--repo`) | **yes**, then `-y` | `gitpro setup` |
+| `agent install`, `mcp install` | yes (deprecated) | **yes**, then `-y` | `gitpro setup --agent NAME` |
+| `setup --write` | yes (deprecated) | **yes**, then `-y` | `gitpro setup -y` |
+| `scan --suggest` | no (deprecated) | no | `gitpro setup --add PATH` (the user runs it) |
+| `devcontainer --write` | yes (deprecated): **team file** | **yes**, then `-y` | VS Code "Set up devcontainer pin" |
+| `keys --generate` | yes (deprecated): creates keys, interactive | do not run: ask the user to | `gitpro setup` |
+| `plan`, plain `check`, `doctor`, `which`, `lost`, `discover`, `agent status`, `devcontainer`, `devcontainer status` | no (deprecated) | no | `setup -n`, `setup -n`, `setup -n` and `why`, `why --json`, `scan --lost`, `setup PATH`, `setup -n`, VS Code, VS Code |
+| `preflight`, `operation-status`, `operation-reconcile`, `change propose`, `change status` | no (deprecated) | no | none |
+| `run` | yes (deprecated) | **yes**, then `-y` | none |
+| `change approve`, `change apply`, `change recover` | yes (deprecated) | **yes** | none |
+
+Notes:
+
+- Plain `check` only exits 1 when `apply` would change something; it never
+  looks at policies. `check --repo DIR` checks the repo's identity against its
+  team policy, `check --policy FILE` checks every identity that uses FILE,
+  and `check --policy FILE --range A..B` checks commits (CI; the base's policy
+  judges). Only plain `check` is deprecated (use `setup -n`); the policy forms
+  stay and are listed under "more".
+- `setup -n` exits 0 when nothing is to do, 1 when something is (or when an
+  agent named with `--agent` cannot be covered), 2 on an error. `--json` has
+  `identities`, `pending`, `done`, `notes`, `agents` (per agent: `hook` and
+  `mcp`, each `installed`, `plugin`, `missing` or `unavailable`), `uncovered`
+  and `skills`; `ok` is false when `pending` or `uncovered` is not empty.
+- `team --online` shows `⚠` (never `✗`) when the forge did not answer; the
+  reason is on stderr and in `warnings`.
+- `scan --json`, `why --json` and the other `--json` forms print one JSON
+  object for you to read. `scan --lost` adds a `lost` object. `--lost` with
+  `--fix` is refused.
+- `scan --fix` keeps an override that is a repo's only identity. Without `-y`
+  it shows a preview (`scan --fix --json` too). With `-y` it prints the undo
+  script's path.
+- `pin --remote R` pins the identity that remote R's URL matches, for a repo
+  whose remotes match two identities. It also writes that identity's signing
+  and key settings. `pin --remove` with `--remote` is refused.
+- `uninstall` removes the Git and SSH files `setup` wrote and the global
+  guard hooks. It keeps the config and the keys. It does not remove agent
+  hooks, MCP registrations, per-repo hooks, pins, skill copies or
+  `devcontainer.json` entries; each of those has its own undo.
+- `env` output is meant for `eval "$(gitpro env)"` in the user's shell.
+- A deprecated command with `--json` has `"deprecated": {"removed_in": "0.5.0", "use": …}`
+  in its object and prints nothing on stderr.
+
+## MCP server
+
+The gitpro plugin (or `gitpro setup --agent NAME`) gives you an MCP server.
+Its tools have the commands' names and return the same JSON as the matching
+`--json` command:
+
+- `why`: the repo's identity. Takes `path`, `remote`, `author_email`,
+  `committer_email` and `message`. Its `settings` field is the effective
+  settings; its `commit` field has `problems`, `would_block` (the agent hook's
+  verdict) and `guard_would_block` (the Git guard's). On an error it returns
+  `isError` with the same object `why --json` prints (`error`, `config: null`,
+  and the repo fields when the path is a repo).
+- `setup`: the state of the machine (`setup -n --json`): identities and what is
+  still to do. Changes nothing.
+- `scan`: the repos and what needs a fix. With `lost: true` it adds the lost-work
+  checks.
+- `audit`: commits made as the wrong identity.
+- `env`: the commands that fetch the forge token, never a token.
+- `report`: a redacted bug report draft.
+
+Deprecated tools stay in the list in 0.4.x, with a description that starts
+`Deprecated, removed in 0.5.0; use <tool>.`, and are removed in 0.5.0
+(`apply_change`, `recover_change` and `run_operation` are listed only when the
+server runs with `--allow-execution`, as before):
+
+| deprecated tool | use |
+|---|---|
+| `which_identity` | `why` (its `settings`) |
+| `check_commit` | `why` with `committer_email`, `author_email`, `message` (its `commit`) |
+| `identities` | `setup` |
+| `lost` | `scan` with `lost: true` |
+| `env_for` | `env` |
+| `draft_report` | `report` |
+| `preflight`, `operation_status`, `reconcile_operation`, `propose_change`, `change_status`, `apply_change`, `recover_change`, `run_operation` | none |
+
+- Before committing, follow "Before you commit, push or open a pull request".
+  Pass `author_email`, `committer_email` and `message`.
+- Every default tool is read-only. Tools listed only with `--allow-execution`
+  are not.
+- A `fix` field is a command to propose to the user, not to run.
+
+## Troubleshooting
+
+- Not sure what is wrong: `gitpro setup -n` shows what is missing on the
+  machine, and `gitpro why` explains one repo.
+- Wrong or no identity: compare `why` output's remote URL with `host` and
+  `owners` (case!). A repo-level `user.email` overrides everything:
+  `gitpro scan <dir>` shows it, `gitpro scan --fix -y <dir>` removes it.
+- "Please tell me who you are": no identity matches and `[default]` has no
+  name/email. This is intended; add an identity or a default. A repo with no
+  remote uses `[default]`; `why` says "gitpro has no identity for this repo"
+  and whether git will use another email or refuse.
+- Inside a dev container (VS Code Dev Containers copy `~/.gitconfig` but not
+  its includes): on the host, run `gitpro pin` in the repo, or use VS Code's
+  "Set up devcontainer pin" so it happens on every start. An ordinary pin
+  does not pin signing or the SSH key; `pin --remote` writes both.
+- Push or clone signs in as the wrong account: the identity's key isn't
+  registered with that account, or it has no `ssh_alias` while the host is in
+  `[default].ssh_hosts`. `gitpro auth` (online) shows which account each
+  alias signs in as.
+- husky, lefthook or pre-commit: repos with their own `core.hooksPath` are
+  not covered by the global guard; suggest `gitpro guard install --repo <dir>`.
+- "A hook blocked me": read the `cause:` and `fix:` lines, show them to the
+  user and ask before running the fix.
+- "A hook printed `exited N; not blocking`": the guard failed open and the
+  commit went through. Run `gitpro why` in the repo and `gitpro setup -n`.
+- The agent hook does nothing: it runs `gitpro` from a plain `sh`, so gitpro
+  must be on that `PATH` (`command -v gitpro`).
+- A new agent shows `unavailable` in `setup -n`: gitpro has no hook or MCP
+  entry for it. That is not a gitpro failure; the Git guard still applies.
+- Something else, or a gitpro bug: `gitpro report --print` drafts a redacted
+  issue (versions and `why`); the user decides whether to open it.

{gitpro-0.4.5 → gitpro-0.4.6}/src/gitpro/VERSION

@@ -1,3 +1,4 @@
+0.4.6  2026-11-06  setup covers agents and skills, why gives the guard verdict
 0.4.5  2026-10-22  release: releasepro 0.2.2, plain short announcement
 0.4.4  2026-10-22  release: run by releasepro, notes from the changelog
 0.4.3  2026-10-21  release: gitpro.dev last, MCP Registry after PyPI only

{gitpro-0.4.5 → gitpro-0.4.6}/src/gitpro/cli.py

@@ -494,8 +494,8 @@ def cmd_scan(args) -> int:
     if args.lost and args.fix:
         raise config.ConfigError("--lost lists work only you can sort out, so it does not go with --fix; "
                                  "run gitpro scan --lost without --fix")
-    # -n shows the fix and changes nothing; --json without -y still writes (00-existing, known issue 2)
-    preview = bool(args.fix and args.dry_run and preview_only(args))
+    # -n shows the fix and changes nothing; so does --json without -y (spec 23 section 3.1)
+    preview = bool(args.fix and ((args.dry_run and preview_only(args)) or (args.json and not args.yes)))
     if preview:
         args.fix = False
     ask = args.fix and not args.yes and not args.json

{gitpro-0.4.5 → gitpro-0.4.6}/src/gitpro/commitcheck.py

@@ -100,9 +100,23 @@ def call_spec(fn: Callable, values: List[Tuple[str, object]]):
     return fn(*rest[:len(positional)], **kwargs)
 
 
+def guard_would_block(rep, cfg, committer_email: Optional[str], author_email: Optional[str],
+                      probs: List[dict]) -> bool:
+    """Would the Git guard refuse this commit? The identity check is guard.py's own (guard.commit_verdict).
+    A trailer problem counts because the commit-msg hook refuses it. Both follow [guard] on_mismatch, not
+    [agents].hook. Team-policy hooks are not evaluated."""
+    from . import guard
+    committer = committer_email or rep.effective.email.value or None
+    verdict = guard.commit_verdict(rep, cfg, committer, author_email or committer)
+    trailer = any(p["code"] == "trailer" for p in probs) and cfg.guard.on_mismatch == "block"
+    return bool(verdict["would_block"]) or trailer
+
+
 def judge(rep, cfg, *, committer_email: Optional[str] = None, author_email: Optional[str] = None,
           message: Optional[str] = None) -> dict:
-    """{would_block, mode, problems, reason, fix[, warnings]} for a commit in rep.repo."""
+    """{would_block, mode, problems, reason, fix, guard_would_block[, warnings]} for a commit in rep.repo.
+    would_block is the agent hook's verdict ([agents].hook); guard_would_block is the Git guard's
+    ([guard] on_mismatch)."""
     from . import resolve
     probs = identity_problems(rep, cfg, committer_email, author_email)
     probs += [_problem(p.code, p.message, resolve._shown_fix(p) or None) for p in rep.problems
@@ -112,7 +126,8 @@ def judge(rep, cfg, *, committer_email: Optional[str] = None, author_email: Opti
         probs += trailer_problems(rep.repo, rep, cfg, message, warnings)
     mode = cfg.agents.hook
     out = {"would_block": bool(probs) and mode == "block", "mode": mode, "problems": probs,
-           "reason": probs[0]["message"] if probs else None, "fix": probs[0]["fix"] if probs else None}
+           "reason": probs[0]["message"] if probs else None, "fix": probs[0]["fix"] if probs else None,
+           "guard_would_block": guard_would_block(rep, cfg, committer_email, author_email, probs)}
     if warnings:
         out["warnings"] = warnings
     return out

{gitpro-0.4.5 → gitpro-0.4.6}/src/gitpro/files.py

@@ -72,12 +72,14 @@ def show(changes: list[Change], diffs: bool) -> None:
                 (c.old or "").splitlines(True), (c.new or "").splitlines(True), f"a{c.path}", f"b{c.path}"))
 
 
-def _backup(path: Path, data: bytes | None = None) -> Path:
+def _backup(path: Path, data: bytes | None = None, into: Path | None = None) -> Path:
+    """A copy of path (O_EXCL, 0600) named <name>.bak.<stamp>, beside it or in the folder into."""
     stamp = time.strftime("%Y%m%d-%H%M%S")
     if data is None:
         data = path.read_bytes()
     for n in range(100):
-        bak = path.with_name(f"{path.name}.bak.{stamp}" + (f".{n}" if n else ""))
+        name = f"{path.name}.bak.{stamp}" + (f".{n}" if n else "")
+        bak = into / name if into is not None else path.with_name(name)
         try:
             fd = os.open(bak, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
         except FileExistsError:

{gitpro-0.4.5 → gitpro-0.4.6}/src/gitpro/guard.py

@@ -309,6 +309,23 @@ def identity_commit(ctx: Context) -> int:
     return 0
 
 
+def commit_verdict(rep, cfg, committer_email: Optional[str], author_email: Optional[str]) -> Dict[str, object]:
+    """What the pre-commit identity check (identity_commit above) decides for a commit in rep.repo, without
+    printing, recording a denial or running any process. {"refuses": the check returns BLOCK,
+    "would_block": it does and [guard] on_mismatch is "block", "mode": on_mismatch}. Team-policy entries
+    and the commit-msg trailer check are not run here. GITPRO_SKIP is not read."""
+    global _RECORD
+    ctx = Context("pre-commit", rep.repo, (), "", cfg, rep, committer_email or None, author_email or None,
+                  lambda line: None)
+    before, _RECORD = _RECORD, False
+    try:
+        refuses = identity_commit(ctx) == BLOCK
+    finally:
+        _RECORD = before
+    mode = cfg.guard.on_mismatch
+    return {"refuses": refuses, "would_block": refuses and mode == "block", "mode": mode}
+
+
 def _outgoing(repo: Path, stdin: str) -> List[Tuple[str, str, str, str]]:
     """(committer email, author email, short sha, subject) of every commit this push sends that no
     remote-tracking ref has, oldest last as git log prints them."""

{gitpro-0.4.5 → gitpro-0.4.6}/src/gitpro/mcp.py

@@ -46,7 +46,12 @@ PARSE_ERROR, INVALID_REQUEST, NO_METHOD, INVALID_PARAMS, INTERNAL_ERROR = -32700
 
 
 class ToolError(Exception):
-    """A gitpro error a tool reports as a result with isError (the server carries on)."""
+    """A gitpro error a tool reports as a result with isError (the server carries on). data, when given, is
+    the same error object the command's --json prints; the result carries it instead of the message."""
+
+    def __init__(self, message: str = "", data: Optional[dict] = None):
+        super().__init__(message)
+        self.data = data
 
 
 class RpcError(Exception):
@@ -152,7 +157,13 @@ def tool_why(args: dict, ctx: Ctx) -> dict:
     from . import resolve
     resolve.require_git()
     repo = _repo(args["path"])
-    cfg = ctx.config()
+    try:
+        cfg = ctx.config()
+    except ConfigError as e:
+        if ctx.cfg_path:      # an explicit config is an error, as `why -c PATH --json`
+            raise
+        # the object `why --json` prints when there is no usable config (shared construction)
+        raise ToolError(str(e), _envelope("why", {"ok": False, **resolve.why_error(e, repo)})) from None
     rep = resolve.compare(repo, cfg, remote=args.get("remote"), home=ctx.home)
     data = rep.to_json()
     data.pop("ok")
@@ -666,7 +677,7 @@ class Server:
             return self.failed(f"internal error: the tool stopped ({type(e).__name__}"
                                + (f" {code}" if code not in (None, 0) else "") + ")")
         except (ToolError, ConfigError, OSError, UnicodeError) as e:
-            return self.failed(str(e))
+            return self.failed_with(str(e), getattr(e, "data", None))
         except subprocess.CalledProcessError as e:
             cmd = e.cmd if isinstance(e.cmd, str) else shlex.join(str(c) for c in e.cmd)
             return self.failed(f"{cmd} failed ({e.returncode})")
@@ -696,6 +707,17 @@ class Server:
     def failed(message: str) -> dict:
         return {"content": [{"type": "text", "text": f"✗ {redact(message)}"}], "isError": True}
 
+    def failed_with(self, message: str, data: Optional[dict]) -> dict:
+        """An error result. With data, the command's own error object, as `--json` prints it."""
+        if data is None:
+            return self.failed(message)
+        obj = redact(data)
+        out = {"content": [{"type": "text", "text": json.dumps(obj, ensure_ascii=False, allow_nan=False)}],
+               "isError": True}
+        if self.version >= STRUCTURED_SINCE:
+            out["structuredContent"] = obj
+        return out
+
 
 def _error(mid: object, code: int, message: str) -> dict:
     return {"jsonrpc": "2.0", "id": mid, "error": {"code": code, "message": message}}
@@ -755,11 +777,12 @@ def cmd_mcp(args: argparse.Namespace) -> int:
 
 # ---------------------------------------------------------------- install / uninstall
 
-AGENTS = ("claude", "claude-desktop", "cursor", "gemini", "opencode")
+AGENTS = ("claude", "claude-desktop", "copilot", "cursor", "gemini", "opencode")
 ENTRY = {"type": "stdio", "command": "gitpro", "args": ["mcp"]}
 PLAIN_ENTRY = {"command": "gitpro", "args": ["mcp"]}               # formats that document no "type"
 OPENCODE_ENTRY = {"type": "local", "command": ["gitpro", "mcp"]}
-PROJECT_FILES = {"claude": ".mcp.json", "cursor": ".cursor/mcp.json"}
+COPILOT_ENTRY = {"type": "local", "command": "gitpro", "args": ["mcp"], "tools": ["*"]}   # "*": all the tools
+PROJECT_FILES = {"claude": ".mcp.json", "copilot": ".github/mcp.json", "cursor": ".cursor/mcp.json"}
 CLAUDE_ADD = ["claude", "mcp", "add", "--scope", "user", "--transport", "stdio", "gitpro", "--", "gitpro", "mcp"]
 CLAUDE_REMOVE = ["claude", "mcp", "remove", "--scope", "user", "gitpro"]
 
@@ -772,6 +795,8 @@ def _user_target(agent: str, home: Path) -> Tuple[Path, str, dict]:
     if agent == "claude-desktop":
         base = home / "Library/Application Support/Claude" if sys.platform == "darwin" else xdg / "Claude"
         return base / "claude_desktop_config.json", "mcpServers", PLAIN_ENTRY
+    if agent == "copilot":
+        return home / ".copilot/mcp-config.json", "mcpServers", COPILOT_ENTRY
     if agent == "cursor":
         return home / ".cursor/mcp.json", "mcpServers", ENTRY
     if agent == "gemini":
@@ -792,7 +817,7 @@ def _target(args: argparse.Namespace) -> Tuple[Path, str, dict]:
     top = resolve.is_repo(Path.cwd())
     if top is None:
         raise ConfigError(f"{Path.cwd()}: not a git repository (--scope project edits the repo's {rel})")
-    return top / rel, "mcpServers", ENTRY
+    return top / rel, "mcpServers", COPILOT_ENTRY if args.agent == "copilot" else ENTRY
 
 
 def _ours(value: object, entry: dict) -> bool:
@@ -1005,7 +1030,7 @@ def register(sub, common, confirm) -> None:
         a = actions.add_parser(name, parents=[confirm], help=text)
         a.add_argument("--agent", choices=AGENTS, default="claude", help="which assistant (default: claude)")
         a.add_argument("--scope", choices=("user", "project"), default="user",
-                       help="user config (default) or the repo's tracked file (claude, cursor; needs --write)")
+                       help="user config (default) or the repo's tracked file (claude, copilot, cursor; needs --write)")
         a.add_argument("--json", action="store_true", help="machine-readable output (needs -y)")
         if name == "install":
             a.add_argument("--force", action="store_true",

{gitpro-0.4.5 → gitpro-0.4.6}/src/gitpro/resolve.py

@@ -843,8 +843,11 @@ def compare(repo: Path, cfg: Config, *, remote: Optional[str] = None,
     who = _who(exp)
 
     if exp.email is None:
-        out.append(_p("no_identity", f"no identity for {redact_url(first_url) or top}",
-                      None, f"add an identity: gitpro setup --add {_word(str(top))}"))
+        if candidates:
+            fix = f"add an identity: gitpro setup --add {_word(str(top))}"
+        else:   # no remote url: no identity pattern can ever match, so only [default] applies
+            fix = f"add a name and email under [default] in {_tilde(str(cfg.path)) if cfg.path else 'the config'}"
+        out.append(_p("no_identity", f"no identity for {redact_url(first_url) or top}", None, fix))
 
     if exp.match.identity is None:
         for name, url in candidates:
@@ -1008,7 +1011,9 @@ def render_text(rep: Report, cfg: Config) -> str:
     if e.email:
         lines.append(f"  expected  {label}  {e.name or '(no name)'} <{e.email}>")
     else:
-        lines.append(f"  expected  {label}  no name/email in [default]; git will refuse to commit")
+        lines.append(f"  expected  {label}  gitpro has no identity for this repo (no name/email in [default]); "
+                     + (f"git will use {f.email.value} from {_shown_origin(f.email, top)}" if f.email.value
+                        else "git will refuse to commit"))
     lines.append(f"            {e.match.rule}")
     if f.email.value or f.name.value:
         src = f.email if f.email.value else f.name
@@ -1053,6 +1058,17 @@ def register(sub, common, confirm) -> None:
     capability("why", "why.config", "why.commit")
 
 
+def why_error(e: Exception, directory: Path) -> dict:
+    """The object `why --json` (and the MCP `why`) returns when there is no usable config: still an error,
+    but say what git does here (the extension's status bar needs it)."""
+    from . import cli
+    try:
+        data = cli.which_data(Path(directory))
+    except config.ConfigError:
+        data = {}                         # not a repo: the config error is the one to report
+    return {"error": str(e), "config": None, **data}
+
+
 def cmd_why(args) -> int:
     require_git()
     from . import cli, commitcheck
@@ -1064,12 +1080,7 @@ def cmd_why(args) -> int:
     except config.ConfigError as e:
         if not as_json or args.config:
             raise
-        # No usable config: still an error, but say what git does here (the extension's status bar needs it).
-        try:
-            data = cli.which_data(Path(args.dir))
-        except config.ConfigError:
-            data = {}                         # not a repo: the config error is the one to report
-        jsonout.emit("why", {"error": str(e), "config": None, **data}, ok=False)
+        jsonout.emit("why", why_error(e, Path(args.dir)), ok=False)
         return 2
     rep = compare(Path(args.dir), cfg, remote=args.remote, home=home)
     if as_json:

{gitpro-0.4.5 → gitpro-0.4.6}/src/gitpro/setup.py

@@ -22,9 +22,11 @@ from .config import ConfigError, check
 
 Snapshot = Optional[Tuple[bytes, os.stat_result]]
 # agents.INSTALL_CHOICES + mcp.AGENTS (a test keeps them in step), and none
-AGENTS = ("claude", "claude-desktop", "codex", "cursor", "gemini", "opencode", "none")
-TITLE = {"claude": "Claude Code", "claude-desktop": "Claude Desktop", "codex": "Codex", "cursor": "Cursor",
-         "gemini": "Gemini CLI", "opencode": "opencode"}
+AGENTS = ("claude", "claude-desktop", "codex", "copilot", "cursor", "gemini", "opencode", "none")
+TITLE = {"claude": "Claude Code", "claude-desktop": "Claude Desktop", "codex": "Codex",
+         "copilot": "GitHub Copilot CLI", "cursor": "Cursor", "gemini": "Gemini CLI", "opencode": "opencode"}
+# Agents that gitpro has no hook or MCP registration for, and why (shown when one is asked for by name).
+NO_COVERAGE = {"codex": "gitpro has no hook or MCP registration for Codex"}
 QUESTION = "Apply these changes?"
 LEARN = "Look through your repos to find your identities?"
 LEARN_BUDGET = 20.0    # seconds for inspecting the repos found
@@ -362,9 +364,14 @@ class Work:
     mcps: List[Tuple[str, str]] = field(default_factory=list)
     done: List[str] = field(default_factory=list)   # already in place
     notes: List[str] = field(default_factory=list)  # left alone, and why
+    coverage: List[dict] = field(default_factory=list)   # per agent: hook and MCP status (see inspect)
+    uncovered: List[str] = field(default_factory=list)  # agents asked for by name that gitpro cannot cover
+    skills: List[dict] = field(default_factory=list)    # installed gitpro skill copies: {"path","state"}
+    skill_stale: list = field(default_factory=list)     # skillcopy.Copy that differ from the bundled skill
+    skill_text: Optional[bytes] = None                  # the bundled skill
 
     def pending(self) -> bool:
-        return bool(self.config or self.keys or self.changes or self.hooks or self.mcps)
+        return bool(self.config or self.keys or self.changes or self.hooks or self.mcps or self.skill_stale)
 
 
 def _empty(cfg: config.Config) -> bool:
@@ -405,8 +412,35 @@ def _agents(args, home: Path) -> List[str]:
     return ["claude"] if (home / ".claude").is_dir() or shutil.which("claude") else []
 
 
-def inspect(cfg: config.Config, env, names: List[str]) -> Work:
-    """What the files, the guard and the agents still need; reads only."""
+def _skills(w: Work, home: Path) -> None:
+    """Which installed gitpro skill copies differ from the one bundled with this gitpro (spec 23 section 5).
+    Reads only. A copy that is not there is not reported: setup never creates one."""
+    from . import skillcopy
+    w.skill_text = skillcopy.bundled()
+    if w.skill_text is None:
+        w.notes.append("the gitpro skill is not bundled with this install; installed copies not checked")
+        return
+    for c in skillcopy.copies(home, w.skill_text):
+        w.skills.append({"path": str(c.path), "state": c.state})
+        if c.state == "differs":
+            w.skill_stale.append(c)
+        elif c.state == "unreadable":
+            w.notes.append(f"{c.path}: the gitpro skill is there but cannot be read; left alone")
+        else:
+            w.done.append(f"gitpro skill {undo_tilde(c.path)}")
+
+
+def undo_tilde(path: Path) -> str:
+    from . import undo
+    return undo.tilde(path)
+
+
+def inspect(cfg: config.Config, env, names: List[str], explicit: bool = False) -> Work:
+    """What the files, the guard and the agents still need; reads only. For each agent in names, w.coverage
+    has {"agent", "hook", "mcp"[, "reason"]}, each status one of "installed" (gitpro's entry is in the
+    agent's config file), "plugin" (a plugin that ships it is enabled), "missing" (setup would add it) or
+    "unavailable". None of these says the agent loaded it. With explicit (the user named the agents), an
+    agent with neither a hook nor an MCP server available goes to w.uncovered."""
     from . import agents, keys, mcp, plan
     w = Work()
     for k in keys.inventory(cfg.default, list(cfg.identities)):
@@ -418,6 +452,7 @@ def inspect(cfg: config.Config, env, names: List[str]) -> Work:
                            "setup does not create a key over it")
         else:
             w.keys.append(k)
+    _skills(w, env.home)
     w.guard, why = _guard(cfg, env)
     if why:
         w.notes.append(why)
@@ -430,22 +465,41 @@ def inspect(cfg: config.Config, env, names: List[str]) -> Work:
         title = TITLE[a]
         if a == "claude" and agents.plugin_enabled(env.home):
             w.done.append("Claude Code: the gitpro plugin provides the hook and the MCP server")
+            w.coverage.append({"agent": a, "hook": "plugin", "mcp": "plugin"})
             continue
-        parts = [("hook", agents.hook_change, w.hooks)] if a in agents.HOOK_AGENTS else []
-        parts += [("MCP server", mcp.install_change, w.mcps)] if a in mcp.AGENTS else []
-        if not parts:
-            w.notes.append(f"{title}: gitpro has no hook or MCP entry for it; the commit guard still checks "
-                           "its commits")
-        for what, change, todo in parts:
+        row = {"agent": a}
+        reasons: List[str] = []
+        for what, key, change, todo, known in (("hook", "hook", agents.hook_change, w.hooks, agents.HOOK_AGENTS),
+                                               ("MCP server", "mcp", mcp.install_change, w.mcps, mcp.AGENTS)):
+            if a not in known:
+                row[key] = "unavailable"
+                continue
             try:
                 line = change(a, env.home)
             except ConfigError as e:
+                row[key] = "unavailable"
+                reasons.append(f"{what} not set up: {e}")
                 w.notes.append(f"{title} {what} not set up: {e}")
                 continue
             if line:
+                row[key] = "missing"
                 todo.append((a, line))
             else:
+                row[key] = "installed"
                 w.done.append(f"{title} {what}")
+        if row["hook"] == "unavailable" and row["mcp"] == "unavailable":
+            why = NO_COVERAGE.get(a) or "; ".join(reasons) or f"gitpro has no hook or MCP entry for {title}"
+            reasons = [why]
+            if explicit:
+                w.uncovered.append(f"{title}: {why}; the commit guard still checks its commits")
+            else:
+                w.notes.append(f"{title}: {why}; the commit guard still checks its commits")
+        elif a not in agents.HOOK_AGENTS or a not in mcp.AGENTS:
+            reasons.append("gitpro has no " + ("hook" if a not in agents.HOOK_AGENTS else "MCP registration")
+                           + f" for {title}")
+        if reasons:
+            row["reason"] = "; ".join(reasons)
+        w.coverage.append(row)
     return w
 
 
@@ -474,6 +528,8 @@ def rows(w: Work, env, passphrase: bool) -> List[Tuple[str, str]]:
                               "for the right identity)"))
     rows += [(f"{TITLE[a]} hook", f"{line} (checks the git commands it runs)") for a, line in w.hooks]
     rows += [(f"{TITLE[a]} MCP", f"{line} (read-only identity tools)") for a, line in w.mcps]
+    rows += [("gitpro skill", f"update {undo.tilde(c.path)} to this gitpro's version (a backup is kept)")
+             for c in w.skill_stale]
     order = ["config", "SSH key", "Git, SSH", "guard"]
     rows.sort(key=lambda r: order.index(r[0]) if r[0] in order else len(order))   # stable: agents keep theirs
     return rows
@@ -497,6 +553,8 @@ def show(out, w: Work, env, passphrase: bool) -> None:
         out.print(Text("Already in place: " + "; ".join(w.done), style="dim"), soft_wrap=True)
     for n in w.notes:
         out.print(Text("⚠ " + n, style="yellow"), soft_wrap=True)
+    for n in w.uncovered:
+        out.print(Text("✗ " + n, style="red"), soft_wrap=True)
 
 
 def _apply_files(cfg: config.Config, env, guard: bool) -> None:
@@ -513,6 +571,34 @@ def _apply_files(cfg: config.Config, env, guard: bool) -> None:
     print(f"↩ undo: sh {undo.tilde(script)}")
 
 
+def _apply_skills(w: Work) -> int:
+    """Update the stale skill copies: each is written through its link (never replacing it), after a backup
+    in the state folder: a file beside SKILL.md would sit in the skills folder, which may be a synced
+    or committed store. Returns the number that failed."""
+    from . import files, undo, view
+    failed = 0
+    lines: List[str] = []
+    for c in w.skill_stale:
+        try:
+            current = c.path.read_bytes()
+            if c.old is None or current.decode("utf-8") != c.old:
+                raise OSError("it changed since it was checked")
+            into = undo.state_dir() / "skill-backups"
+            into.mkdir(mode=0o700, exist_ok=True)
+            bak = files._backup(c.path, current, into=into)
+            lines.append(f"cp -p {shlex.quote(str(bak))} {shlex.quote(str(c.path))}")
+            files.atomic_write(c.path, w.skill_text or b"", c.mode)
+        except (OSError, UnicodeDecodeError) as e:
+            failed += 1
+            view.error(f"{c.path}: skill not updated: {e}")
+            continue
+        view.ok(f"updated {undo.tilde(c.path)} (backup: {undo.tilde(bak)})")
+    if lines:
+        script = undo.write("setup", lines, what="gitpro skill copies")
+        print(f"↩ undo: sh {undo.tilde(script)}")
+    return failed
+
+
 def _identity_json(i, d) -> dict:
     return {"id": i.id, "name": i.name, "email": i.email, "host": i.host, "owners": list(i.owners),
             "ssh_alias": i.ssh_alias, "ssh_key": i.ssh_key, "gh_account": i.gh_account,
@@ -529,12 +615,12 @@ def state(args, home: Path, path: Path, cfg: Optional[config.Config], names: Lis
         todo = [{"group": "config", "what": f"no identities in {undo.tilde(path)} yet: run gitpro setup in a terminal"}]
         if args.json:
             jsonout.emit("setup", {"dry_run": True, "config": str(path), "identities": [], "default": None,
-                                   "pending": todo, "done": [], "notes": []}, ok=False)
+                                   "pending": todo, "done": [], "notes": [], "agents": [], "uncovered": [], "skills": []}, ok=False)
         else:
             print(f"Config: {path}")
             view.warn(todo[0]["what"])
         return 1
-    w = inspect(cfg, env, names)
+    w = inspect(cfg, env, names, explicit=bool(args.agent))
     pending = [{"group": g, "what": what} for g, what in rows(w, env, passphrase=not args.no_passphrase)]
     warnings = list(lint.warnings(cfg.default, list(cfg.identities), env))
     if args.json:
@@ -544,8 +630,9 @@ def state(args, home: Path, path: Path, cfg: Optional[config.Config], names: Lis
             "identities": [_identity_json(i, d) for i in cfg.identities],
             "default": {"name": d.name, "email": d.email, "gh_account": d.gh_account, "glab_account": d.glab_account,
                         "clone_dir": d.clone_dir, "sign": d.sign},
-            "pending": pending, "done": w.done, "notes": w.notes + warnings}, ok=not pending)
-        return 1 if pending else 0
+            "pending": pending, "done": w.done, "notes": w.notes + warnings, "agents": w.coverage,
+            "uncovered": w.uncovered, "skills": w.skills}, ok=not (pending or w.uncovered))
+        return 1 if pending or w.uncovered else 0
     out = view.console()
     out.print(Text(f"Config: {cfg.path}"))
     for identity in cfg.identities:
@@ -561,6 +648,8 @@ def state(args, home: Path, path: Path, cfg: Optional[config.Config], names: Lis
     if pending:
         view.step("to do it: gitpro setup")
         return 1
+    if w.uncovered:
+        return 1
     view.ok("this machine is set up; nothing to change")
     return 0
 
@@ -619,14 +708,14 @@ def cmd_setup(args) -> int:
             out.print(Syntax(text[len(original):] if added else text, "toml", word_wrap=True))
 
     env = plan.Env(home)
-    w = inspect(cfg, env, names)
+    w = inspect(cfg, env, names, explicit=bool(args.agent))
     if text != original:
         w.config = (f"create {undo.tilde(path)}" if before is None else
                     f"update {undo.tilde(path)} (a backup is kept)")
     show(out, w, env, passphrase=not args.no_passphrase)
     failed = 0
     if not w.pending():
-        view.ok("this machine is set up; nothing to change")
+        view.ok("nothing to change" if w.uncovered else "this machine is set up; nothing to change")
     else:
         out.print(Text("Repos are not changed: 'gitpro scan' lists the ones that need a fix.", style="dim"))
         check(not w.keys or args.no_passphrase or tty,
@@ -656,8 +745,9 @@ def cmd_setup(args) -> int:
         for a, _ in w.mcps:
             failed += mcp.cmd_install(argparse.Namespace(
                 agent=a, scope="user", home=home, json=False, yes=True, write=True, force=False)) != 0
+        failed += _apply_skills(w)
         if failed:
-            view.error("an agent step failed (above); run gitpro setup again after fixing it")
+            view.error("a step failed (above); run gitpro setup again after fixing it")
     for msg in lint.warnings(cfg.default, list(cfg.identities), env):
         view.warn(msg)
     inv = keys.inventory(cfg.default, list(cfg.identities))
@@ -665,4 +755,4 @@ def cmd_setup(args) -> int:
         out.print()
         keys.report(inv, env.expand)
     view.step("check your repos: gitpro scan (it changes nothing; it shows each fix)")
-    return 1 if failed else 0
+    return 1 if failed or w.uncovered else 0

gitpro-0.4.6/src/gitpro/skillcopy.py

@@ -0,0 +1,65 @@
+"""The gitpro skill that ships inside the package, and the copies of it that agents already have.
+
+`setup -n` reports an installed copy that differs from the bundled one; `setup -y` updates the copies that
+exist and never creates one (spec 23 section 5). Standard library only."""
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from importlib import resources
+from pathlib import Path
+from typing import List, Optional
+
+# Where agents look for a user-level skill, relative to the home folder. ~/.claude/skills and
+# ~/.copilot/skills are often links to ~/.agents/skills: one physical file counts once.
+LOCATIONS = (".claude/skills/gitpro", ".copilot/skills/gitpro", ".agents/skills/gitpro")
+NAME = "SKILL.md"
+PACKAGED = "skill/SKILL.md"          # inside the wheel (pyproject force-include)
+
+
+def bundled() -> Optional[bytes]:
+    """The skill of this gitpro: the packaged copy, else (a source checkout) skills/gitpro/SKILL.md."""
+    try:
+        return resources.files("gitpro").joinpath(PACKAGED).read_bytes()
+    except (OSError, ModuleNotFoundError):
+        pass
+    try:
+        return (Path(__file__).resolve().parents[2] / "skills" / "gitpro" / NAME).read_bytes()
+    except OSError:
+        return None
+
+
+@dataclass
+class Copy:
+    path: Path                                   # the physical file (symlinks resolved)
+    locations: List[Path] = field(default_factory=list)   # the paths under home that lead to it
+    state: str = "current"                       # current | differs | unreadable
+    old: Optional[str] = None                    # its text, when it differs
+    mode: int = 0o644
+
+
+def copies(home: Path, want: Optional[bytes]) -> List[Copy]:
+    """The installed copies under home, each physical file once, in LOCATIONS order. A location with no
+    SKILL.md (or a dangling link) is not a copy. Reads only."""
+    found: dict = {}
+    for loc in LOCATIONS:
+        link = home / loc / NAME
+        try:
+            if not link.is_file():
+                continue
+            real = Path(os.path.realpath(link))
+        except OSError:
+            continue
+        c = found.get(real)
+        if c is None:
+            c = found[real] = Copy(real)
+            try:
+                data = real.read_bytes()
+                c.mode = real.stat().st_mode & 0o777
+                if want is not None and data != want:
+                    c.state = "differs"
+                    c.old = data.decode("utf-8")
+            except (OSError, UnicodeDecodeError):
+                c.state = "unreadable"
+        c.locations.append(link)
+    return list(found.values())