gitwise-cli 0.24.2__py3-none-any.whl

gitwise/_cli_introspection.py

@@ -0,0 +1,275 @@
+"""CLI introspection: help payload, command metadata, JSON schema generation."""
+
+import argparse
+from typing import TypedDict
+
+from . import __version__
+
+
+def _json_safe(value: object) -> object:
+    if value is argparse.SUPPRESS:
+        return None
+    if value is None or isinstance(value, str | int | float | bool):
+        return value
+    if isinstance(value, list | tuple | set):
+        return [_json_safe(item) for item in value]
+    if isinstance(value, dict):
+        return {str(key): _json_safe(item) for key, item in value.items()}
+    return str(value)
+
+
+def _subparsers_action(parser: argparse.ArgumentParser) -> argparse._SubParsersAction | None:
+    for action in parser._actions:
+        if isinstance(action, argparse._SubParsersAction):
+            return action
+    return None
+
+
+def _serialize_actions(parser: argparse.ArgumentParser) -> list[dict[str, object]]:
+    items: list[dict[str, object]] = []
+    for action in parser._actions:
+        if action.dest in {"help"}:
+            continue
+        if isinstance(action, argparse._SubParsersAction):
+            continue
+        option_strings = list(action.option_strings)
+        items.append(
+            {
+                "kind": "option" if option_strings else "argument",
+                "name": action.dest,
+                "flags": option_strings,
+                "required": bool(getattr(action, "required", False)),
+                "nargs": _json_safe(action.nargs),
+                "default": _json_safe(action.default),
+                "choices": _json_safe(list(action.choices) if action.choices else []),
+                "help": "" if action.help is argparse.SUPPRESS else (action.help or ""),
+            }
+        )
+    return items
+
+
+def extract_command_token(argv: list[str]) -> str | None:
+    skip_next = False
+    for token in argv:
+        if skip_next:
+            skip_next = False
+            continue
+        if token in {"--lang", "--theme"}:
+            skip_next = True
+            continue
+        if token.startswith("-"):
+            continue
+        return token
+    return None
+
+
+def help_payload(parser: argparse.ArgumentParser, command: str | None = None) -> dict[str, object]:
+    payload: dict[str, object] = {
+        "v": 2,
+        "ok": True,
+        "kind": "help",
+        "schema": "gitwise/help/v1",
+        "version": __version__,
+    }
+
+    sub_action = _subparsers_action(parser)
+    if command is None or sub_action is None or command not in sub_action.choices:
+        commands: list[dict[str, object]] = []
+        if sub_action is not None:
+            help_by_parser_id: dict[int, str] = {}
+            for pseudo in sub_action._choices_actions:
+                parser_name = str(pseudo.dest)
+                parser_obj = sub_action.choices.get(parser_name)
+                if parser_obj is None:
+                    continue
+                parser_id = id(parser_obj)
+                if parser_id not in help_by_parser_id:
+                    help_by_parser_id[parser_id] = pseudo.help or ""
+
+            seen_parsers: set[int] = set()
+            for name, choice_parser in sorted(sub_action.choices.items()):
+                parser_id = id(choice_parser)
+                if parser_id in seen_parsers:
+                    continue
+                seen_parsers.add(parser_id)
+                aliases = [
+                    alias
+                    for alias, alias_parser in sub_action.choices.items()
+                    if alias_parser is choice_parser and alias != name
+                ]
+                commands.append(
+                    {
+                        "name": name,
+                        "help": help_by_parser_id.get(parser_id, choice_parser.description or ""),
+                        "aliases": sorted(aliases),
+                    }
+                )
+
+        payload.update(
+            {
+                "scope": "root",
+                "usage": parser.format_usage().strip(),
+                "description": parser.description or "",
+                "options": _serialize_actions(parser),
+                "commands": sorted(commands, key=lambda item: str(item["name"])),
+            }
+        )
+        return payload
+
+    command_parser = sub_action.choices[command]
+    payload.update(
+        {
+            "scope": "command",
+            "command": command,
+            "usage": command_parser.format_usage().strip(),
+            "description": command_parser.description or "",
+            "options": _serialize_actions(command_parser),
+        }
+    )
+    return payload
+
+
+class CommandMetadata(TypedDict):
+    name: str
+    help: str
+    aliases: list[str]
+    supports_json: bool
+
+
+def canonical_command_name(command_parser: argparse.ArgumentParser) -> str:
+    prog = command_parser.prog.strip()
+    if not prog:
+        return ""
+    parts = prog.split()
+    return parts[-1] if parts else ""
+
+
+def commands_metadata(parser: argparse.ArgumentParser) -> list[CommandMetadata]:
+    sub_action = _subparsers_action(parser)
+    if sub_action is None:
+        return []
+
+    help_by_parser_id: dict[int, str] = {}
+    for pseudo in sub_action._choices_actions:
+        parser_name = str(pseudo.dest)
+        parser_obj = sub_action.choices.get(parser_name)
+        if parser_obj is None:
+            continue
+        parser_id = id(parser_obj)
+        if parser_id not in help_by_parser_id:
+            help_by_parser_id[parser_id] = pseudo.help or ""
+
+    entries: list[CommandMetadata] = []
+    seen_parser_ids: set[int] = set()
+    for command_parser in sub_action.choices.values():
+        parser_id = id(command_parser)
+        if parser_id in seen_parser_ids:
+            continue
+        seen_parser_ids.add(parser_id)
+
+        name = canonical_command_name(command_parser)
+        aliases = sorted(
+            [
+                n
+                for n, candidate in sub_action.choices.items()
+                if candidate is command_parser and n != name
+            ]
+        )
+
+        entries.append(
+            {
+                "name": name,
+                "help": help_by_parser_id.get(parser_id, command_parser.description or ""),
+                "aliases": aliases,
+                "supports_json": True,
+            }
+        )
+
+    return sorted(entries, key=lambda item: str(item["name"]))
+
+
+def _json_type_for_action(action: argparse.Action) -> str:
+    if isinstance(action, argparse._StoreTrueAction | argparse._StoreFalseAction):
+        return "boolean"
+
+    action_type = getattr(action, "type", None)
+    if action_type is int:
+        return "integer"
+    if action_type is float:
+        return "number"
+    return "string"
+
+
+def _action_property_schema(action: argparse.Action) -> dict[str, object]:
+    value_schema: dict[str, object] = {"type": _json_type_for_action(action)}
+
+    if action.choices:
+        value_schema["enum"] = [_json_safe(choice) for choice in action.choices]
+
+    description = "" if action.help is argparse.SUPPRESS else (action.help or "")
+    if description:
+        value_schema["description"] = description
+
+    if action.default is not argparse.SUPPRESS and action.default is not None:
+        value_schema["default"] = _json_safe(action.default)
+
+    nargs = action.nargs
+    if nargs in ("*", "+") or (isinstance(nargs, int) and nargs > 1):
+        array_schema: dict[str, object] = {
+            "type": "array",
+            "items": value_schema,
+        }
+        if nargs == "+":
+            array_schema["minItems"] = 1
+        if isinstance(nargs, int) and nargs > 1:
+            array_schema["minItems"] = nargs
+            array_schema["maxItems"] = nargs
+        return array_schema
+
+    return value_schema
+
+
+def _action_required(action: argparse.Action) -> bool:
+    if action.option_strings:
+        return bool(getattr(action, "required", False))
+
+    nargs = action.nargs
+    if nargs in (None, "+"):
+        return True
+    if isinstance(nargs, int):
+        return nargs > 0
+    return False
+
+
+def command_input_schema(command_parser: argparse.ArgumentParser) -> dict[str, object]:
+    properties: dict[str, object] = {}
+    required: list[str] = []
+
+    for action in command_parser._actions:
+        if action.dest == "help" or isinstance(action, argparse._SubParsersAction):
+            continue
+        properties[action.dest] = _action_property_schema(action)
+        if _action_required(action):
+            required.append(action.dest)
+
+    schema: dict[str, object] = {
+        "$schema": "https://json-schema.org/draft/2020-12/schema",
+        "$id": f"https://gitwise.dev/schemas/v1/input/{canonical_command_name(command_parser)}.json",
+        "title": f"gitwise {canonical_command_name(command_parser)} cli input",
+        "type": "object",
+        "additionalProperties": False,
+        "properties": properties,
+    }
+    if required:
+        schema["required"] = sorted(set(required))
+
+    return schema
+
+
+def resolve_command_parser(
+    *, parser: argparse.ArgumentParser, name: str
+) -> argparse.ArgumentParser | None:
+    sub_action = _subparsers_action(parser)
+    if sub_action is None:
+        return None
+    return sub_action.choices.get(name)

