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

nsc/cli/init_commands.py

@@ -0,0 +1,95 @@
+"""`nsc init` — first-run wizard.
+
+Prompts for a profile name, URL, and token storage mode, then writes a minimal
+`~/.nsc/config.yaml`. Refuses to clobber an existing non-empty config (spec §4.2);
+the user should `nsc login --new --profile <name>` to add a profile to an
+existing config instead.
+
+`init` is offline-safe: it does not call `verify()` — that is `login`'s job.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+from ruamel.yaml.comments import CommentedMap, TaggedScalar
+
+from nsc.config.settings import default_paths
+from nsc.config.writer import (
+    ConfigWriteError,
+    acquire_lock,
+    atomic_write,
+    dump_round_trip,
+    load_round_trip,
+)
+
+
+def _config_path() -> Path:
+    return default_paths().config_file
+
+
+def _existing_is_empty(path: Path) -> bool:
+    """True only when the file parses as an empty mapping; malformed → False.
+
+    A malformed pre-existing config is more worth refusing to clobber, not less —
+    so any parse failure is treated as 'present and non-empty.'
+    """
+    try:
+        existing = load_round_trip(path)
+    except ConfigWriteError:
+        return False
+    return len(existing) == 0
+
+
+def _build_doc(
+    profile_name: str,
+    url: str,
+    token_value: object,
+) -> CommentedMap:
+    """Produce the minimal config doc for a fresh init run."""
+    profiles = CommentedMap()
+    profile = CommentedMap()
+    profile["url"] = url
+    profile["token"] = token_value
+    profiles[profile_name] = profile
+
+    doc = CommentedMap()
+    doc["default_profile"] = profile_name
+    doc["profiles"] = profiles
+    return doc
+
+
+def _env_tagged(var_name: str) -> object:
+    """Build a `!env <VARNAME>` scalar that ruamel will emit with its tag intact."""
+    return TaggedScalar(value=var_name, style=None, tag="!env")
+
+
+def register(app: typer.Typer) -> None:
+    @app.command("init", help="First-run wizard — create ~/.nsc/config.yaml.")
+    def init_cmd() -> None:
+        path = _config_path()
+        if path.exists() and not _existing_is_empty(path):
+            typer.echo(
+                f"error: config already exists at {path}; use `nsc login --new` to add a profile.",
+                err=True,
+            )
+            raise typer.Exit(code=12)
+
+        profile_name = typer.prompt("Profile name", default="default")
+        url = typer.prompt("NetBox URL (e.g. https://netbox.example.com/)")
+        storage = typer.prompt("Token storage [plaintext|env]", default="plaintext").strip().lower()
+        token_value: object
+        if storage == "env":
+            var_name = typer.prompt("Environment variable name (e.g. NSC_PROD_TOKEN)")
+            token_value = _env_tagged(var_name.strip())
+        else:
+            token_value = typer.prompt("Token", hide_input=True)
+
+        doc = _build_doc(profile_name.strip(), url.strip(), token_value)
+
+        with acquire_lock(path):
+            atomic_write(path, dump_round_trip(doc))
+
+        typer.echo(f"wrote {path}")
+        typer.echo(f"next: nsc login --profile {profile_name.strip()}")

nsc/cli/login_commands.py

@@ -0,0 +1,265 @@
+"""`nsc login` — verify / create / rotate a profile's token.
+
+Three modes (mutually exclusive):
+
+* bare or `--profile <name>` — verify an existing profile against the live NetBox.
+* `--new --profile <name>` — create a new profile entry, then verify.
+* `--rotate --profile <name>` — prompt for a new token, verify, replace in storage.
+
+All three end with `verify()`; only success persists changes (for `--rotate`)
+or returns 0 (for bare). Cache is never touched.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Annotated
+
+import typer
+from ruamel.yaml.comments import CommentedMap, TaggedScalar
+
+from nsc.auth.verify import VerifyError, verify
+from nsc.cli.runtime import emit_envelope
+from nsc.config.loader import ConfigParseError, load_config
+from nsc.config.models import OutputFormat, Profile
+from nsc.config.settings import default_paths
+from nsc.config.writer import (
+    acquire_lock,
+    atomic_write,
+    dump_round_trip,
+    load_round_trip,
+)
+from nsc.output.errors import ErrorEnvelope, ErrorType
+
+
+def _config_path() -> Path:
+    return default_paths().config_file
+
+
+def _env_tagged(var_name: str) -> object:
+    """Build a `!env <VARNAME>` scalar that ruamel will emit with its tag intact."""
+    return TaggedScalar(value=var_name, style=None, tag="!env")
+
+
+def _emit_auth_envelope(
+    message: str,
+    *,
+    status_code: int | None,
+    user_check_status: int | None,
+) -> int:
+    details: dict[str, object] = {"reason": "rejected"}
+    if user_check_status is not None:
+        details["user_check_status"] = user_check_status
+    env = ErrorEnvelope(
+        error=message,
+        type=ErrorType.AUTH,
+        status_code=status_code,
+        details=details,
+    )
+    return emit_envelope(env, output_format=OutputFormat.TABLE)
+
+
+def _emit_config_envelope(message: str) -> int:
+    env = ErrorEnvelope(error=message, type=ErrorType.CONFIG)
+    return emit_envelope(env, output_format=OutputFormat.TABLE)
+
+
+def _resolved_profile(name: str) -> Profile:
+    """Return the validated `Profile` for `name`, raising on missing/invalid config."""
+    try:
+        config = load_config(_config_path())
+    except ConfigParseError as exc:
+        raise typer.BadParameter(str(exc)) from exc
+    if name not in config.profiles:
+        raise typer.BadParameter(f"profile {name!r} not in config")
+    return config.profiles[name]
+
+
+def _ensure_profile_exists_in_doc(doc: CommentedMap, name: str) -> CommentedMap:
+    profiles = doc.get("profiles")
+    if not isinstance(profiles, CommentedMap):
+        profiles = CommentedMap()
+        doc["profiles"] = profiles
+    if name not in profiles:
+        profiles[name] = CommentedMap()
+    entry = profiles[name]
+    assert isinstance(entry, CommentedMap)
+    return entry
+
+
+def _write_profile_entry(*, profile: str, url: str, token_value: object, set_default: bool) -> None:
+    path = _config_path()
+    with acquire_lock(path):
+        doc = load_round_trip(path)
+        if set_default and "default_profile" not in doc:
+            doc["default_profile"] = profile
+        entry = _ensure_profile_exists_in_doc(doc, profile)
+        entry["url"] = url
+        entry["token"] = token_value
+        atomic_write(path, dump_round_trip(doc))
+
+
+def _replace_token(profile: str, token_value: object) -> None:
+    path = _config_path()
+    with acquire_lock(path):
+        doc = load_round_trip(path)
+        profiles = doc.get("profiles")
+        if not isinstance(profiles, CommentedMap) or profile not in profiles:
+            raise typer.BadParameter(f"profile {profile!r} not in config")
+        entry = profiles[profile]
+        if not isinstance(entry, CommentedMap):
+            raise typer.BadParameter(f"profile {profile!r} is not a mapping")
+        entry["token"] = token_value
+        atomic_write(path, dump_round_trip(doc))
+
+
+def _print_success(username: str, version: str) -> None:
+    typer.echo(f"✓ authenticated as {username}, NetBox {version}")
+
+
+def register(app: typer.Typer) -> None:
+    @app.command("login", help="Verify / create / rotate a profile's token.")
+    def login_cmd(
+        profile: Annotated[str | None, typer.Option("--profile")] = None,
+        new: Annotated[bool, typer.Option("--new", help="Create a new profile.")] = False,
+        rotate: Annotated[
+            bool, typer.Option("--rotate", help="Replace an existing profile's token.")
+        ] = False,
+        url: Annotated[str | None, typer.Option("--url")] = None,
+        store: Annotated[
+            str, typer.Option("--store", help="Token storage: plaintext|env.")
+        ] = "plaintext",
+        env_var: Annotated[
+            str | None,
+            typer.Option(
+                "--env-var",
+                help="Environment variable name (required when --store=env).",
+            ),
+        ] = None,
+    ) -> None:
+        if new and rotate:
+            raise typer.BadParameter("--new and --rotate are mutually exclusive")
+
+        if new:
+            _do_login_new(profile, url, store, env_var)
+            return
+        if rotate:
+            _do_login_rotate(profile, store, env_var)
+            return
+        _do_login_verify(profile)
+
+
+def _do_login_verify(profile_name: str | None) -> None:
+    try:
+        config = load_config(_config_path())
+    except ConfigParseError as exc:
+        code = _emit_config_envelope(str(exc))
+        raise typer.Exit(code=code) from exc
+    name = profile_name or config.default_profile
+    if name is None:
+        code = _emit_config_envelope("no profile selected and no default_profile set in config")
+        raise typer.Exit(code=code)
+    if name not in config.profiles:
+        code = _emit_config_envelope(f"profile {name!r} not in config")
+        raise typer.Exit(code=code)
+    profile = config.profiles[name]
+    try:
+        result = verify(profile)
+    except VerifyError as exc:
+        code = _emit_auth_envelope(
+            str(exc),
+            status_code=exc.status_code,
+            user_check_status=exc.user_check_status,
+        )
+        raise typer.Exit(code=code) from exc
+    _print_success(result.username, result.netbox_version)
+
+
+def _do_login_new(
+    profile_name: str | None,
+    url: str | None,
+    store: str,
+    env_var: str | None,
+) -> None:
+    if profile_name is None:
+        raise typer.BadParameter("--new requires --profile <name>")
+    if url is None:
+        raise typer.BadParameter("--new requires --url <url>")
+    try:
+        existing_config = load_config(_config_path())
+    except ConfigParseError:
+        existing_config = None
+    if existing_config and profile_name in existing_config.profiles:
+        typer.echo(
+            f"error: profile {profile_name!r} already exists; "
+            f"use `nsc login --rotate --profile {profile_name}` to replace its token.",
+            err=True,
+        )
+        raise typer.Exit(code=12)
+    token_input = typer.prompt("Token", hide_input=True)
+    token_for_verify = token_input.strip()
+    token_value: object
+    if store.lower() == "env":
+        if not env_var:
+            raise typer.BadParameter("--store=env requires --env-var <NAME>")
+        token_value = _env_tagged(env_var)
+    else:
+        token_value = token_for_verify
+
+    candidate = Profile(name=profile_name, url=url, token=token_for_verify)  # type: ignore[arg-type]
+    try:
+        result = verify(candidate)
+    except VerifyError as exc:
+        code = _emit_auth_envelope(
+            str(exc),
+            status_code=exc.status_code,
+            user_check_status=exc.user_check_status,
+        )
+        raise typer.Exit(code=code) from exc
+    set_default = (existing_config is None) or (existing_config.default_profile is None)
+    _write_profile_entry(
+        profile=profile_name,
+        url=url,
+        token_value=token_value,
+        set_default=set_default,
+    )
+    _print_success(result.username, result.netbox_version)
+
+
+def _do_login_rotate(
+    profile_name: str | None,
+    store: str,
+    env_var: str | None,
+) -> None:
+    if profile_name is None:
+        raise typer.BadParameter("--rotate requires --profile <name>")
+    profile = _resolved_profile(profile_name)
+    new_token = typer.prompt("New token", hide_input=True).strip()
+
+    candidate = Profile(
+        name=profile.name,
+        url=profile.url,
+        token=new_token,
+        verify_ssl=profile.verify_ssl,
+        schema_url=profile.schema_url,
+        timeout=profile.timeout,
+    )
+    try:
+        result = verify(candidate)
+    except VerifyError as exc:
+        code = _emit_auth_envelope(
+            str(exc),
+            status_code=exc.status_code,
+            user_check_status=exc.user_check_status,
+        )
+        raise typer.Exit(code=code) from exc
+
+    token_value: object
+    if store.lower() == "env":
+        if not env_var:
+            raise typer.BadParameter("--store=env requires --env-var <NAME>")
+        token_value = _env_tagged(env_var)
+    else:
+        token_value = new_token
+    _replace_token(profile_name, token_value)
+    _print_success(result.username, result.netbox_version)

