navig-github 0.2.4__tar.gz → 0.3.0__tar.gz

navig_github-0.3.0/PKG-INFO

@@ -0,0 +1,165 @@
+Metadata-Version: 2.4
+Name: navig-github
+Version: 0.3.0
+Summary: The full GitHub toolbox (backup, mirror, export, manage): its own navig-github command, and `navig github` inside navig.
+Author-email: NAVIG Development Team <opensource@navig.run>
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://navig.run
+Project-URL: Documentation, https://navig.run/docs
+Keywords: navig,cli,agent,automation,plugin,github,git,backup,mirror
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: navig-sdk>=2.7.0
+Requires-Dist: typer>=0.14.0
+Requires-Dist: rich>=13.7.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: requests>=2.31.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: schedule>=1.2.0
+Provides-Extra: vault
+Requires-Dist: navig-vault>=0.7.0; extra == "vault"
+Dynamic: license-file
+
+# navig-github
+
+<!-- navig:plugin-card:start -->
+<!-- Generated by scripts/gen_plugin_catalog.py — edit the plugin's pyproject.toml, not this block. -->
+
+> The full GitHub toolbox (backup, mirror, export, manage): its own navig-github command, and `navig github` inside navig.
+
+**Works on its own** — its own CLI, no navig required · v0.3.0 · [PyPI](https://pypi.org/project/navig-github/)
+
+**On its own** (no navig needed)
+
+```bash
+pip install navig-github
+navig-github --help   # no navig needed
+```
+
+**With navig**
+
+```bash
+pip install "navig[github]"
+navig github --help
+```
+
+<details><summary>Commands</summary>
+
+| Command | What it does |
+|---|---|
+| `navig github analytics` | Analyze backup directory and generate statistics report. |
+| `navig github analytics-history` | Show backup history and statistics. |
+| `navig github attachments` | Download attachments (images, files) from issues and pull requests. |
+| `navig github backup` | 📦 Clone / mirror every repo for a user (or --org organisation). |
+| `navig github clone` | ⬇️  Clone a single repository (with the full toolbox if available, else plain git). |
+| `navig github config-delete` | Delete a saved backup profile. |
+| `navig github config-export` | Export a profile to a file for sharing. |
+| `navig github config-import` | Import a profile from a file. |
+| `navig github config-list` | List all saved backup profiles. |
+| `navig github config-load` | Load and display a saved backup profile. |
+| `navig github config-save` | Save a backup configuration profile. |
+| `navig github delete` | Delete a GitHub repository. |
+| `navig github diff` | Compare two backup directories and show differences. |
+| `navig github discussions` | Export all discussions from a GitHub repository. |
+| `navig github followers` | Export followers (and optionally following) for a GitHub user. |
+| `navig github gists` | Backup all gists for a user. |
+| `navig github issues` | Export all issues from a GitHub repository. |
+| `navig github labels` | Export all labels from a GitHub repository. |
+| `navig github milestones` | Export all milestones from a GitHub repository. |
+| `navig github notify-status` | Show notification configuration status. |
+| `navig github notify-test` | Test all configured notification providers. |
+| `navig github org` | Backup all repositories for a GitHub organization. |
+| `navig github profile` | Export GitHub user profile information. |
+| `navig github projects` | Export GitHub Projects (v2) for a user/org or repository. |
+| `navig github pulls` | Export all pull requests from a GitHub repository. |
+| `navig github releases` | Download all releases and assets from a GitHub repository. |
+| `navig github repo` | Backup a single GitHub repository with optional data exports. |
+| `navig github restore-issues` | Restore issues from a backup to a GitHub repository. |
+| `navig github restore-labels` | Restore labels from a backup to a GitHub repository. |
+| `navig github restore-milestones` | Restore milestones from a backup to a GitHub repository. |
+| `navig github restore-releases` | Restore releases from a backup to a GitHub repository. |
+| `navig github schedule-add` | Add a scheduled backup. |
+| `navig github schedule-list` | List all scheduled backups. |
+| `navig github schedule-remove` | Remove a scheduled backup. |
+| `navig github schedule-run` | Run the backup scheduler daemon. |
+| `navig github search` | 🔍 Search GitHub and clone matching repositories. |
+| `navig github secrets` | Export repository secrets (names only, not values). |
+| `navig github snapshot` | Create a snapshot of the current backup state for later comparison. |
+| `navig github starred` | Mirror all repositories starred by a user. |
+| `navig github status` | ℹ️  Show engine installation status and token configuration. |
+| `navig github template-create` | Create a custom backup template. |
+| `navig github template-delete` | Delete a custom template (built-in templates cannot be deleted). |
+| `navig github template-show` | Show details of a backup template. |
+| `navig github template-use` | Run a backup using a template. |
+| `navig github templates` | List available backup templates. |
+| `navig github token remove` | 🗑  Remove the stored GitHub token. |
+| `navig github token set` | 🔑 Save a GitHub token for navig github to use automatically. |
+| `navig github token show` | 🔍 Display where the current GitHub token comes from (masked). |
+| `navig github transfer` | Transfer repository(ies) to a GitHub organization. |
+| `navig github user` | Backup all repositories for a GitHub user. |
+| `navig github verify` | Verify backup integrity. |
+| `navig github watched` | Mirror all repositories watched by a user. |
+| `navig github webhooks` | Export webhooks configuration from a GitHub repository. |
+| `navig github wiki` | Backup a repository's wiki (if it exists). |
+| `navig github workflows` | Backup GitHub Actions workflows from a repository. |
+
+</details>
+
+<!-- navig:plugin-card:end -->
+
+NAVIG GitHub module — the **full GitHub toolbox** (backup, mirror, export, restore,
+analytics, scheduling) wired natively into `navig github`. A first-party navig plugin
+(free, toggleable).
+
+**License:** Apache-2.0 · **Version:** 0.2.0
+
+## What it is
+
+`navig-github` is a **first-party NAVIG plugin** — it extends NAVIG itself (CLI verbs +
+gateway routes), and it is free and toggleable. Plugins are different from
+*blocks*: a plugin adds capabilities to the platform; a block is an outcome you
+*apply* with `navig apply`.
+
+The GitHub engine is bundled in-package (`navig_github.engine`) and
+mounted **in-process**: every engine command is a `navig github` subcommand, and a
+group callback injects the vault token (`github_token`) into `GITHUB_TOKEN` so the
+whole surface authenticates automatically.
+
+```
+navig github token set <PAT>          # store the token in the navig vault, once
+navig github backup <user> -y         # mirror every repo (curated wrapper)
+navig github issues owner/repo        # export issues (in-process)
+navig github releases owner/repo      # download releases + assets
+navig github verify ./mirrors         # backup integrity check
+navig github --help                   # the full surface, grouped by panels
+```
+
+## Install
+
+It ships in the NAVIG monorepo and loads automatically when NAVIG is installed.
+To add/enable it explicitly:
+
+```
+navig plugin add navig-github
+```
+
+Check wiring and toggle state:
+
+```
+navig store list
+```
+
+## Development
+
+This package lives in the NAVIG monorepo under `plugins/navig-github/`. It registers via
+the `navig.plugins` entry-point group; CLI verbs register via `navig.commands`.

navig_github-0.3.0/README.md

@@ -0,0 +1,133 @@
+# navig-github
+
+<!-- navig:plugin-card:start -->
+<!-- Generated by scripts/gen_plugin_catalog.py — edit the plugin's pyproject.toml, not this block. -->
+
+> The full GitHub toolbox (backup, mirror, export, manage): its own navig-github command, and `navig github` inside navig.
+
+**Works on its own** — its own CLI, no navig required · v0.3.0 · [PyPI](https://pypi.org/project/navig-github/)
+
+**On its own** (no navig needed)
+
+```bash
+pip install navig-github
+navig-github --help   # no navig needed
+```
+
+**With navig**
+
+```bash
+pip install "navig[github]"
+navig github --help
+```
+
+<details><summary>Commands</summary>
+
+| Command | What it does |
+|---|---|
+| `navig github analytics` | Analyze backup directory and generate statistics report. |
+| `navig github analytics-history` | Show backup history and statistics. |
+| `navig github attachments` | Download attachments (images, files) from issues and pull requests. |
+| `navig github backup` | 📦 Clone / mirror every repo for a user (or --org organisation). |
+| `navig github clone` | ⬇️  Clone a single repository (with the full toolbox if available, else plain git). |
+| `navig github config-delete` | Delete a saved backup profile. |
+| `navig github config-export` | Export a profile to a file for sharing. |
+| `navig github config-import` | Import a profile from a file. |
+| `navig github config-list` | List all saved backup profiles. |
+| `navig github config-load` | Load and display a saved backup profile. |
+| `navig github config-save` | Save a backup configuration profile. |
+| `navig github delete` | Delete a GitHub repository. |
+| `navig github diff` | Compare two backup directories and show differences. |
+| `navig github discussions` | Export all discussions from a GitHub repository. |
+| `navig github followers` | Export followers (and optionally following) for a GitHub user. |
+| `navig github gists` | Backup all gists for a user. |
+| `navig github issues` | Export all issues from a GitHub repository. |
+| `navig github labels` | Export all labels from a GitHub repository. |
+| `navig github milestones` | Export all milestones from a GitHub repository. |
+| `navig github notify-status` | Show notification configuration status. |
+| `navig github notify-test` | Test all configured notification providers. |
+| `navig github org` | Backup all repositories for a GitHub organization. |
+| `navig github profile` | Export GitHub user profile information. |
+| `navig github projects` | Export GitHub Projects (v2) for a user/org or repository. |
+| `navig github pulls` | Export all pull requests from a GitHub repository. |
+| `navig github releases` | Download all releases and assets from a GitHub repository. |
+| `navig github repo` | Backup a single GitHub repository with optional data exports. |
+| `navig github restore-issues` | Restore issues from a backup to a GitHub repository. |
+| `navig github restore-labels` | Restore labels from a backup to a GitHub repository. |
+| `navig github restore-milestones` | Restore milestones from a backup to a GitHub repository. |
+| `navig github restore-releases` | Restore releases from a backup to a GitHub repository. |
+| `navig github schedule-add` | Add a scheduled backup. |
+| `navig github schedule-list` | List all scheduled backups. |
+| `navig github schedule-remove` | Remove a scheduled backup. |
+| `navig github schedule-run` | Run the backup scheduler daemon. |
+| `navig github search` | 🔍 Search GitHub and clone matching repositories. |
+| `navig github secrets` | Export repository secrets (names only, not values). |
+| `navig github snapshot` | Create a snapshot of the current backup state for later comparison. |
+| `navig github starred` | Mirror all repositories starred by a user. |
+| `navig github status` | ℹ️  Show engine installation status and token configuration. |
+| `navig github template-create` | Create a custom backup template. |
+| `navig github template-delete` | Delete a custom template (built-in templates cannot be deleted). |
+| `navig github template-show` | Show details of a backup template. |
+| `navig github template-use` | Run a backup using a template. |
+| `navig github templates` | List available backup templates. |
+| `navig github token remove` | 🗑  Remove the stored GitHub token. |
+| `navig github token set` | 🔑 Save a GitHub token for navig github to use automatically. |
+| `navig github token show` | 🔍 Display where the current GitHub token comes from (masked). |
+| `navig github transfer` | Transfer repository(ies) to a GitHub organization. |
+| `navig github user` | Backup all repositories for a GitHub user. |
+| `navig github verify` | Verify backup integrity. |
+| `navig github watched` | Mirror all repositories watched by a user. |
+| `navig github webhooks` | Export webhooks configuration from a GitHub repository. |
+| `navig github wiki` | Backup a repository's wiki (if it exists). |
+| `navig github workflows` | Backup GitHub Actions workflows from a repository. |
+
+</details>
+
+<!-- navig:plugin-card:end -->
+
+NAVIG GitHub module — the **full GitHub toolbox** (backup, mirror, export, restore,
+analytics, scheduling) wired natively into `navig github`. A first-party navig plugin
+(free, toggleable).
+
+**License:** Apache-2.0 · **Version:** 0.2.0
+
+## What it is
+
+`navig-github` is a **first-party NAVIG plugin** — it extends NAVIG itself (CLI verbs +
+gateway routes), and it is free and toggleable. Plugins are different from
+*blocks*: a plugin adds capabilities to the platform; a block is an outcome you
+*apply* with `navig apply`.
+
+The GitHub engine is bundled in-package (`navig_github.engine`) and
+mounted **in-process**: every engine command is a `navig github` subcommand, and a
+group callback injects the vault token (`github_token`) into `GITHUB_TOKEN` so the
+whole surface authenticates automatically.
+
+```
+navig github token set <PAT>          # store the token in the navig vault, once
+navig github backup <user> -y         # mirror every repo (curated wrapper)
+navig github issues owner/repo        # export issues (in-process)
+navig github releases owner/repo      # download releases + assets
+navig github verify ./mirrors         # backup integrity check
+navig github --help                   # the full surface, grouped by panels
+```
+
+## Install
+
+It ships in the NAVIG monorepo and loads automatically when NAVIG is installed.
+To add/enable it explicitly:
+
+```
+navig plugin add navig-github
+```
+
+Check wiring and toggle state:
+
+```
+navig store list
+```
+
+## Development
+
+This package lives in the NAVIG monorepo under `plugins/navig-github/`. It registers via
+the `navig.plugins` entry-point group; CLI verbs register via `navig.commands`.

navig_github-0.3.0/navig_github/_typed_path.py

@@ -0,0 +1,28 @@
+"""Resolve a path the operator TYPED against the directory they typed it in.
+
+``navig`` chdir's into the active space before a command runs, so a relative path
+resolved with a bare ``Path(x)`` lands inside the space, not where the operator stands.
+Core's ``navig.platform.paths.resolve_user_path`` fixes that; this shim uses it when the
+installed core has it and otherwise reads the same ``NAVIG_INVOCATION_CWD`` variable, so
+the plugin keeps working against an older core (and standalone, where cwd is correct).
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+try:
+    from navig.platform.paths import resolve_user_path
+except ImportError:  # core older than the helper
+
+    def resolve_user_path(given: Path | str) -> Path:
+        p = Path(given).expanduser()
+        if p.is_absolute():
+            return p.resolve()
+        origin = os.environ.get("NAVIG_INVOCATION_CWD")
+        base = Path(origin) if origin and Path(origin).is_dir() else Path.cwd()
+        return (base / p).resolve()
+
+
+__all__ = ["resolve_user_path"]

navig_github-0.3.0/navig_github/cli.py

@@ -0,0 +1,19 @@
+"""Standalone entry point for the ``navig-github`` console script.
+
+Installs and runs without navig: the same ``github_app`` Typer app navig mounts as
+``navig github``. One command surface, two front doors.
+"""
+
+from __future__ import annotations
+
+from navig_sdk.cli import run
+
+from navig_github.commands.github import github_app
+
+
+def main() -> None:
+    run(github_app, "navig-github")
+
+
+if __name__ == "__main__":
+    main()

{navig_github-0.2.4 → navig_github-0.3.0}/navig_github/commands/github.py

@@ -16,6 +16,7 @@ Token resolution order:
   4. No token → public repos only (curated `clone` falls back to plain git)
 """
 
+import importlib
 import os
 import subprocess
 from pathlib import Path
@@ -23,11 +24,17 @@ from typing import Annotated
 
 import typer
 
-from navig.core.yaml_io import load_yaml_for_update, safe_load_yaml
-from navig.lazy_loader import lazy_import
-from navig.platform.paths import config_dir
+# navig-sdk, not navig.*: this plugin runs as `navig github` inside navig AND as its own
+# `navig-github` command with no navig installed. Each helper is navig's own when navig is
+# present, and a faithful standalone copy when it is not.
+from navig_sdk import console as ch
+from navig_sdk.files import atomic_write_yaml, load_yaml_for_update, safe_load_yaml
+from navig_sdk.host import config_dir, navig_available
 
-ch = lazy_import("navig.console_helper")
+
+def _cmd() -> str:
+    """How the user invokes this tool here: `navig github` inside navig, else `navig-github`."""
+    return "navig github" if navig_available() else "navig-github"
 
 github_app = typer.Typer(
     name="github",
@@ -63,27 +70,9 @@ def _resolve_github_token() -> str | None:
     Returns None if not found anywhere.
     """
     # 1 — navig vault
-    try:
-        from navig.vault import get_vault  # type: ignore
-
-        vault = get_vault()
-        secret = vault.get("github_token", caller="navig-github")
-        if secret is not None:
-            # Credential exposes the decrypted payload via `.data` / `.get_secret()`
-            # — there is NO `.value` attribute. The token is stored under "value"
-            # (also accept "token"/"api_key" for older entries).
-            tok = None
-            data = getattr(secret, "data", None)
-            if isinstance(data, dict):
-                tok = data.get("value") or data.get("token") or data.get("api_key")
-            if not tok and hasattr(secret, "get_secret"):
-                tok = secret.get_secret("value") or secret.get_secret("token")
-            if not tok:
-                tok = getattr(secret, "value", None)
-            if tok:
-                return str(tok)
-    except Exception:  # noqa: BLE001
-        pass  # best-effort; failure is non-critical
+    tok = _vault_token()
+    if tok:
+        return tok
 
     # 2 — env var
     token = os.environ.get("GITHUB_TOKEN", "").strip()
@@ -103,6 +92,32 @@ def _resolve_github_token() -> str | None:
     return None
 
 
+def _vault_token(caller: str = "navig-github") -> str | None:
+    """The token stored in the shared navig vault (`github_token`), or None.
+
+    navig-vault is its own package, so this works with or without navig; with navig
+    installed it is the very vault navig reads.
+    """
+    try:
+        from navig_vault.core import get_vault
+
+        secret = get_vault().get("github_token", caller=caller)
+    except Exception:  # noqa: BLE001 - no vault / locked vault = no token, never a crash
+        return None
+    if secret is None:
+        return None
+    # A Credential exposes its payload via `.data` / `.get_secret()` — there is NO
+    # `.value` attribute. The token is stored under "value" ("token"/"api_key" for
+    # older entries).
+    tok = None
+    data = getattr(secret, "data", None)
+    if isinstance(data, dict):
+        tok = data.get("value") or data.get("token") or data.get("api_key")
+    if not tok and hasattr(secret, "get_secret"):
+        tok = secret.get_secret("value") or secret.get_secret("token")
+    return str(tok) if tok else None
+
+
 def _engine_available() -> bool:
     """Return True if the bundled GitHub engine is importable."""
     try:
@@ -138,21 +153,25 @@ def _run_engine(args: list[str], token: str | None) -> None:
     if token:
         os.environ["GITHUB_TOKEN"] = token
 
-    import click
-    from navig_github.engine.cli import app as engine_cli
     from typer.main import get_command
 
+    from navig_github.engine.cli import app as engine_cli
+
+    # the click Typer runs on — Typer 0.27 vendors it and ships no `click` package, so take
+    # it from Typer's own Context base class (what navig.core.click_compat does).
+    click_pkg = typer.Context.__mro__[1].__module__.rsplit(".", 1)[0]
+    _click_exc = importlib.import_module(f"{click_pkg}.exceptions")
     cmd = get_command(engine_cli)
     try:
-        cmd.main(list(args), prog_name="navig github", standalone_mode=False)
-    except click.exceptions.Exit as exc:  # typer.Exit inside the engine lands here
+        cmd.main(list(args), prog_name=_cmd(), standalone_mode=False)
+    except typer.Exit as exc:  # typer.Exit inside the engine lands here
         code = exc.exit_code or 0
         if code:
             raise typer.Exit(code) from None
-    except click.exceptions.Abort:
+    except _click_exc.Abort:
         ch.warning("Aborted.")
         raise typer.Exit(1) from None
-    except click.ClickException as exc:
+    except _click_exc.ClickException as exc:
         exc.show()
         raise typer.Exit(exc.exit_code) from None
     except KeyboardInterrupt:
@@ -252,7 +271,7 @@ def gh_search(
     if not resolved_token:
         ch.warning(
             "No GitHub token found. Using unauthenticated access (60 req/hour).\n"
-            "Set one with:  navig github token set <your-token>"
+            f"Set one with:  {_cmd()} token set <your-token>"
         )
 
     if not _require_engine():
@@ -312,7 +331,7 @@ def gh_backup(
     if not resolved_token:
         ch.warning(
             "No GitHub token found — only public repos accessible.\n"
-            "Set a token with:  navig github token set <your-token>"
+            f"Set a token with:  {_cmd()} token set <your-token>"
         )
 
     if not _require_engine():
@@ -400,7 +419,7 @@ def token_set(
     """
     if use_vault:
         try:
-            from navig.vault import get_vault  # type: ignore
+            from navig_vault.core import get_vault
 
             vault = get_vault()
             existing = vault.get("github_token", caller="navig-github.token_set")
@@ -425,8 +444,6 @@ def token_set(
         cfg_path.parent.mkdir(parents=True, exist_ok=True)
         cfg = load_yaml_for_update(cfg_path)
         cfg.setdefault("github", {})["token"] = value
-        from navig.core.yaml_io import atomic_write_yaml
-
         atomic_write_yaml(cfg, cfg_path)
         ch.success(f"GitHub token saved to {cfg_path}")
     except Exception as exc:
@@ -447,16 +464,9 @@ def token_show():
         masked = token[:6] + "..." + token[-4:]
         ch.success(f"GitHub token found: {masked}")
         # Identify source
-        try:
-            from navig.vault import get_vault  # type: ignore
-
-            v = get_vault()
-            s = v.get("github_token", caller="navig-github.token_show")
-            if s and getattr(s, "value", None) == token:
-                ch.info("Source: navig vault")
-                return
-        except Exception:  # noqa: BLE001
-            pass  # best-effort; failure is non-critical
+        if _vault_token("navig-github.token_show") == token:
+            ch.info("Source: navig vault")
+            return
         if os.environ.get("GITHUB_TOKEN", "").strip() == token:
             ch.info("Source: GITHUB_TOKEN env var")
         else:
@@ -464,8 +474,8 @@ def token_show():
     else:
         ch.warning(
             "No GitHub token configured.\n"
-            "Set one with:  navig github token set <your-token>\n"
-            "Without a token, navig github only accesses public repos at low rate limits."
+            f"Set one with:  {_cmd()} token set <your-token>\n"
+            "Without a token, only public repos are reachable, at low rate limits."
         )
 
 
@@ -481,7 +491,7 @@ def token_remove():
 
     # Vault
     try:
-        from navig.vault import get_vault  # type: ignore
+        from navig_vault.core import get_vault
 
         vault = get_vault()
         secret = vault.get("github_token", caller="navig-github.token_remove")
@@ -499,8 +509,6 @@ def token_remove():
             cfg = load_yaml_for_update(cfg_path)
             if cfg.get("github", {}).get("token"):
                 cfg["github"].pop("token")
-                from navig.core.yaml_io import atomic_write_yaml
-
                 atomic_write_yaml(cfg, cfg_path)
                 ch.success(f"GitHub token removed from {cfg_path}")
                 removed = True
@@ -542,7 +550,7 @@ def gh_status():
     else:
         ch.warning(
             "No GitHub token — only public repos accessible at low rate limits.\n"
-            "Set one with:  navig github token set <your-token>"
+            f"Set one with:  {_cmd()} token set <your-token>"
         )
 
     if engine_missing:

{navig_github-0.2.4 → navig_github-0.3.0}/navig_github/engine/analytics.py

@@ -12,7 +12,7 @@ from datetime import datetime
 from pathlib import Path
 from typing import Any
 
-from navig.core.json_io import JsonReadError, atomic_write_json, load_json_for_update
+from navig_sdk.files import JsonReadError, atomic_write_json, load_json_for_update
 
 
 @dataclass