netbox-super-cli 1.0.0__py3-none-any.whl

nsc/cli/app.py

@@ -0,0 +1,291 @@
+"""Root Typer application."""
+
+from __future__ import annotations
+
+from typing import Annotated, Any
+
+import click
+import typer
+from typer.core import TyperGroup
+from typer.main import get_group, get_group_from_info
+
+from nsc._version import __version__
+from nsc.cli import (
+    aliases_commands,
+    cache_commands,
+    commands_dump,
+    config_commands,
+    init_commands,
+    login_commands,
+    profiles_commands,
+    skill_commands,
+)
+from nsc.cli.globals import GlobalState, build_runtime_context
+from nsc.cli.registration import register_dynamic_commands
+from nsc.cli.runtime import (
+    CLIOverrides,
+    NoProfileError,
+    RuntimeContext,
+    UnknownProfileError,
+    emit_envelope,
+    map_error,
+)
+from nsc.config import default_paths
+from nsc.config.loader import ConfigParseError, load_config
+from nsc.config.models import Config, OutputFormat
+from nsc.http.errors import NetBoxAPIError, NetBoxClientError
+from nsc.schema.source import SchemaSourceError
+
+# Mutable dict used as a single-slot holder to avoid `global` statements.
+# Keys: "runtime" -> RuntimeContext | None, "error" -> Exception | None.
+_invocation: dict[str, object] = {"runtime": None, "error": None}
+
+# Static subcommands that do not need a profile.
+_META_COMMANDS: frozenset[str] = frozenset(
+    {"cache", "commands", "config", "init", "login", "profiles", "skill"}
+)
+
+# Populated at module-load time (after all static `register()` calls) so that
+# make_context can tear down dynamically-added commands before each invocation.
+# See the bottom of this module where these are assigned.
+_static_groups_count: int = 0  # sentinel; set after `app` is created
+_static_command_names: frozenset[str] = frozenset()
+
+
+def _extract_global_overrides(args: list[str]) -> CLIOverrides:
+    """Scan raw argv for global flags without consuming the full Click context."""
+    kwargs: dict[str, object] = {}
+    two_arg = {
+        "--profile": "profile",
+        "--url": "url",
+        "--token": "token",
+        "--schema": "schema_override",
+        "--output": "output",
+        "-o": "output",
+    }
+    i = 0
+    while i < len(args):
+        a = args[i]
+        if a.startswith("--") and "=" in a:
+            flag, _, value = a.partition("=")
+            if flag in two_arg:
+                kwargs[two_arg[flag]] = value
+            i += 1
+            continue
+        if a in two_arg and i + 1 < len(args):
+            kwargs[two_arg[a]] = args[i + 1]
+            i += 2
+            continue
+        if a == "--insecure":
+            kwargs["insecure"] = True
+            i += 1
+            continue
+        if a == "--no-insecure":
+            kwargs["insecure"] = False
+            i += 1
+            continue
+        i += 1
+    return CLIOverrides(**kwargs)  # type: ignore[arg-type]
+
+
+def _first_non_option(args: list[str]) -> str | None:
+    """Return the first arg that looks like a subcommand name (not a flag/value)."""
+    skip_next = False
+    skip_flags = {
+        "--profile",
+        "--url",
+        "--token",
+        "--schema",
+        "--output",
+        "-o",
+    }
+    for a in args:
+        if skip_next:
+            skip_next = False
+            continue
+        if a in skip_flags:
+            skip_next = True
+            continue
+        if a.startswith("-"):
+            continue
+        return a
+    return None
+
+
+class _BootstrappingGroup(TyperGroup):
+    """TyperGroup subclass that registers dynamic commands before dispatch.
+
+    Overrides `make_context` (called once per invocation, before `resolve_command`)
+    so dynamic Typer commands are visible to Click's command resolver.
+    """
+
+    def make_context(
+        self,
+        info_name: str | None,
+        args: list[str],
+        parent: click.Context | None = None,
+        **extra: Any,
+    ) -> click.Context:
+        _invocation["runtime"] = None
+        _invocation["error"] = None
+
+        # Tear down any dynamic commands registered by a previous invocation so
+        # that each call to `app(...)` (e.g. consecutive CliRunner.invoke calls
+        # in tests) starts from a clean static baseline.  Without this, commands
+        # like `dcim` that were registered during an earlier invocation remain in
+        # `self.commands` and bypass the bootstrap-error path of `resolve_command`.
+        del app.registered_groups[_static_groups_count:]
+        for name in list(self.commands):
+            if name not in _static_command_names:
+                del self.commands[name]
+
+        subcommand = _first_non_option(args)
+
+        if subcommand not in _META_COMMANDS:
+            overrides = _extract_global_overrides(args)
+            debug = "--debug" in args
+            try:
+                config = load_config(default_paths().config_file)
+            except ConfigParseError as exc:
+                _invocation["error"] = exc
+                return super().make_context(info_name, args, parent, **extra)
+
+            state = GlobalState(overrides=overrides, config=config, debug=debug)
+
+            try:
+                runtime = build_runtime_context(state)
+            except (NoProfileError, UnknownProfileError, SchemaSourceError) as exc:
+                _invocation["error"] = exc
+                return super().make_context(info_name, args, parent, **extra)
+
+            _invocation["runtime"] = runtime
+            # `app` is defined after this class; by call time it is available.
+            register_dynamic_commands(app, runtime.command_model, lambda: runtime)
+            # Sync newly added Typer sub-apps into this Click group's commands
+            # dict. Typer builds its Click group once at invocation time from
+            # `app.registered_groups`; commands added inside `make_context`
+            # would otherwise be invisible to `resolve_command`.
+            for group_info in app.registered_groups:
+                sub = get_group_from_info(
+                    group_info,
+                    pretty_exceptions_short=app.pretty_exceptions_short,
+                    rich_markup_mode=app.rich_markup_mode,
+                    suggest_commands=app.suggest_commands,
+                )
+                if sub.name and sub.name not in self.commands:
+                    self.commands[sub.name] = sub
+
+        return super().make_context(info_name, args, parent, **extra)
+
+    def resolve_command(
+        self, ctx: click.Context, args: list[str]
+    ) -> tuple[str | None, click.Command | None, list[str]]:
+        # Surface a bootstrap error when the requested command was not registered
+        # (because bootstrap failed). SchemaSourceError exits 3 per spec; all
+        # other bootstrap errors are usage errors (exit 2).
+        error = _invocation["error"]
+        if error is not None and args and args[0] not in self.commands:
+            if isinstance(error, SchemaSourceError):
+                # Exit code 3 matches EXIT_CODES[ErrorType.SCHEMA] — keep in sync.
+                typer.echo(f"Error: {error}", err=True)
+                raise typer.Exit(3)
+            ctx.fail(str(error))
+        return super().resolve_command(ctx, args)
+
+
+app = typer.Typer(
+    name="nsc",
+    help="netbox-super-cli — dynamic NetBox CLI driven by the live OpenAPI schema.",
+    no_args_is_help=True,
+    add_completion=True,
+    cls=_BootstrappingGroup,
+)
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        typer.echo(f"nsc {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def _root(
+    ctx: typer.Context,
+    version: Annotated[
+        bool,
+        typer.Option(
+            "--version",
+            callback=_version_callback,
+            is_eager=True,
+            help="Show the nsc version and exit.",
+        ),
+    ] = False,
+    profile: Annotated[str | None, typer.Option("--profile")] = None,
+    url: Annotated[str | None, typer.Option("--url")] = None,
+    token: Annotated[str | None, typer.Option("--token")] = None,
+    insecure: Annotated[bool | None, typer.Option("--insecure/--no-insecure")] = None,
+    schema: Annotated[str | None, typer.Option("--schema")] = None,
+    output: Annotated[str | None, typer.Option("--output", "-o")] = None,
+    debug: Annotated[bool, typer.Option("--debug")] = False,
+) -> None:
+    """Root callback — global options live here."""
+    overrides = CLIOverrides(
+        profile=profile,
+        url=url,
+        token=token,
+        insecure=insecure,
+        schema_override=schema,
+        output=output,
+    )
+    try:
+        config = load_config(default_paths().config_file)
+    except ConfigParseError as exc:
+        if ctx.invoked_subcommand in ("cache", "init", "login", "profiles", "skill"):
+            config = Config()
+        else:
+            typer.echo(f"Error: {exc}", err=True)
+            raise typer.Exit(2) from exc
+
+    state = GlobalState(overrides=overrides, config=config, debug=debug)
+    ctx.obj = state
+
+    if ctx.invoked_subcommand in _META_COMMANDS or ctx.invoked_subcommand is None:
+        return
+
+    runtime = _invocation["runtime"]
+    if isinstance(runtime, RuntimeContext):
+        ctx.obj = (state, runtime)
+
+
+cache_commands.register(app)
+commands_dump.register(app)
+config_commands.register(app)
+init_commands.register(app)
+login_commands.register(app)
+profiles_commands.register(app)
+aliases_commands.register(app)
+skill_commands.register(app)
+
+# Capture the static baseline AFTER all static sub-apps are registered so that
+# make_context can restore this state at the start of every invocation.
+_static_groups_count = len(app.registered_groups)
+_static_command_names = frozenset(get_group(app).commands.keys())
+
+
+def main() -> None:
+    try:
+        app()
+    except typer.Exit:
+        raise
+    except (NetBoxAPIError, NetBoxClientError) as exc:
+        env = map_error(exc)
+        code = emit_envelope(env, output_format=OutputFormat.TABLE)
+        raise typer.Exit(code) from exc
+    except Exception as exc:  # catch-all to produce internal envelope
+        env = map_error(exc)
+        code = emit_envelope(env, output_format=OutputFormat.TABLE)
+        raise typer.Exit(code) from exc
+
+
+if __name__ == "__main__":
+    main()

