gitwise-cli 0.35.1__tar.gz → 0.36.1__tar.gz

{gitwise_cli-0.35.1 → gitwise_cli-0.36.1}/CHANGELOG.md

@@ -3,6 +3,18 @@
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## v0.36.1 (2026-07-22)
+
+### Fix
+
+- **schema**: align output contracts after review
+
+## v0.36.0 (2026-07-22)
+
+### Fix
+
+- remove unimplemented clean refs contract
+
 ## v0.35.1 (2026-07-22)
 
 ### Fix

{gitwise_cli-0.35.1 → gitwise_cli-0.36.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gitwise-cli
-Version: 0.35.1
+Version: 0.36.1
 Summary: Python CLI for optimizing git workflows and Claude Code integration
 Project-URL: Homepage, https://github.com/drzioner/gitwise
 Project-URL: Repository, https://github.com/drzioner/gitwise
@@ -44,21 +44,20 @@ Python CLI for optimized Git workflows and coding agents integration.
 [![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
 [![Docs: EN/ES](https://img.shields.io/badge/docs-EN%20%7C%20ES-0A7EA4)](docs/README.md)
 
-gitwise addresses three daily pain points:
-
-1. AI context bloat from raw `git diff`
-2. Slow repositories without modern Git maintenance settings
-3. Unsafe commit flows that bypass GPG signing rules
+gitwise gives coding agents bounded repository context, isolated branch workflows,
+and safe commit paths without hiding the underlying Git operations. Every command
+supports machine-readable JSON, and destructive operations expose dry-run or
+confirmation gates.
 
 ## Requirements
 
 - Python >= 3.10
 - git >= 2.29
-- macOS or Linux
+- macOS, Linux, or Windows
 
 ## Install
 
-Pick one:
+Choose the channel you already trust:
 
 **Homebrew** (macOS/Linux, recommended if you already use [Homebrew](https://brew.sh)):
 
@@ -68,7 +67,7 @@ brew install drzioner/tap/gitwise
 
 Update later with `brew upgrade gitwise`. Uninstall with `brew uninstall gitwise`.
 
-**curl | bash** (auto-installs `uv` if missing, no package manager required):
+**Installer script** (auto-installs `uv` if needed):
 
 ```bash
 curl -fsSL https://raw.githubusercontent.com/drzioner/gitwise/main/install.sh | bash
@@ -80,7 +79,13 @@ curl -fsSL https://raw.githubusercontent.com/drzioner/gitwise/main/install.sh |
 uv tool install gitwise-cli
 ```
 
-**From source** (development only):
+**Windows PowerShell** (PowerShell 5.1+):
+
+```powershell
+irm https://raw.githubusercontent.com/drzioner/gitwise/main/install.ps1 | iex
+```
+
+**From source** (contributors only):
 
 ```bash
 git clone https://github.com/drzioner/gitwise.git
@@ -89,20 +94,12 @@ uv sync
 uv run python -m gitwise doctor
 ```
 
-**Windows** (PowerShell 5.1+, auto-installs `uv` if missing):
-
-```powershell
-irm https://raw.githubusercontent.com/drzioner/gitwise/main/install.ps1 | iex
-```
-
-For a version-pinned install (e.g. for reproducible setups), see `Get-Help .\install.ps1 -Detailed` after download.
-
-Update an existing installation:
+Update through the same channel used to install:
 
 ```bash
 brew upgrade gitwise                   # if installed via Homebrew (macOS/Linux)
 uv tool upgrade gitwise-cli            # if installed via uv (any OS)
-# or re-run the curl | bash installer, which always pulls latest
+# or rerun the installer script
 ```
 
 Uninstall:
@@ -112,7 +109,7 @@ brew uninstall gitwise                 # if installed via Homebrew
 uv tool uninstall gitwise-cli          # if installed via uv (any OS)
 ```
 
-## Quick Start
+## Quick start
 
 ```bash
 gitwise doctor
@@ -121,28 +118,128 @@ gitwise setup-agents --local --dry-run
 gitwise summarize
 ```
 
-## Most Used Commands
+The first three commands inspect or plan changes. Add `--yes` only after reviewing
+the plan.
+
+## Five workflows
+
+### 1. Prepare a repository
+
+Check the environment, preview modern Git defaults, and install the canonical
+agent layout:
+
+```bash
+gitwise doctor --json
+gitwise setup --dry-run
+gitwise setup --yes
+gitwise setup-agents --local --dry-run
+gitwise setup-agents --local --yes
+```
+
+`setup` and `setup-agents` do not change `commit.gpgsign` or `user.signingkey`.
+
+### 2. Give an agent bounded context
+
+Use structured summaries instead of feeding an agent an unbounded raw diff:
+
+```bash
+gitwise context --json
+gitwise context --max-entries 50 --json
+gitwise summarize --json
+gitwise diff --stat --json
+```
+
+`context --json` defaults to 100 tree entries and reports `tree_total` plus
+`tree_truncated` when it omits entries.
+
+### 3. Isolate agent work
+
+Create a sibling worktree for a branch and use the path printed by the command:
+
+```bash
+gitwise worktree new feature/agent-task
+gitwise worktree list --json
+```
+
+Use `gitwise worktree remove feature/agent-task --dry-run` before removal.
+
+### 4. Review and commit safely
+
+Inspect staged changes, scan for likely secrets, then create a conventional,
+GPG-signed commit through the repository's Git configuration:
+
+```bash
+gitwise diff --staged --scan-secrets
+gitwise commit -m "fix: handle empty configuration"
+```
+
+gitwise blocks known signing and hook bypasses in generated agent rules. It does
+not create or replace signing keys.
+
+### 5. Maintain the repo and check a PR
+
+Keep maintenance explicit and inspect GitHub state without changing it:
+
+```bash
+gitwise audit --quick
+gitwise clean --branches --dry-run
+gitwise optimize --dry-run
+gitwise pr checks
+gitwise pr create --fill
+```
+
+`pr` delegates GitHub operations to `gh`; authenticate `gh` before using it.
+
+## Core commands
 
 | Command | Purpose |
 |---|---|
-| `gitwise doctor` | Check Python, git, platform, optional tools |
-| `gitwise setup` | Apply modern Git defaults safely |
-| `gitwise setup-agents` | Install canonical agents layout + optional provider config |
-| `gitwise audit` | Detect stale branches, graph/cache gaps, large blobs |
-| `gitwise summarize` | Compact context for humans and AI |
-| `gitwise diff` | Focused changed-file view (`--stat`, `--staged`, `--patch`) |
-| `gitwise worktree` | Create and clean worktree-based branch setups |
-| `gitwise status` | Enhanced status with staged/unstaged and ahead/behind |
-| `gitwise commands --json` | List subcommands with aliases and metadata |
-| `gitwise schema <command> --json` | Return versioned JSON Schema for command inputs |
-| `gitwise completions <shell>` | Generate shell completion scripts (bash/zsh/fish/powershell) |
-| `gitwise pr` | List/check/view PRs via GitHub CLI |
-
-For all commands, examples, aliases, and JSON usage, see:
+| `setup-agents` | Install the canonical multi-agent layout and provider templates |
+| `worktree` | Isolate branch work in sibling directories |
+| `summarize` | Produce compact status, log, and optional diff context |
+| `context` | Produce bounded repository context with truncation metadata |
+| `diff` | Inspect focused, staged, statistical, or patch output |
+| `commit` | Guard and create conventional commits |
+| `audit` | Diagnose stale branches, repository structure, and maintenance gaps |
+
+Support commands such as `doctor`, `setup`, `status`, `clean`, `optimize`, `pr`,
+`commands`, and `schema` serve those workflows. For all 30 commands, aliases,
+flags, and examples, see:
 
 - [Command reference (English)](docs/reference/commands.md)
 - [Referencia de comandos (Español)](docs/es/reference/commands.md)
 
+## JSON contract for agents
+
+Global machine flags work before or after the subcommand:
+
+```bash
+gitwise --json status
+gitwise status --json
+gitwise commands --json
+gitwise schema diff --json
+```
+
+Most JSON commands use the standard v3 envelope:
+
+```json
+{"v":3,"ok":true,"command":"status","data":{},"hints":[],"errors":[]}
+```
+
+Use `command` and stable error `code` values for branching. Treat `data` as the
+command-specific payload. `setup-agents` retains versioned compatibility fields;
+inspect its current contract with `gitwise schema setup-agents --json`.
+
+## Safety model
+
+- Git subprocesses scrub executable/config injection variables and use explicit timeouts.
+- Destructive batch commands require confirmation; JSON mode returns an explicit gate.
+- `diff --scan-secrets` and `commit` detect high-confidence credential patterns.
+- setup-agents symlink creation is sandboxed to the target repository.
+- CI runs ruff, basedpyright, pytest with a 75% coverage floor, pip-audit, and shellcheck.
+
+See [Security Policy](SECURITY.md) for vulnerability reporting.
+
 ## Documentation
 
 - [Documentation index (English)](docs/README.md)
@@ -156,13 +253,6 @@ For all commands, examples, aliases, and JSON usage, see:
 - [Git conventions](CONVENTIONS.md)
 - [Convenciones Git](CONVENTIONS.es.md)
 
-## GPG and Safety Model
-
-`setup` and `setup-agents` never modify `commit.gpgsign` or `user.signingkey`.
-
-- Git layer: `setup` manages hooks safely (`--hooks-mode preserve|native|legacy|skip`) to validate signing key availability and conventional commits.
-- Agent layer: deny-rules block `--no-gpg-sign`, `--no-verify`, and `-c commit.gpgsign=false`.
-
 ## Environment Variables
 
 | Variable | Description |
@@ -203,7 +293,11 @@ Completion covers subcommands as the first token and per-command flags
 
 ## Demo
 
-[![asciicast](https://asciinema.org/a/6tm4TnYMygEQT7ef.svg)](https://asciinema.org/a/6tm4TnYMygEQT7ef)
+Run the non-destructive current demo from a Git repository:
+
+```bash
+bash demo/script.sh
+```
 
 ## License
 

gitwise_cli-0.36.1/README.md

@@ -0,0 +1,271 @@
+# gitwise
+
+[English](README.md) | [Español](README.es.md)
+
+Python CLI for optimized Git workflows and coding agents integration.
+
+[![CI](https://github.com/drzioner/gitwise/actions/workflows/ci.yml/badge.svg)](https://github.com/drzioner/gitwise/actions/workflows/ci.yml)
+[![Coverage](https://codecov.io/gh/drzioner/gitwise/graph/badge.svg)](https://codecov.io/gh/drzioner/gitwise)
+[![Version](https://img.shields.io/github/v/release/drzioner/gitwise?display_name=tag)](https://github.com/drzioner/gitwise/releases)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
+[![Docs: EN/ES](https://img.shields.io/badge/docs-EN%20%7C%20ES-0A7EA4)](docs/README.md)
+
+gitwise gives coding agents bounded repository context, isolated branch workflows,
+and safe commit paths without hiding the underlying Git operations. Every command
+supports machine-readable JSON, and destructive operations expose dry-run or
+confirmation gates.
+
+## Requirements
+
+- Python >= 3.10
+- git >= 2.29
+- macOS, Linux, or Windows
+
+## Install
+
+Choose the channel you already trust:
+
+**Homebrew** (macOS/Linux, recommended if you already use [Homebrew](https://brew.sh)):
+
+```bash
+brew install drzioner/tap/gitwise
+```
+
+Update later with `brew upgrade gitwise`. Uninstall with `brew uninstall gitwise`.
+
+**Installer script** (auto-installs `uv` if needed):
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/drzioner/gitwise/main/install.sh | bash
+```
+
+**uv** (if you already use [uv](https://docs.astral.sh/uv/)):
+
+```bash
+uv tool install gitwise-cli
+```
+
+**Windows PowerShell** (PowerShell 5.1+):
+
+```powershell
+irm https://raw.githubusercontent.com/drzioner/gitwise/main/install.ps1 | iex
+```
+
+**From source** (contributors only):
+
+```bash
+git clone https://github.com/drzioner/gitwise.git
+cd gitwise
+uv sync
+uv run python -m gitwise doctor
+```
+
+Update through the same channel used to install:
+
+```bash
+brew upgrade gitwise                   # if installed via Homebrew (macOS/Linux)
+uv tool upgrade gitwise-cli            # if installed via uv (any OS)
+# or rerun the installer script
+```
+
+Uninstall:
+
+```bash
+brew uninstall gitwise                 # if installed via Homebrew
+uv tool uninstall gitwise-cli          # if installed via uv (any OS)
+```
+
+## Quick start
+
+```bash
+gitwise doctor
+gitwise setup --dry-run
+gitwise setup-agents --local --dry-run
+gitwise summarize
+```
+
+The first three commands inspect or plan changes. Add `--yes` only after reviewing
+the plan.
+
+## Five workflows
+
+### 1. Prepare a repository
+
+Check the environment, preview modern Git defaults, and install the canonical
+agent layout:
+
+```bash
+gitwise doctor --json
+gitwise setup --dry-run
+gitwise setup --yes
+gitwise setup-agents --local --dry-run
+gitwise setup-agents --local --yes
+```
+
+`setup` and `setup-agents` do not change `commit.gpgsign` or `user.signingkey`.
+
+### 2. Give an agent bounded context
+
+Use structured summaries instead of feeding an agent an unbounded raw diff:
+
+```bash
+gitwise context --json
+gitwise context --max-entries 50 --json
+gitwise summarize --json
+gitwise diff --stat --json
+```
+
+`context --json` defaults to 100 tree entries and reports `tree_total` plus
+`tree_truncated` when it omits entries.
+
+### 3. Isolate agent work
+
+Create a sibling worktree for a branch and use the path printed by the command:
+
+```bash
+gitwise worktree new feature/agent-task
+gitwise worktree list --json
+```
+
+Use `gitwise worktree remove feature/agent-task --dry-run` before removal.
+
+### 4. Review and commit safely
+
+Inspect staged changes, scan for likely secrets, then create a conventional,
+GPG-signed commit through the repository's Git configuration:
+
+```bash
+gitwise diff --staged --scan-secrets
+gitwise commit -m "fix: handle empty configuration"
+```
+
+gitwise blocks known signing and hook bypasses in generated agent rules. It does
+not create or replace signing keys.
+
+### 5. Maintain the repo and check a PR
+
+Keep maintenance explicit and inspect GitHub state without changing it:
+
+```bash
+gitwise audit --quick
+gitwise clean --branches --dry-run
+gitwise optimize --dry-run
+gitwise pr checks
+gitwise pr create --fill
+```
+
+`pr` delegates GitHub operations to `gh`; authenticate `gh` before using it.
+
+## Core commands
+
+| Command | Purpose |
+|---|---|
+| `setup-agents` | Install the canonical multi-agent layout and provider templates |
+| `worktree` | Isolate branch work in sibling directories |
+| `summarize` | Produce compact status, log, and optional diff context |
+| `context` | Produce bounded repository context with truncation metadata |
+| `diff` | Inspect focused, staged, statistical, or patch output |
+| `commit` | Guard and create conventional commits |
+| `audit` | Diagnose stale branches, repository structure, and maintenance gaps |
+
+Support commands such as `doctor`, `setup`, `status`, `clean`, `optimize`, `pr`,
+`commands`, and `schema` serve those workflows. For all 30 commands, aliases,
+flags, and examples, see:
+
+- [Command reference (English)](docs/reference/commands.md)
+- [Referencia de comandos (Español)](docs/es/reference/commands.md)
+
+## JSON contract for agents
+
+Global machine flags work before or after the subcommand:
+
+```bash
+gitwise --json status
+gitwise status --json
+gitwise commands --json
+gitwise schema diff --json
+```
+
+Most JSON commands use the standard v3 envelope:
+
+```json
+{"v":3,"ok":true,"command":"status","data":{},"hints":[],"errors":[]}
+```
+
+Use `command` and stable error `code` values for branching. Treat `data` as the
+command-specific payload. `setup-agents` retains versioned compatibility fields;
+inspect its current contract with `gitwise schema setup-agents --json`.
+
+## Safety model
+
+- Git subprocesses scrub executable/config injection variables and use explicit timeouts.
+- Destructive batch commands require confirmation; JSON mode returns an explicit gate.
+- `diff --scan-secrets` and `commit` detect high-confidence credential patterns.
+- setup-agents symlink creation is sandboxed to the target repository.
+- CI runs ruff, basedpyright, pytest with a 75% coverage floor, pip-audit, and shellcheck.
+
+See [Security Policy](SECURITY.md) for vulnerability reporting.
+
+## Documentation
+
+- [Documentation index (English)](docs/README.md)
+- [Indice de documentacion (Español)](docs/es/README.md)
+- [Contributing guide](CONTRIBUTING.md)
+- [Guia de contribucion](CONTRIBUTING.es.md)
+- [Security policy](SECURITY.md)
+- [Politica de seguridad](SECURITY.es.md)
+- [Code of Conduct](CODE_OF_CONDUCT.md)
+- [Código de conducta](CODE_OF_CONDUCT.es.md)
+- [Git conventions](CONVENTIONS.md)
+- [Convenciones Git](CONVENTIONS.es.md)
+
+## Environment Variables
+
+| Variable | Description |
+|---|---|
+| `GITWISE_DEBUG=1` | Print each `git` subprocess command to stderr |
+| `GITWISE_LOG_JSON=1` | Emit structured stderr logs as JSON lines |
+| `GITWISE_JSON_PRETTY=1` | Pretty-print JSON output by default |
+| `GITWISE_LANG=es` / `GITWISE_LANG=en` | Force output locale |
+| `GITWISE_THEME=dark` / `GITWISE_THEME=light` / `GITWISE_THEME=auto` | Override color theme selection |
+| `GITWISE_NO_COLOR=1` | Disable ANSI color output |
+| `GITWISE_OUTPUT=agent` | Force machine-oriented output mode |
+| `GITWISE_AGENT=1` | Alias to enable agent output mode |
+| `GITWISE_GIT_TIMEOUT=<seconds>` | Override git subprocess timeout |
+| `GITWISE_WIDTH=<columns>` | Override output width |
+
+## Shell Completions
+
+Generate completions script per shell:
+
+```bash
+gitwise completions bash > ~/.local/share/bash-completion/completions/gitwise
+gitwise completions zsh > ~/.zsh/completions/_gitwise
+gitwise completions fish > ~/.config/fish/completions/gitwise.fish
+```
+
+**PowerShell** (Windows / PowerShell Core): generate and dot-source the
+`Register-ArgumentCompleter` script. Add it to your `$PROFILE` for persistence:
+
+```powershell
+gitwise completions powershell > gitwise.ps1
+. .\gitwise.ps1
+# or, to load on every session:
+Add-Content $PROFILE ('. ' + ((Resolve-Path 'gitwise.ps1').Path))
+```
+
+Completion covers subcommands as the first token and per-command flags
+(`--json`, `--dry-run`, `--max-count`, etc.) thereafter.
+
+## Demo
+
+Run the non-destructive current demo from a Git repository:
+
+```bash
+bash demo/script.sh
+```
+
+## License
+
+[MIT](LICENSE) - Deiner

{gitwise_cli-0.35.1 → gitwise_cli-0.36.1}/gitwise/__init__.py

@@ -1,6 +1,6 @@
 """gitwise -- CLI for optimizing git workflows and coding-agent integration."""
 
-__version__ = "0.35.1"
+__version__ = "0.36.1"
 
 
 def get_version() -> str:

{gitwise_cli-0.35.1 → gitwise_cli-0.36.1}/gitwise/_cli_dispatch.py

@@ -125,7 +125,6 @@ def _run_clean(args: argparse.Namespace) -> int:
 
     return run_clean(
         branches=args.branches,
-        refs=args.refs,
         dry_run=args.dry_run,
         yes=args.yes,
         as_json=args.json,

{gitwise_cli-0.35.1 → gitwise_cli-0.36.1}/gitwise/_cli_parser.py

@@ -157,16 +157,15 @@ def build_parser() -> argparse.ArgumentParser:
     p.add_argument("--diff", action="store_true")
     p.add_argument("--max-commits", type=int, default=10, dest="max_commits")
 
-    p = sub.add_parser("snapshot", help="generate .claude/git-snapshot.md", parents=[parent])
+    p = sub.add_parser("snapshot", help="generate agent git snapshot", parents=[parent])
 
     p = sub.add_parser(
         "clean",
-        help="clean up stale branches and refs",
+        help="clean up stale branches",
         aliases=["branch-clean"],
         parents=[parent],
     )
     p.add_argument("--branches", action="store_true")
-    p.add_argument("--refs", action="store_true")
     p.add_argument("--dry-run", action="store_true")
     p.add_argument("--yes", "-y", action="store_true")
 

{gitwise_cli-0.35.1 → gitwise_cli-0.36.1}/gitwise/_i18n_data.json

@@ -151,13 +151,9 @@
     "es": "gitwise clean --branches --dry-run",
     "en": "gitwise clean --branches --dry-run"
   },
-  "clean_refs_not_implemented": {
-    "es": "'clean --refs' no está implementado",
-    "en": "'clean --refs' is not implemented"
-  },
   "clean_specify_flag": {
-    "es": "especifica --branches  (o --refs)",
-    "en": "specify --branches  (or --refs)"
+    "es": "especifica --branches",
+    "en": "specify --branches"
   },
   "clean_to_delete": {
     "es": "para eliminar: gitwise clean --branches --yes",
@@ -876,7 +872,7 @@
     "en": ".claude/commands/{skill}.md is legacy format — now using .claude/skills/{skill}/SKILL.md. Delete the old .md manually."
   },
   "legacy_migration_mode": {
-    "es": "modo migracion legacy activo: se prioriza layout canonico (AGENTS.md + .agents/skills)",
+    "es": "modo migración legacy activo: se prioriza layout canónico (AGENTS.md + .agents/skills)",
     "en": "legacy migration mode enabled: canonical layout (AGENTS.md + .agents/skills) is enforced"
   },
   "log_no_commits": {
@@ -2071,6 +2067,10 @@
     "es": "ejecutaría: git pull --ff-only en {dir}",
     "en": "would run: git pull --ff-only in {dir}"
   },
+  "update_deprecation_hint": {
+    "es": "update está deprecado; usa `brew upgrade gitwise` para Homebrew o `uv tool upgrade gitwise-cli` para instalaciones con uv tool",
+    "en": "update is deprecated; use `brew upgrade gitwise` for Homebrew or `uv tool upgrade gitwise-cli` for uv tool installations"
+  },
   "updated_git_conventions": {
     "es": "actualizado: {file} (convenciones git agregadas)",
     "en": "updated: {file} (git conventions added)"

{gitwise_cli-0.35.1 → gitwise_cli-0.36.1}/gitwise/clean.py

@@ -59,7 +59,6 @@ def _categorize(
 def run_clean(
     *,
     branches: bool = False,
-    refs: bool = False,
     dry_run: bool = False,
     yes: bool = False,
     as_json: bool = False,
@@ -70,11 +69,6 @@ def run_clean(
     user-cancelled), 1 on delete failures or missing flag, 2 when
     ``--json`` is used without ``--yes``.
     """
-    if refs:
-        return report_error(
-            "clean", as_json=as_json, msg=t("clean_refs_not_implemented"), code="not_implemented"
-        )
-
     if not branches:
         return report_error(
             "clean", as_json=as_json, msg=t("clean_specify_flag"), code="clean_specify_flag"