nsc/cli/profiles_commands.py

@@ -0,0 +1,256 @@
+"""`nsc profiles` — list / add / remove / rename / set-default.
+
+Operates on the same `~/.nsc/config.yaml` as `nsc config` and the same on-disk
+cache as the dynamic-tree handlers. `add` runs `verify()` before persisting;
+`remove` purges the cache; `rename` moves the cache directory.
+"""
+
+from __future__ import annotations
+
+import json
+from enum import StrEnum
+from pathlib import Path
+from typing import Annotated
+
+import typer
+from ruamel.yaml.comments import CommentedMap
+
+from nsc.auth.verify import VerifyError, verify
+from nsc.cache.store import CacheStore
+from nsc.cli.runtime import emit_envelope
+from nsc.config.loader import ConfigParseError, load_config
+from nsc.config.models import OutputFormat, Profile
+from nsc.config.settings import default_paths
+from nsc.config.writer import (
+    acquire_lock,
+    atomic_write,
+    dump_round_trip,
+    load_round_trip,
+)
+from nsc.output.errors import ErrorEnvelope, ErrorType
+
+
+class _ListFormat(StrEnum):
+    TABLE = "table"
+    JSON = "json"
+
+
+def _config_path() -> Path:
+    return default_paths().config_file
+
+
+def _cache() -> CacheStore:
+    return CacheStore(root=default_paths().cache_dir)
+
+
+def _emit_auth_envelope(
+    message: str, *, status_code: int | None, user_check_status: int | None
+) -> int:
+    details: dict[str, object] = {"reason": "rejected"}
+    if user_check_status is not None:
+        details["user_check_status"] = user_check_status
+    env = ErrorEnvelope(
+        error=message,
+        type=ErrorType.AUTH,
+        status_code=status_code,
+        details=details,
+    )
+    return emit_envelope(env, output_format=OutputFormat.TABLE)
+
+
+def _emit_config_envelope(message: str) -> int:
+    env = ErrorEnvelope(error=message, type=ErrorType.CONFIG)
+    return emit_envelope(env, output_format=OutputFormat.TABLE)
+
+
+def register(app: typer.Typer) -> None:
+    profiles_app = typer.Typer(
+        name="profiles",
+        help="Manage profiles in ~/.nsc/config.yaml.",
+        no_args_is_help=True,
+    )
+
+    @profiles_app.command("list")
+    def list_cmd(
+        output: Annotated[
+            _ListFormat,
+            typer.Option("--output", "-o", help="table|json"),
+        ] = _ListFormat.TABLE,
+    ) -> None:
+        _do_list(output)
+
+    @profiles_app.command("add")
+    def add_cmd(
+        name: str = typer.Argument(...),
+        url: str = typer.Option(..., "--url"),
+        token: str = typer.Option(..., "--token"),
+    ) -> None:
+        _do_add(name, url, token)
+
+    @profiles_app.command("remove")
+    def remove_cmd(
+        name: str = typer.Argument(...),
+        force: bool = typer.Option(False, "--force"),
+    ) -> None:
+        _do_remove(name, force=force)
+
+    @profiles_app.command("rename")
+    def rename_cmd(
+        old: str = typer.Argument(...),
+        new: str = typer.Argument(...),
+    ) -> None:
+        _do_rename(old, new)
+
+    @profiles_app.command("set-default")
+    def set_default_cmd(name: str = typer.Argument(...)) -> None:
+        _do_set_default(name)
+
+    app.add_typer(profiles_app)
+
+
+def _load_doc() -> CommentedMap:
+    path = _config_path()
+    doc = load_round_trip(path)
+    if "profiles" not in doc:
+        doc["profiles"] = CommentedMap()
+    return doc
+
+
+def _do_list(output: _ListFormat) -> None:
+    try:
+        config = load_config(_config_path())
+    except ConfigParseError as exc:
+        code = _emit_config_envelope(str(exc))
+        raise typer.Exit(code=code) from exc
+
+    if output is _ListFormat.JSON:
+        payload = {
+            "default": config.default_profile,
+            "profiles": [{"name": p.name, "url": str(p.url)} for p in config.profiles.values()],
+        }
+        typer.echo(json.dumps(payload, indent=2))
+        return
+
+    if not config.profiles:
+        typer.echo("(no profiles configured)")
+        return
+    for name, profile in config.profiles.items():
+        marker = "*" if name == config.default_profile else " "
+        typer.echo(f"{marker} {name}\t{profile.url}")
+
+
+def _do_add(name: str, url: str, token: str) -> None:
+    path = _config_path()
+    try:
+        existing = load_config(path)
+    except ConfigParseError:
+        existing = None
+    if existing and name in existing.profiles:
+        code = _emit_config_envelope(
+            f"profile {name!r} already exists; use `nsc login --rotate --profile {name}` "
+            f"to replace its token."
+        )
+        raise typer.Exit(code=code)
+
+    candidate = Profile(name=name, url=url, token=token)  # type: ignore[arg-type]
+    try:
+        result = verify(candidate)
+    except VerifyError as exc:
+        code = _emit_auth_envelope(
+            str(exc),
+            status_code=exc.status_code,
+            user_check_status=exc.user_check_status,
+        )
+        raise typer.Exit(code=code) from exc
+
+    with acquire_lock(path):
+        doc = _load_doc()
+        if existing is None or existing.default_profile is None:
+            doc.setdefault("default_profile", name)
+        profiles = doc["profiles"]
+        entry = CommentedMap()
+        entry["url"] = url
+        entry["token"] = token
+        profiles[name] = entry
+        atomic_write(path, dump_round_trip(doc))
+    typer.echo(f"✓ added profile {name!r}; authenticated as {result.username}")
+
+
+def _do_remove(name: str, *, force: bool) -> None:
+    path = _config_path()
+    try:
+        config = load_config(path)
+    except ConfigParseError as exc:
+        code = _emit_config_envelope(str(exc))
+        raise typer.Exit(code=code) from exc
+    if name not in config.profiles:
+        code = _emit_config_envelope(f"profile {name!r} not in config")
+        raise typer.Exit(code=code)
+    if config.default_profile == name and not force:
+        code = _emit_config_envelope(
+            f"refusing to remove default profile {name!r}; "
+            f"`nsc profiles set-default <other>` first, or pass --force."
+        )
+        raise typer.Exit(code=code)
+
+    with acquire_lock(path):
+        doc = _load_doc()
+        profiles = doc.get("profiles") or CommentedMap()
+        if name in profiles:
+            del profiles[name]
+        if doc.get("default_profile") == name:
+            del doc["default_profile"]
+        atomic_write(path, dump_round_trip(doc))
+    _cache().purge(name)
+    typer.echo(f"✓ removed profile {name!r}")
+
+
+def _do_rename(old: str, new: str) -> None:
+    path = _config_path()
+    try:
+        config = load_config(path)
+    except ConfigParseError as exc:
+        code = _emit_config_envelope(str(exc))
+        raise typer.Exit(code=code) from exc
+    if old not in config.profiles:
+        code = _emit_config_envelope(f"profile {old!r} not in config")
+        raise typer.Exit(code=code)
+    if new in config.profiles:
+        code = _emit_config_envelope(f"profile {new!r} already exists")
+        raise typer.Exit(code=code)
+
+    with acquire_lock(path):
+        doc = _load_doc()
+        profiles = doc["profiles"]
+        new_profiles = CommentedMap()
+        for k, v in profiles.items():
+            new_profiles[new if k == old else k] = v
+        doc["profiles"] = new_profiles
+        if doc.get("default_profile") == old:
+            doc["default_profile"] = new
+        atomic_write(path, dump_round_trip(doc))
+    try:
+        _cache().move(old, new)
+    except FileExistsError as exc:
+        typer.echo(
+            f"warning: cache for {new!r} already exists ({exc}); skipping cache move",
+            err=True,
+        )
+    typer.echo(f"✓ renamed profile {old!r} → {new!r}")
+
+
+def _do_set_default(name: str) -> None:
+    path = _config_path()
+    try:
+        config = load_config(path)
+    except ConfigParseError as exc:
+        code = _emit_config_envelope(str(exc))
+        raise typer.Exit(code=code) from exc
+    if name not in config.profiles:
+        code = _emit_config_envelope(f"profile {name!r} not in config")
+        raise typer.Exit(code=code)
+    with acquire_lock(path):
+        doc = _load_doc()
+        doc["default_profile"] = name
+        atomic_write(path, dump_round_trip(doc))
+    typer.echo(f"✓ default_profile = {name}")