nsc/cli/cache_commands.py

@@ -0,0 +1,159 @@
+"""`nsc cache` — local cache management. Phase 5a ships `prune`."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Callable
+from enum import StrEnum
+from typing import Annotated
+
+import httpx
+import typer
+
+from nsc.cache.store import (
+    CacheStore,
+    PrunePlan,
+    PruneResult,
+    compute_prune_plan,
+    prune_orphans,
+)
+from nsc.config.loader import ConfigParseError, load_config
+from nsc.config.models import Config, Profile
+from nsc.config.settings import default_paths
+from nsc.schema.hashing import canonical_sha256
+
+_PRUNE_FETCH_TIMEOUT_SECONDS = 5.0
+"""Per-profile timeout when fetching the live schema for stale-hash classification.
+Deliberately tighter than `Config.defaults.timeout` (30s): cache prune is a fast
+cleanup tool, and an unreachable profile must not stall the operation."""
+
+
+class _OutputFormat(StrEnum):
+    TABLE = "table"
+    JSON = "json"
+
+
+def _store() -> CacheStore:
+    return CacheStore(root=default_paths().cache_dir)
+
+
+def _load_config_or_empty() -> Config:
+    try:
+        return load_config(default_paths().config_file)
+    except (FileNotFoundError, ConfigParseError):
+        return Config()
+
+
+def _fetch_live_hash(profile: Profile, *, default_timeout: float) -> str:
+    url = str(profile.url).rstrip("/") + "/api/schema/?format=json"
+    headers = {"Accept": "application/json"}
+    if profile.token:
+        headers["Authorization"] = f"Token {profile.token}"
+    timeout = profile.timeout if profile.timeout is not None else default_timeout
+    with httpx.Client(verify=profile.verify_ssl, timeout=timeout, headers=headers) as c:
+        resp = c.get(url)
+        resp.raise_for_status()
+        return canonical_sha256(resp.content)
+
+
+def _make_fetcher(default_timeout: float) -> Callable[[Profile], str]:
+    def fetcher(profile: Profile) -> str:
+        return _fetch_live_hash(profile, default_timeout=default_timeout)
+
+    return fetcher
+
+
+def _render_table(plan: PrunePlan, mode: str, result: PruneResult | None) -> str:
+    lines: list[str] = []
+    if mode == "dry-run":
+        lines.append("nsc cache prune (dry-run) — pass --apply to delete")
+    else:
+        lines.append("nsc cache prune (applied)")
+    if plan.orphan_profile_dirs:
+        lines.append("  orphan profile directories:")
+        for d in plan.orphan_profile_dirs:
+            lines.append(f"    {d}")
+    if plan.stale_hash_files:
+        lines.append("  stale-hash files:")
+        for f in plan.stale_hash_files:
+            lines.append(f"    {f}")
+    if plan.aged_files:
+        lines.append("  aged-out files:")
+        for f in plan.aged_files:
+            lines.append(f"    {f}")
+    if plan.total_count() == 0:
+        lines.append("  nothing to prune")
+    if mode == "dry-run":
+        lines.append(f"  would free: {plan.total_bytes()} bytes")
+    elif result is not None:
+        lines.append(
+            f"  freed: {result.freed_bytes} bytes "
+            f"({result.deleted_dirs} dir(s), {result.deleted_files} file(s))"
+        )
+    return "\n".join(lines)
+
+
+def _render_json(plan: PrunePlan, mode: str, result: PruneResult | None) -> str:
+    payload: dict[str, object] = {
+        "mode": mode,
+        "plan": {
+            "orphan_profile_dirs": [str(p) for p in plan.orphan_profile_dirs],
+            "stale_hash_files": [str(p) for p in plan.stale_hash_files],
+            "aged_files": [str(p) for p in plan.aged_files],
+            "total_count": plan.total_count(),
+        },
+    }
+    if mode == "dry-run":
+        payload["would_free_bytes"] = plan.total_bytes()
+    elif result is not None:
+        payload["result"] = {
+            "deleted_dirs": result.deleted_dirs,
+            "deleted_files": result.deleted_files,
+            "freed_bytes": result.freed_bytes,
+        }
+    return json.dumps(payload)
+
+
+def register(app: typer.Typer) -> None:
+    cache_app = typer.Typer(
+        name="cache",
+        help="Manage the on-disk command-model cache.",
+        no_args_is_help=True,
+    )
+
+    @cache_app.command("prune")
+    def prune_cmd(
+        apply_: Annotated[
+            bool, typer.Option("--apply", help="Actually delete (default: dry-run).")
+        ] = False,
+        max_age: Annotated[
+            int | None,
+            typer.Option(
+                "--max-age",
+                help="Also prune cache files older than N days.",
+                min=1,
+            ),
+        ] = None,
+        output: Annotated[
+            _OutputFormat,
+            typer.Option("--output", "-o", help="table|json"),
+        ] = _OutputFormat.TABLE,
+    ) -> None:
+        config = _load_config_or_empty()
+        store = _store()
+        fetcher = _make_fetcher(default_timeout=_PRUNE_FETCH_TIMEOUT_SECONDS)
+        plan = compute_prune_plan(
+            config=config,
+            store=store,
+            fetch_live_hash=fetcher,
+            max_age_days=max_age,
+        )
+        mode = "apply" if apply_ else "dry-run"
+        result = prune_orphans(plan) if apply_ else None
+
+        if output is _OutputFormat.JSON:
+            typer.echo(_render_json(plan, mode, result))
+        else:
+            typer.echo(_render_table(plan, mode, result))
+
+    app.add_typer(cache_app, name="cache")

nsc/cli/commands_dump.py

@@ -0,0 +1,57 @@
+"""`nsc commands` — dump the generated CommandModel as JSON.
+
+In Phase 1 this is the only useful subcommand. It exists so an agent or human
+can see exactly what the schema-derived command tree would look like, without
+needing the dynamic Typer registration that Phase 2 will add.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from enum import StrEnum
+
+import typer
+
+from nsc.builder.build import build_command_model
+from nsc.schema.loader import SchemaLoadError, load_schema
+
+
+class _Output(StrEnum):
+    JSON = "json"
+
+
+def register(app: typer.Typer) -> None:
+    @app.command("commands")
+    def commands_dump(
+        schema: str = typer.Option(
+            ...,
+            "--schema",
+            help="Path or URL to an OpenAPI schema. Required in Phase 1.",
+        ),
+        output: _Output = typer.Option(  # noqa: B008
+            _Output.JSON,
+            "--output",
+            "-o",
+            help="Output format. Phase 1 supports `json` only.",
+        ),
+        compact: bool = typer.Option(
+            False,
+            "--compact",
+            help="Emit a single-line JSON object instead of indented output.",
+        ),
+    ) -> None:
+        """Dump the schema-derived command tree."""
+        try:
+            loaded = load_schema(schema)
+        except SchemaLoadError as exc:
+            typer.echo(f"error: {exc}", err=True)
+            raise typer.Exit(code=2) from exc
+
+        model = build_command_model(loaded)
+
+        if output is _Output.JSON:
+            indent = None if compact else 2
+            payload = json.loads(model.model_dump_json())
+            json.dump(payload, sys.stdout, indent=indent, sort_keys=False)
+            sys.stdout.write("\n")