gitwise/_cli_parser.py

@@ -0,0 +1,345 @@
+"""Argparse parser builder for all gitwise subcommands."""
+
+import argparse
+
+from . import __version__
+from .design import GitwiseRichHelpFormatter
+from .i18n import t
+
+
+def _root_help_epilog() -> str:
+    return t("help_root_environment_epilog")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parent = argparse.ArgumentParser(add_help=False)
+    parent.add_argument(
+        "--lang",
+        choices=["es", "en"],
+        default=None,
+        help="output language (default: auto-detect from locale)",
+    )
+    parent.add_argument(
+        "--theme",
+        choices=["dark", "light", "auto"],
+        default=None,
+        help="color theme: dark, light, or auto-detect (default: auto)",
+    )
+    parent.add_argument("--json", action="store_true", help="output JSON")
+    parent.add_argument(
+        "--json-pretty",
+        "--pretty",
+        dest="json_pretty",
+        action="store_true",
+        help="pretty-print JSON output",
+    )
+
+    parser = argparse.ArgumentParser(
+        prog="gitwise",
+        description="CLI for optimizing git workflows and coding agents integration",
+        formatter_class=GitwiseRichHelpFormatter,
+        epilog=_root_help_epilog(),
+        parents=[parent],
+    )
+    parser.add_argument("--version", action="version", version=f"gitwise {__version__}")
+
+    sub = parser.add_subparsers(dest="command", metavar="COMMAND")
+
+    p = sub.add_parser("doctor", help="check requirements and environment", parents=[parent])
+
+    p = sub.add_parser(
+        "setup-agents",
+        help="install canonical agents layout + optional providers globally or locally",
+        parents=[parent],
+    )
+    p.add_argument(
+        "--local",
+        action="store_true",
+        help="install into current repo instead of global home",
+    )
+    p.add_argument(
+        "--no-skills",
+        action="store_true",
+        dest="no_skills",
+        help="skip skills installation (global mode only)",
+    )
+    p.add_argument("--dry-run", action="store_true", help="show actions without executing")
+    p.add_argument("--yes", "-y", action="store_true", help="skip confirmation")
+    p.add_argument(
+        "--no-symlinks",
+        action="store_true",
+        help="force @AGENTS.md import fallback (no symlinks) — --local only",
+    )
+    p.add_argument(
+        "--strict",
+        action="store_true",
+        help="treat warnings as errors (CI) — --local only",
+    )
+    p.add_argument(
+        "--replace-claude-with-symlink",
+        action="store_true",
+        dest="replace_claude_with_symlink",
+        help="bucket 4: replace CLAUDE.md with symlink to AGENTS.md — --local only",
+    )
+    p.add_argument(
+        "--migrate-legacy-claude",
+        action="store_true",
+        dest="migrate_legacy_claude",
+        help="migrate legacy Claude-only layout to canonical AGENTS/.agents — --local only",
+    )
+    p.add_argument(
+        "--frozen-time",
+        action="store_true",
+        dest="frozen_time",
+        help="freeze snapshot timestamp — --local only",
+    )
+    p.add_argument(
+        "--no-git-files",
+        action="store_true",
+        dest="no_git_files",
+        help="don't touch .gitignore or .gitattributes — --local only",
+    )
+    p.add_argument(
+        "--providers",
+        nargs="*",
+        default=None,
+        dest="providers",
+        help="install config for coding providers (comma-separated: claude,cursor or multiple: --providers claude cursor)",
+    )
+    p.add_argument(
+        "--adapters",
+        nargs="*",
+        default=None,
+        dest="adapters",
+        help=argparse.SUPPRESS,
+    )
+    p.add_argument(
+        "--list-providers",
+        action="store_true",
+        dest="list_providers",
+        help="list available providers and exit",
+    )
+    p.add_argument(
+        "--list-adapters",
+        action="store_true",
+        dest="list_adapters",
+        help=argparse.SUPPRESS,
+    )
+
+    p = sub.add_parser("setup", help="apply modern git defaults", parents=[parent])
+    p.add_argument("--dry-run", action="store_true")
+    p.add_argument("--yes", "-y", action="store_true")
+    p.add_argument(
+        "--hooks-mode",
+        choices=["preserve", "native", "legacy", "skip"],
+        default="preserve",
+        help="hooks strategy: preserve (default), native, legacy, or skip",
+    )
+
+    p = sub.add_parser("audit", help="repository diagnostics", parents=[parent])
+    p.add_argument("--quick", action="store_true")
+
+    p = sub.add_parser("summarize", help="compact status + log", parents=[parent])
+    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(
+        "clean",
+        help="clean up stale branches and refs",
+        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")
+
+    p = sub.add_parser("optimize", help="optimize the repository", parents=[parent])
+    p.add_argument("--dry-run", action="store_true")
+    p.add_argument("--yes", "-y", action="store_true")
+
+    p = sub.add_parser("worktree", help="worktree helpers for Claude agents", parents=[parent])
+    p.add_argument("action", choices=["new", "clean"], nargs="?", metavar="new|clean")
+    p.add_argument("branch", nargs="?")
+    p.add_argument("--dry-run", action="store_true")
+
+    p = sub.add_parser(
+        "diff",
+        help="changed files with diffstat (default), or patch view",
+        parents=[parent],
+    )
+    diff_group = p.add_mutually_exclusive_group()
+    diff_group.add_argument("--staged", action="store_true", help="show staged changes only")
+    diff_group.add_argument("--name-only", action="store_true", help="show only file names")
+    diff_group.add_argument(
+        "--full", "--patch", action="store_true", help="show full patch with delta integration"
+    )
+    p.add_argument("--stat", action="store_true", help="show diffstat (default behavior)")
+
+    p = sub.add_parser("log", help="pretty git log with filters", parents=[parent])
+    p.add_argument("--oneline", action="store_true", help="one line per commit")
+    p.add_argument("--graph", action="store_true", help="show branch topology graph")
+    p.add_argument("--author", type=str, default=None, help="filter by author")
+    p.add_argument("--grep", type=str, default=None, help="filter by message pattern")
+    p.add_argument("--since", type=str, default=None, help="show commits since date")
+    p.add_argument("--until", type=str, default=None, help="show commits until date")
+    p.add_argument("--file", type=str, default=None, help="show commits for file")
+    p.add_argument("--max-count", type=int, default=20, dest="max_count", help="max commits")
+
+    p = sub.add_parser("show", help="commit inspector", parents=[parent])
+    p.add_argument("ref", nargs="?", default="HEAD", help="commit ref (default: HEAD)")
+    p.add_argument("--stat", action="store_true", help="show diffstat")
+
+    p = sub.add_parser("commit", help="smart conventional commit", parents=[parent])
+    p.add_argument("-m", "--message", type=str, default=None, help="commit message")
+    p.add_argument("--type", type=str, default=None, help="commit type (feat/fix/etc)")
+    p.add_argument("--scope", type=str, default=None, help="commit scope")
+    p.add_argument("--breaking", action="store_true", help="breaking change (!)")
+    p.add_argument("--amend", action="store_true", help="amend last commit")
+    p.add_argument("--dry-run", action="store_true", help="show without committing")
+
+    p = sub.add_parser("branches", help="branch intelligence dashboard", parents=[parent])
+    p.add_argument("--stale", action="store_true", help="show stale [gone] branches only")
+    p.add_argument("--remote", action="store_true", help="show remote branches")
+    p.add_argument(
+        "--sort",
+        type=str,
+        default="refname",
+        help="sort field: refname, committerdate, -committerdate",
+    )
+
+    p = sub.add_parser("sync", help="remote fetch, safe pull/push", parents=[parent])
+    p.add_argument("--pull", action="store_true", help="pull --ff-only after fetch")
+    p.add_argument("--push", action="store_true", help="push unpushed commits")
+    p.add_argument("--remote", type=str, default=None, help="specific remote (default: all)")
+    p.add_argument("--dry-run", action="store_true", help="show planned actions")
+
+    p = sub.add_parser("pr", help="GitHub PR wrapper (requires gh)", parents=[parent])
+    p.add_argument(
+        "action",
+        nargs="?",
+        default="list",
+        choices=["list", "checks", "view", "comments"],
+        help="pr action",
+    )
+    p.add_argument(
+        "selector",
+        nargs="?",
+        default=None,
+        help="PR number/url/branch (default: current branch PR)",
+    )
+
+    p = sub.add_parser("undo", help="reflog-based undo", parents=[parent])
+    p.add_argument("ref", nargs="?", default=None, help="target ref (default: HEAD~1)")
+    p.add_argument("--soft", action="store_true", help="soft reset (keep working tree)")
+    p.add_argument("--steps", type=int, default=1, help="number of steps back")
+    p.add_argument("--dry-run", action="store_true", help="show without resetting")
+    p.add_argument("--yes", "-y", action="store_true", help="skip confirmation for --hard")
+
+    p = sub.add_parser("context", help="enriched repo snapshot for LLMs", parents=[parent])
+
+    p = sub.add_parser("health", help="repo health score (0-100)", parents=[parent])
+
+    p = sub.add_parser(
+        "stash",
+        help="manage stashes (list/show/pop/drop/clear)",
+        parents=[parent],
+    )
+    p.add_argument(
+        "action",
+        nargs="?",
+        default="list",
+        choices=["list", "show", "pop", "drop", "clear", "clean"],
+    )
+    p.add_argument("--index", type=int, default=0, help="stash index (default: 0)")
+    p.add_argument("--dry-run", action="store_true", help="dry run (clear only)")
+    p.add_argument("--yes", "-y", action="store_true", help="skip confirmation")
+    p.add_argument("--patch", action="store_true", help="show full patch (show only)")
+
+    p = sub.add_parser("tag", help="semver-aware tag management", parents=[parent])
+    p.add_argument(
+        "action", nargs="?", default="list", choices=["list", "latest", "create", "delete"]
+    )
+    p.add_argument("name", nargs="?", help="tag name (for create/delete)")
+    p.add_argument("--bump", choices=["major", "minor", "patch"], help="bump semver part")
+    p.add_argument("-m", "--message", type=str, help="annotated tag message")
+    p.add_argument("--dry-run", action="store_true", help="show without executing")
+    p.add_argument("--yes", "-y", action="store_true", help="skip confirmation")
+
+    p = sub.add_parser("merge", help="merge/rebase with pre-flight checks", parents=[parent])
+    p.add_argument("branch", help="branch to merge/rebase from")
+    p.add_argument("--rebase", action="store_true", help="rebase instead of merge")
+    p.add_argument("--no-ff", action="store_true", help="force no-fast-forward")
+    p.add_argument("--dry-run", action="store_true", help="show checks without merging")
+    p.add_argument("--yes", "-y", action="store_true", help="skip confirmation")
+
+    p = sub.add_parser(
+        "conflicts", help="conflict detection and resolution helper", parents=[parent]
+    )
+    p.add_argument("--ours", action="store_true", help="resolve all conflicts using ours")
+    p.add_argument("--theirs", action="store_true", help="resolve all conflicts using theirs")
+
+    p = sub.add_parser(
+        "suggest",
+        help="suggest commit message from staged diff",
+        aliases=["commit-suggest"],
+        parents=[parent],
+    )
+
+    p = sub.add_parser(
+        "pick", help="cherry-pick or revert commits", aliases=["cherry-pick"], parents=[parent]
+    )
+    p.add_argument("refs", nargs="*", help="commit refs to pick/revert")
+    p.add_argument("--revert", action="store_true", help="revert instead of cherry-pick")
+    p.add_argument(
+        "--continue", dest="continue_", action="store_true", help="continue after conflict"
+    )
+    p.add_argument("--abort", action="store_true", help="abort in-progress pick/revert")
+    p.add_argument("--dry-run", action="store_true", help="show without executing")
+
+    p = sub.add_parser(
+        "update", help="update gitwise (git pull in install directory)", parents=[parent]
+    )
+    p.add_argument("--dry-run", action="store_true")
+
+    p = sub.add_parser("status", help="enhanced git status for humans and AI", parents=[parent])
+
+    p = sub.add_parser(
+        "commands",
+        help="list available subcommands and metadata",
+        parents=[parent],
+    )
+
+    p = sub.add_parser(
+        "schema",
+        help="print JSON schema for a command",
+        parents=[parent],
+    )
+    p.add_argument("name", help="command name to inspect")
+    p.add_argument(
+        "--version",
+        default="v1",
+        help="schema catalog version (default: v1)",
+    )
+
+    p = sub.add_parser(
+        "completions",
+        help="print shell completion script (bash/zsh/fish)",
+        parents=[parent],
+    )
+    p.add_argument(
+        "shell",
+        choices=["bash", "zsh", "fish"],
+        default="bash",
+        nargs="?",
+        help="target shell for completion script",
+    )
+    p.add_argument(
+        "--prog",
+        default="gitwise",
+        help="command name used inside completion script (default: gitwise)",
+    )
+
+    return parser