universal-dev-security 1.0.0__py3-none-any.whl

universal_dev_security/__init__.py

@@ -0,0 +1,3 @@
+"""Universal Dev Security (UDS) — one security system for every project."""
+
+__version__ = "1.0.0"

universal_dev_security/__main__.py

@@ -0,0 +1,4 @@
+"""Allow ``python -m universal_dev_security``."""
+from universal_dev_security.cli import main
+
+raise SystemExit(main())

universal_dev_security/cli.py

@@ -0,0 +1,376 @@
+"""Command-line interface for Universal Dev Security."""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import platform
+import shutil
+import sys
+from pathlib import Path
+from typing import Any, Callable
+
+from universal_dev_security import __version__
+from universal_dev_security.config import FAIL_ON_LEVELS, ConfigError, ProjectConfig, load_config
+from universal_dev_security.detector import detect_project
+from universal_dev_security.initializer import initialize_project
+
+EXIT_OK, EXIT_FINDINGS, EXIT_ERROR = 0, 1, 2
+
+
+def _out(data: Any) -> None:
+    print(json.dumps(data, indent=2, ensure_ascii=False))
+
+
+def _err(message: str) -> None:
+    print(f"uds: {message}", file=sys.stderr)
+
+
+def _project(path: str) -> Path:
+    target = Path(path).expanduser().resolve()
+    if not target.is_dir():
+        raise ValueError(f"Not an existing directory: {target}")
+    return target
+
+
+def _config(root: Path) -> ProjectConfig:
+    return load_config(root)
+
+
+# ---------------------------------------------------------------------------
+# Commands
+# ---------------------------------------------------------------------------
+
+def cmd_doctor(args: argparse.Namespace) -> int:
+    from universal_dev_security.scanners import available_scanners, get_scanner
+
+    root = _project(args.path)
+    scanners = [get_scanner(name).info(root) for name in available_scanners()]
+    try:
+        config = load_config(root)
+        config_state = {"exists": config.exists, "warnings": config.warnings}
+    except ConfigError as exc:
+        config_state = {"exists": True, "error": str(exc)}
+    data = {
+        "uds_version": __version__,
+        "python": sys.version.split()[0],
+        "platform": f"{platform.system()} {platform.release()}",
+        "git": shutil.which("git") is not None,
+        "config": config_state,
+        "scanners": scanners,
+        "network_used": False,
+        "global_settings_modified": False,
+    }
+    if args.json:
+        _out(data)
+    else:
+        print(f"UDS {__version__} · Python {data['python']} · {data['platform']}")
+        print(f"Git available: {'yes' if data['git'] else 'no'}")
+        print(f"Project config: {'found' if config_state.get('exists') else 'not initialized'}")
+        for warning in config_state.get("warnings", []):
+            print(f"  ! {warning}")
+        if config_state.get("error"):
+            print(f"  ! {config_state['error']}")
+        print("Scanners:")
+        for s in scanners:
+            if not s["installed"]:
+                state = "not installed" + (f" ({s['note']})" if s["note"] else "")
+            elif not s["compatible"]:
+                state = f"installed {s['version'] or 'unknown version'} — UNSUPPORTED (need {s['minimum_version']}+)"
+            else:
+                state = f"OK {s['version']}"
+            print(f"  {s['display_name']:<12} {state}")
+            if not s["installed"]:
+                hint = s["install_hints"].get({"Windows": "windows", "Darwin": "macos"}.get(platform.system(), "linux"))
+                print(f"  {'':<12} install: {hint}  ({s['docs_url']})")
+        print("UDS runtime: OK (no network access used, no global settings modified)")
+    return EXIT_OK
+
+
+def cmd_detect(args: argparse.Namespace) -> int:
+    _out(detect_project(_project(args.path)))
+    return EXIT_OK
+
+
+def cmd_init(args: argparse.Namespace) -> int:
+    result = initialize_project(Path(args.path))
+    _out(result)
+    return EXIT_OK if result["status"] in {"initialized", "already_initialized"} else EXIT_ERROR
+
+
+def cmd_status(args: argparse.Namespace) -> int:
+    from universal_dev_security.history import list_scans, load_scan
+
+    target = _project(args.path)
+    config = target / ".uds" / "config.toml"
+    if not config.is_file():
+        print(f"UDS not initialized: {target}")
+        print("Run `uds init` to create the local project configuration.")
+        return EXIT_FINDINGS
+    print(f"UDS initialized: {target}")
+    print(f"Configuration: {config}")
+    scans = list_scans(target)
+    if scans:
+        latest = load_scan(target, "latest")
+        print(f"Latest scan: {latest['scan_id']} · status {latest['overall_status']} · "
+              f"{latest['summary']['finding_count']} finding(s) · scanners run: "
+              f"{', '.join(latest['coverage']['executed']) or 'none'}")
+    else:
+        print("Latest scan: none (run `uds scan`)")
+    return EXIT_OK
+
+
+def _print_scan_summary(scan: dict[str, Any], paths: dict[str, str], comparison: dict[str, Any] | None) -> None:
+    summary = scan["summary"]
+    print(f"UDS scan {scan['scan_id']} · {scan['target']}")
+    print(f"Overall status: {scan['overall_status'].upper()}")
+    for s in scan["scanners"]:
+        print(f"  {s['tool']:<12} {s['status']:<15} {s['finding_count'] if s['executed'] else '-':>5}  {s['message']}")
+    sev = summary["by_severity"]
+    print("Findings: " + ", ".join(f"{k} {v}" for k, v in sev.items()) + f" (total {summary['finding_count']})")
+    if comparison:
+        print(f"Since previous scan: {len(comparison['new'])} new, {len(comparison['resolved'])} resolved, "
+              f"{len(comparison['not_rescanned'])} not re-scanned")
+        for warning in comparison.get("warnings", []):
+            print(f"  ! {warning}")
+    for kind, path in paths.items():
+        print(f"Report ({kind}): {path}")
+
+
+def cmd_scan(args: argparse.Namespace) -> int:
+    from universal_dev_security.engine import exit_code_for, run_scan
+    from universal_dev_security.history import compare_scans, history_summaries, list_scans, load_scan, save_scan
+    from universal_dev_security.reports import build_report, write_reports
+
+    root = _project(args.path)
+    config = _config(root)
+    for warning in config.warnings:
+        _err(f"config warning: {warning}")
+    progress: Callable[[str], None] | None = None if (args.json or args.quiet) else (lambda m: print(m, file=sys.stderr))
+    scan = run_scan(root, config, tools=args.tool or None,
+                    allow_network=True if args.allow_network else None, progress=progress)
+
+    comparison = None
+    if not args.no_history:
+        previous = list_scans(root)
+        if previous:
+            try:
+                comparison = compare_scans(load_scan(root, previous[-1]), scan)
+            except (OSError, ValueError):
+                comparison = None
+        save_scan(root, scan, config.history_limit)
+    history = [] if args.no_history else history_summaries(root)
+    report = build_report(scan, comparison, history)
+    formats = tuple(f.strip() for f in args.format.split(",") if f.strip())
+    paths = write_reports(report, root, Path(args.report_dir) if args.report_dir else None, formats)
+    fail_on = args.fail_on or config.fail_on
+    code = exit_code_for(scan, fail_on, args.require_complete)
+    if args.json:
+        _out({"scan_id": scan["scan_id"], "overall_status": scan["overall_status"], "exit_code": code,
+              "summary": scan["summary"], "scanners": scan["scanners"], "reports": paths,
+              "comparison": {k: (len(v) if isinstance(v, list) else v) for k, v in comparison.items()} if comparison else None})
+    elif not args.quiet:
+        _print_scan_summary(scan, paths, comparison)
+        if code == EXIT_FINDINGS:
+            print(f"Result: findings at or above fail-on threshold '{fail_on}'.")
+        elif code == EXIT_ERROR:
+            print("Result: scan incomplete or failed — results must not be treated as a pass.")
+    return code
+
+
+def cmd_report(args: argparse.Namespace) -> int:
+    from universal_dev_security.history import compare_scans, history_summaries, list_scans, load_scan, resolve_scan_id
+    from universal_dev_security.reports import build_report, write_reports
+
+    root = _project(args.path)
+    scan_id = resolve_scan_id(root, args.scan)
+    scan = load_scan(root, scan_id)
+    scans = list_scans(root)
+    index = scans.index(scan_id)
+    comparison = compare_scans(load_scan(root, scans[index - 1]), scan) if index > 0 else None
+    history = [h for h in history_summaries(root, 1000) if str(h["scan_id"]) <= scan_id][-20:]
+    formats = tuple(f.strip() for f in args.format.split(",") if f.strip())
+    paths = write_reports(build_report(scan, comparison, history), root,
+                          Path(args.report_dir) if args.report_dir else None, formats)
+    _out(paths)
+    return EXIT_OK
+
+
+def cmd_dashboard(args: argparse.Namespace) -> int:
+    root = _project(args.path)
+    html = (Path(args.report_dir).expanduser().resolve() if args.report_dir else root / ".uds" / "reports") / "security-report.html"
+    if not html.is_file():
+        _err("No dashboard found. Run `uds scan` first.")
+        return EXIT_ERROR
+    print(html)
+    if args.open:
+        import webbrowser
+        webbrowser.open(html.as_uri())
+    return EXIT_OK
+
+
+def cmd_history(args: argparse.Namespace) -> int:
+    from universal_dev_security.history import history_summaries
+
+    entries = history_summaries(_project(args.path), args.limit)
+    if args.json:
+        _out(entries)
+        return EXIT_OK
+    if not entries:
+        print("No scan history. Run `uds scan`.")
+        return EXIT_OK
+    for e in entries:
+        sev = e["by_severity"]
+        print(f"{e['scan_id']}  {e['overall_status']:<12} total {e['finding_count']:>4}  "
+              + " ".join(f"{k[:4]}:{v}" for k, v in sev.items()) + f"  [{', '.join(e['executed'])}]")
+    return EXIT_OK
+
+
+def cmd_compare(args: argparse.Namespace) -> int:
+    from universal_dev_security.history import compare_scans, load_scan
+
+    root = _project(args.path)
+    result = compare_scans(load_scan(root, args.base), load_scan(root, args.head))
+    if args.json:
+        _out(result)
+        return EXIT_OK
+    print(f"Base {result['base_scan_id']} → head {result['current_scan_id']} (tools: {', '.join(result['compared_tools']) or 'none'})")
+    print(f"New: {len(result['new'])}  Resolved: {len(result['resolved'])}  Unchanged: {result['unchanged_count']}  "
+          f"Not re-scanned: {len(result['not_rescanned'])}")
+    for label in ("new", "resolved"):
+        for f in result[label][:50]:
+            print(f"  [{label}] {f['severity']:<12} {f['tool']:<11} {f['rule_id']}  {f.get('file') or ''}")
+    return EXIT_OK
+
+
+def cmd_policy(args: argparse.Namespace) -> int:
+    from universal_dev_security.policy import GLOBAL_COMMAND_RULES, Action, ActionKind, PolicyEngine
+
+    root = _project(args.path)
+    config = _config(root)
+    if args.policy_command == "show":
+        _out({
+            "precedence": ["mandatory global policy", "technology profile", "project configuration"],
+            "global_command_rules": [{"rule_id": r.rule_id, "decision": r.decision.value, "risk": r.risk.value,
+                                      "reason": r.reason} for r in GLOBAL_COMMAND_RULES],
+            "project": config.to_dict(),
+        })
+        return EXIT_OK
+    engine = PolicyEngine(config)
+    if args.command_text is not None:
+        action = Action(ActionKind.SHELL, command=args.command_text, project_root=str(root))
+    else:
+        content = Path(args.content_file).read_text(encoding="utf-8", errors="replace") if args.content_file else ""
+        action = Action(ActionKind.WRITE_FILE, path=args.write, content=content, project_root=str(root))
+    decision = engine.evaluate(action)
+    _out(decision.to_dict())
+    return {"allow": EXIT_OK, "ask": EXIT_FINDINGS, "deny": EXIT_ERROR}[decision.decision.value]
+
+
+def cmd_scanners(args: argparse.Namespace) -> int:
+    from universal_dev_security.scanners import available_scanners, get_scanner
+
+    _out([get_scanner(name).info(Path.cwd()) for name in available_scanners()])
+    return EXIT_OK
+
+
+# ---------------------------------------------------------------------------
+# Parser
+# ---------------------------------------------------------------------------
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="uds", description="Universal Dev Security — One Security System. Every Project.")
+    parser.add_argument("--version", action="version", version=f"UDS {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    def with_path(p: argparse.ArgumentParser) -> argparse.ArgumentParser:
+        p.add_argument("path", nargs="?", default=".", help="Project directory (default: current directory)")
+        return p
+
+    p = with_path(sub.add_parser("doctor", help="Check the UDS runtime, configuration and scanners"))
+    p.add_argument("--json", action="store_true")
+    p.set_defaults(func=cmd_doctor)
+    with_path(sub.add_parser("detect", help="Detect project technologies and scanning profile")).set_defaults(func=cmd_detect)
+    with_path(sub.add_parser("init", help="Initialize UDS in a project safely (never overwrites)")).set_defaults(func=cmd_init)
+    with_path(sub.add_parser("status", help="Show UDS project status")).set_defaults(func=cmd_status)
+
+    p = with_path(sub.add_parser("scan", help="Run applicable security scanners and write reports"))
+    p.add_argument("--tool", action="append", choices=["gitleaks", "semgrep", "osv-scanner", "trivy"],
+                   help="Run only this scanner (repeatable). Default: scanners enabled in config.")
+    p.add_argument("--report-dir", help="Directory for reports (default: PATH/.uds/reports)")
+    p.add_argument("--format", default="json,html", help="Comma-separated: json,html,sarif (default: json,html)")
+    p.add_argument("--allow-network", action="store_true",
+                   help="Allow scanners that send package metadata to external services (OSV-Scanner)")
+    p.add_argument("--fail-on", choices=FAIL_ON_LEVELS, help="Exit 1 when findings reach this severity")
+    p.add_argument("--require-complete", action="store_true",
+                   help="Exit 2 when an applicable scanner did not run (not installed or skipped)")
+    p.add_argument("--no-history", action="store_true", help="Do not record this scan in .uds/history")
+    p.add_argument("--json", action="store_true", help="Print a machine-readable summary")
+    p.add_argument("--quiet", action="store_true")
+    p.set_defaults(func=cmd_scan)
+
+    p = with_path(sub.add_parser("report", help="Regenerate reports from scan history"))
+    p.add_argument("--scan", default="latest", help="Scan id, 'latest' or 'previous'")
+    p.add_argument("--report-dir")
+    p.add_argument("--format", default="json,html")
+    p.set_defaults(func=cmd_report)
+
+    p = with_path(sub.add_parser("dashboard", help="Show (or open) the latest HTML dashboard"))
+    p.add_argument("--report-dir")
+    p.add_argument("--open", action="store_true", help="Open the dashboard in the default browser")
+    p.set_defaults(func=cmd_dashboard)
+
+    p = with_path(sub.add_parser("history", help="List previous scans"))
+    p.add_argument("--limit", type=int, default=20)
+    p.add_argument("--json", action="store_true")
+    p.set_defaults(func=cmd_history)
+
+    p = with_path(sub.add_parser("compare", help="Compare two scans from history"))
+    p.add_argument("--base", default="previous")
+    p.add_argument("--head", default="latest")
+    p.add_argument("--json", action="store_true")
+    p.set_defaults(func=cmd_compare)
+
+    p = sub.add_parser("policy", help="Show or test the effective security policy")
+    psub = p.add_subparsers(dest="policy_command", required=True)
+    with_path(psub.add_parser("show", help="Print global rules and project policy")).set_defaults(func=cmd_policy)
+    pc = with_path(psub.add_parser("check", help="Evaluate a command or file write against the policy"))
+    group = pc.add_mutually_exclusive_group(required=True)
+    group.add_argument("--command", dest="command_text", help="Shell command to evaluate")
+    group.add_argument("--write", help="Relative path of a file about to be written")
+    pc.add_argument("--content-file", help="File whose content would be written (with --write)")
+    pc.set_defaults(func=cmd_policy)
+
+    sub.add_parser("scanners", help="List supported scanners, versions and install sources").set_defaults(func=cmd_scanners)
+
+    from universal_dev_security import cli_extra
+    cli_extra.register(sub, with_path)
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    if os.name == "nt":
+        for stream in (sys.stdout, sys.stderr):
+            try:
+                stream.reconfigure(encoding="utf-8", errors="replace")  # type: ignore[attr-defined]
+            except (AttributeError, ValueError):
+                pass
+    args = build_parser().parse_args(argv)
+    try:
+        return int(args.func(args))
+    except ConfigError as exc:
+        _err(str(exc))
+        return EXIT_ERROR
+    except (ValueError, FileNotFoundError, NotADirectoryError) as exc:
+        _err(str(exc))
+        return EXIT_ERROR
+    except PermissionError as exc:
+        _err(f"Permission denied: {exc.filename or ''}")
+        return EXIT_ERROR
+    except KeyboardInterrupt:
+        _err("Interrupted.")
+        return 130
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

universal_dev_security/cli_extra.py

@@ -0,0 +1,244 @@
+"""CLI commands for integrations, Git protection, recovery, fixes, testing and updates."""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any, Callable
+
+EXIT_OK, EXIT_FINDINGS, EXIT_ERROR = 0, 1, 2
+
+
+def _out(data: Any) -> None:
+    print(json.dumps(data, indent=2, ensure_ascii=False))
+
+
+def _project(path: str) -> Path:
+    target = Path(path).expanduser().resolve()
+    if not target.is_dir():
+        raise ValueError(f"Not an existing directory: {target}")
+    return target
+
+
+def _print_plan(result: dict[str, Any], apply: bool) -> None:
+    if not result["changes"]:
+        print("No changes needed.")
+    for change in result["changes"]:
+        print(f"{change['action'].upper()}: {change['path']}")
+        if not apply and change.get("diff"):
+            print(change["diff"])
+    if apply and result.get("checkpoint"):
+        print(f"Applied. Recovery checkpoint: {result['checkpoint']} (undo with `uds rollback {result['checkpoint']}`)")
+    elif not apply and result["changes"]:
+        print("Dry run only. Re-run with --apply to make these changes.")
+    for note in result.get("notes", []):
+        print(f"note: {note}")
+    for conflict in result.get("conflicts", []):
+        print(f"conflict: {conflict['path']}: {conflict['message']}")
+
+
+# -- hooks runtime -----------------------------------------------------------
+
+def cmd_hook(args: argparse.Namespace) -> int:
+    if args.hook_name == "claude-code":
+        from universal_dev_security.integrations.claude_code import run_hook
+
+        code, output = run_hook(sys.stdin.read())
+        if output:
+            print(output)
+        return code
+    from universal_dev_security import gitguard
+
+    try:
+        if args.hook_name == "git-pre-commit":
+            code, message = gitguard.pre_commit(Path.cwd())
+        else:
+            remote = args.hook_args[0] if args.hook_args else "origin"
+            code, message = gitguard.pre_push(Path.cwd(), remote, sys.stdin.read())
+    except Exception as exc:  # noqa: BLE001 - fail closed
+        print(f"UDS: security check failed ({type(exc).__name__}); blocking to be safe.", file=sys.stderr)
+        return EXIT_FINDINGS
+    print(message, file=sys.stderr)
+    return code
+
+
+def cmd_guard(args: argparse.Namespace) -> int:
+    from universal_dev_security.integrations.agents import guard
+
+    code, payload = guard(sys.stdin.read(), str(Path(args.project).expanduser().resolve()))
+    _out(payload)
+    return code
+
+
+# -- installation commands ------------------------------------------------------
+
+def cmd_hooks(args: argparse.Namespace) -> int:
+    from universal_dev_security import gitguard
+
+    root = _project(args.path)
+    try:
+        if args.hooks_command == "status":
+            _out(gitguard.hooks_status(root))
+            return EXIT_OK
+        python = sys.executable if args.python_path else None
+        result = gitguard.install_hooks(root, apply=args.apply, uninstall=args.hooks_command == "uninstall",
+                                        python=python)
+    except gitguard.GitError as exc:
+        print(f"uds: {exc}", file=sys.stderr)
+        return EXIT_ERROR
+    _print_plan(result, args.apply)
+    return EXIT_FINDINGS if result.get("conflicts") else EXIT_OK
+
+
+def cmd_integrate(args: argparse.Namespace) -> int:
+    root = _project(args.path)
+    if args.target == "claude-code":
+        from universal_dev_security.integrations import claude_code
+
+        result = claude_code.install(root, apply=args.apply, remove=args.remove, local=args.local,
+                                     use_python_path=args.python_path)
+    elif args.target == "github":
+        from universal_dev_security.integrations import github
+
+        result = github.install(root, apply=args.apply, remove=args.remove, branch=args.branch,
+                                fail_on=args.fail_on, uds_spec=args.uds_spec)
+    else:
+        from universal_dev_security.integrations import vscode
+
+        result = vscode.install(root, apply=args.apply, remove=args.remove)
+    if args.json:
+        _out(result)
+    else:
+        _print_plan(result, args.apply)
+    return EXIT_OK
+
+
+# -- recovery ---------------------------------------------------------------------
+
+def cmd_checkpoint(args: argparse.Namespace) -> int:
+    from universal_dev_security.recovery import RecoveryManager
+
+    manager = RecoveryManager(_project(args.path))
+    if args.checkpoint_command == "list":
+        _out(manager.list())
+        return EXIT_OK
+    checkpoint = manager.create(args.label or "manual checkpoint", args.files)
+    manager.seal(checkpoint)
+    _out({"checkpoint": checkpoint, "files": args.files})
+    return EXIT_OK
+
+
+def cmd_rollback(args: argparse.Namespace) -> int:
+    from universal_dev_security.recovery import RecoveryManager
+
+    result = RecoveryManager(_project(args.path)).restore(args.checkpoint, force=args.force)
+    _out(result)
+    return EXIT_OK if result["status"] == "restored" else EXIT_FINDINGS
+
+
+# -- fixes and tests ------------------------------------------------------------
+
+def cmd_fix(args: argparse.Namespace) -> int:
+    from universal_dev_security.config import load_config
+    from universal_dev_security.fixes import apply_fixes, manual_recommendations, plan_fixes
+    from universal_dev_security.history import list_scans, load_scan
+
+    root = _project(args.path)
+    config = load_config(root)
+    latest = load_scan(root, "latest") if list_scans(root) else None
+    if not args.apply:
+        _out({"automatic_fixes": plan_fixes(root), "manual_recommendations": manual_recommendations(latest),
+              "note": "Dry run. Use --apply for low-risk fixes; add --include-medium for medium-risk fixes."})
+        return EXIT_OK
+    result = apply_fixes(root, config, include_medium=args.include_medium, run_test_suite=not args.skip_tests,
+                         approved=args.approve)
+    _out(result)
+    return EXIT_OK if result["status"] in ("applied", "nothing_to_do") else EXIT_FINDINGS
+
+
+def cmd_test(args: argparse.Namespace) -> int:
+    from universal_dev_security.config import load_config
+    from universal_dev_security.testing import run_tests
+
+    root = _project(args.path)
+    result = run_tests(root, load_config(root))
+    _out(result)
+    return {"passed": EXIT_OK, "not_configured": EXIT_FINDINGS}.get(result["status"], EXIT_ERROR)
+
+
+# -- updates ------------------------------------------------------------------------
+
+def cmd_update(args: argparse.Namespace) -> int:
+    from universal_dev_security.updates import check_uds_update, scanner_status
+
+    if args.update_command == "scanners":
+        _out(scanner_status())
+        return EXIT_OK
+    result = check_uds_update(args.source)
+    _out(result)
+    return EXIT_ERROR if result["status"] == "error" else EXIT_OK
+
+
+def register(sub: Any, with_path: Callable[[argparse.ArgumentParser], argparse.ArgumentParser]) -> None:
+    p = sub.add_parser("hook", help="Hook entry points (called by Git and Claude Code)")
+    p.add_argument("hook_name", choices=["claude-code", "git-pre-commit", "git-pre-push"])
+    p.add_argument("hook_args", nargs="*")
+    p.set_defaults(func=cmd_hook)
+
+    p = sub.add_parser("guard", help="Policy decision for AI agents: JSON action on stdin, decision on stdout")
+    p.add_argument("--project", default=".", help="Project root (default: current directory)")
+    p.set_defaults(func=cmd_guard)
+
+    p = sub.add_parser("hooks", help="Install, remove or inspect UDS Git hooks")
+    hsub = p.add_subparsers(dest="hooks_command", required=True)
+    for name in ("install", "uninstall"):
+        hp = with_path(hsub.add_parser(name))
+        hp.add_argument("--apply", action="store_true", help="Make the change (default is a dry run)")
+        hp.add_argument("--python-path", action="store_true",
+                        help="Embed this Python interpreter in the hook instead of relying on `uds` on PATH")
+        hp.set_defaults(func=cmd_hooks)
+    with_path(hsub.add_parser("status")).set_defaults(func=cmd_hooks, apply=False, python_path=False)
+
+    p = sub.add_parser("integrate", help="Set up Claude Code, GitHub Actions or VS Code integration")
+    p.add_argument("target", choices=["claude-code", "github", "vscode"])
+    with_path(p)
+    p.add_argument("--apply", action="store_true", help="Make the change (default is a dry run with a diff)")
+    p.add_argument("--remove", action="store_true", help="Remove UDS-owned configuration only")
+    p.add_argument("--local", action="store_true", help="Claude Code: write .claude/settings.local.json")
+    p.add_argument("--python-path", action="store_true", help="Claude Code: embed this interpreter path in the hook")
+    p.add_argument("--branch", default="main", help="GitHub: default branch for push scans")
+    p.add_argument("--fail-on", default="high", help="GitHub: severity threshold that fails the check")
+    p.add_argument("--uds-spec", default="universal-dev-security", help="GitHub: pip install spec for UDS")
+    p.add_argument("--json", action="store_true")
+    p.set_defaults(func=cmd_integrate)
+
+    p = sub.add_parser("checkpoint", help="Create or list recovery checkpoints")
+    csub = p.add_subparsers(dest="checkpoint_command", required=True)
+    cp = with_path(csub.add_parser("create"))
+    cp.add_argument("--label")
+    cp.add_argument("--file", dest="files", action="append", required=True, help="Project-relative file (repeatable)")
+    cp.set_defaults(func=cmd_checkpoint)
+    with_path(csub.add_parser("list")).set_defaults(func=cmd_checkpoint)
+
+    p = sub.add_parser("rollback", help="Restore a recovery checkpoint (keeps later user edits unless --force)")
+    p.add_argument("checkpoint")
+    with_path(p)
+    p.add_argument("--force", action="store_true", help="Also overwrite files changed after the checkpoint")
+    p.set_defaults(func=cmd_rollback)
+
+    p = with_path(sub.add_parser("fix", help="Plan or apply safe, reversible automatic fixes"))
+    p.add_argument("--apply", action="store_true")
+    p.add_argument("--include-medium", action="store_true")
+    p.add_argument("--skip-tests", action="store_true", help="Do not run tests before/after fixing")
+    p.add_argument("--approve", action="store_true", help="Explicit approval when automatic fixes are disabled by config")
+    p.set_defaults(func=cmd_fix)
+
+    with_path(sub.add_parser("test", help="Detect and run the project's test suite")).set_defaults(func=cmd_test)
+
+    p = sub.add_parser("update", help="Check for UDS updates or show scanner versions (never installs)")
+    usub = p.add_subparsers(dest="update_command", required=True)
+    up = usub.add_parser("check")
+    up.add_argument("--source", help="'pypi' or 'github:OWNER/REPO' (network request only when given)")
+    up.set_defaults(func=cmd_update)
+    usub.add_parser("scanners").set_defaults(func=cmd_update)