nsc/cli/config_commands.py

@@ -0,0 +1,156 @@
+"""`nsc config` — read/write the user's `~/.nsc/config.yaml`.
+
+Phase 4a ships read commands (`get`, `list`, `path`) and write commands
+(`set`, `unset`, `edit`). Storage is driven by `nsc/config/writer.py` and
+preserves comments + `!env` tags through round trips.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+from pathlib import Path
+
+import typer
+from ruamel.yaml.comments import CommentedMap
+
+from nsc.config.settings import default_paths
+from nsc.config.writer import (
+    ConfigWriteError,
+    acquire_lock,
+    atomic_write,
+    dump_round_trip,
+    load_round_trip,
+    set_path,
+    unset_path,
+)
+
+
+def _config_path() -> Path:
+    return default_paths().config_file
+
+
+def _get_at(doc: CommentedMap, dotted: str) -> object:
+    cursor: object = doc
+    for key in [p for p in dotted.split(".") if p]:
+        if not isinstance(cursor, CommentedMap) or key not in cursor:
+            raise KeyError(dotted)
+        cursor = cursor[key]
+    return cursor
+
+
+def _path_cmd() -> None:
+    """Print the resolved config-file path."""
+    typer.echo(str(_config_path()))
+
+
+def _get_cmd(key: str) -> None:
+    """Print the value at the given dotted path."""
+    doc = load_round_trip(_config_path())
+    try:
+        value = _get_at(doc, key)
+    except KeyError:
+        typer.echo(f"error: no such key: {key}", err=True)
+        raise typer.Exit(code=1) from None
+    if isinstance(value, CommentedMap):
+        typer.echo(dump_round_trip(value), nl=False)
+    else:
+        typer.echo(str(value))
+
+
+def _list_cmd() -> None:
+    """Print the entire config file."""
+    doc = load_round_trip(_config_path())
+    typer.echo(dump_round_trip(doc), nl=False)
+
+
+def _set_cmd(key: str, value: str) -> None:
+    """Set the value at the given dotted path. Creates parents as needed."""
+    path = _config_path()
+    with acquire_lock(path):
+        doc = load_round_trip(path)
+        try:
+            set_path(doc, key, value)
+        except ConfigWriteError as exc:
+            typer.echo(f"error: {exc}", err=True)
+            raise typer.Exit(code=1) from exc
+        atomic_write(path, dump_round_trip(doc))
+
+
+def _unset_cmd(key: str) -> None:
+    """Remove the leaf at the given dotted path. Prunes empty parents."""
+    path = _config_path()
+    with acquire_lock(path):
+        doc = load_round_trip(path)
+        try:
+            unset_path(doc, key)
+        except ConfigWriteError as exc:
+            typer.echo(f"error: {exc}", err=True)
+            raise typer.Exit(code=1) from exc
+        atomic_write(path, dump_round_trip(doc))
+
+
+def _edit_cmd() -> None:
+    """Open the config file in $EDITOR."""
+    path = _config_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    if not path.exists():
+        atomic_write(path, "")
+    editor = os.environ.get("EDITOR") or os.environ.get("VISUAL")
+    if not editor:
+        editor = shutil.which("vi") or shutil.which("nano")
+    if not editor:
+        typer.echo(
+            "error: $EDITOR not set and no fallback editor (vi/nano) found",
+            err=True,
+        )
+        raise typer.Exit(code=1)
+    subprocess.run([editor, str(path)], check=True)
+
+
+def register(app: typer.Typer) -> None:
+    config_app = typer.Typer(
+        name="config",
+        help="Read and edit ~/.nsc/config.yaml.",
+        no_args_is_help=True,
+    )
+
+    @config_app.command("path")
+    def path_cmd() -> None:
+        """Print the resolved config-file path."""
+        _path_cmd()
+
+    @config_app.command("get")
+    def get_cmd(
+        key: str = typer.Argument(..., help="Dotted path, e.g. profiles.prod.url"),
+    ) -> None:
+        """Print the value at the given dotted path."""
+        _get_cmd(key)
+
+    @config_app.command("list")
+    def list_cmd() -> None:
+        """Print the entire config file."""
+        _list_cmd()
+
+    @config_app.command("set")
+    def set_cmd(
+        key: str = typer.Argument(..., help="Dotted path"),
+        value: str = typer.Argument(..., help="Value (string)"),
+    ) -> None:
+        """Set the value at the given dotted path. Creates parents as needed."""
+        _set_cmd(key, value)
+
+    @config_app.command("unset")
+    def unset_cmd(
+        key: str = typer.Argument(..., help="Dotted path to remove"),
+    ) -> None:
+        """Remove the leaf at the given dotted path. Prunes empty parents."""
+        _unset_cmd(key)
+
+    @config_app.command("edit")
+    def edit_cmd() -> None:
+        """Open the config file in $EDITOR."""
+        _edit_cmd()
+
+    app.add_typer(config_app)