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

nsc/cache/store.py

@@ -0,0 +1,295 @@
+"""Persist generated CommandModels under `~/.nsc/cache/<profile>/<hash>.json`."""
+
+from __future__ import annotations
+
+import contextlib
+import logging
+import re
+import shutil
+import time
+from collections.abc import Callable
+from dataclasses import dataclass
+from pathlib import Path
+
+from nsc.config.models import Config, Profile
+from nsc.model.command_model import CommandModel
+
+_LOG = logging.getLogger(__name__)
+_PROFILE_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$")
+_HASH_RE = re.compile(r"^[0-9a-f]{64}$")
+
+
+@dataclass(frozen=True, slots=True)
+class CacheEntry:
+    profile: str
+    schema_hash: str
+    path: Path
+
+
+@dataclass(frozen=True, slots=True)
+class PrunePlan:
+    orphan_profile_dirs: list[Path]
+    stale_hash_files: list[Path]
+    aged_files: list[Path]
+
+    def total_count(self) -> int:
+        return len(self.orphan_profile_dirs) + len(self.stale_hash_files) + len(self.aged_files)
+
+    def total_bytes(self) -> int:
+        total = 0
+        for d in self.orphan_profile_dirs:
+            for f in d.rglob("*"):
+                if f.is_file():
+                    total += f.stat().st_size
+        for f in (*self.stale_hash_files, *self.aged_files):
+            if f.exists():
+                total += f.stat().st_size
+        return total
+
+
+@dataclass(frozen=True, slots=True)
+class PruneResult:
+    deleted_dirs: int
+    deleted_files: int
+    freed_bytes: int
+
+
+@dataclass(frozen=True, slots=True)
+class CacheStore:
+    root: Path
+
+    def load(self, profile: str, schema_hash: str) -> CommandModel | None:
+        self._validate_profile(profile)
+        if not _HASH_RE.match(schema_hash):
+            return None
+        target = self._path_for(profile, schema_hash)
+        if not target.exists():
+            return None
+        try:
+            text = target.read_text()
+            model = CommandModel.model_validate_json(text)
+        except Exception as exc:  # broad: corrupt JSON, schema mismatch, etc.
+            _LOG.warning("cache: ignoring corrupt entry %s (%s)", target, exc)
+            return None
+        if model.schema_hash != schema_hash:
+            _LOG.warning("cache: hash mismatch for %s (file says %s)", target, model.schema_hash)
+            return None
+        return model
+
+    def save(self, profile: str, model: CommandModel) -> Path:
+        self._validate_profile(profile)
+        target = self._path_for(profile, model.schema_hash)
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_text(model.model_dump_json(indent=2))
+        return target
+
+    def clear(self, *, profile: str | None = None) -> None:
+        if profile is None:
+            if self.root.exists():
+                shutil.rmtree(self.root)
+            return
+        self._validate_profile(profile)
+        target = self.root / profile
+        if target.exists():
+            shutil.rmtree(target)
+
+    def move(self, old: str, new: str) -> None:
+        """Rename a profile's cache directory from `old` to `new`.
+
+        No-op when `old` does not exist (the profile was never warmed). Raises
+        `FileExistsError` when `new` already exists — the caller must purge
+        the target first if that's the intent. Both names are validated to
+        prevent path-component injection (matches `_PROFILE_RE`).
+        """
+        self._validate_profile(old)
+        self._validate_profile(new)
+        src = self.root / old
+        dst = self.root / new
+        if not src.exists():
+            return
+        if dst.exists():
+            raise FileExistsError(f"cache directory for profile {new!r} already exists at {dst}")
+        dst.parent.mkdir(parents=True, exist_ok=True)
+        src.rename(dst)
+
+    def purge(self, profile: str) -> None:
+        """Remove a profile's cache directory entirely. No-op if missing."""
+        self._validate_profile(profile)
+        target = self.root / profile
+        if target.exists():
+            shutil.rmtree(target)
+
+    def enumerate_caches(self) -> list[CacheEntry]:
+        """Walk the cache root and return one CacheEntry per valid <profile>/<hash>.json file.
+
+        Silently skips:
+          - Entries in `self.root` that aren't directories.
+          - Directories whose names don't match `_PROFILE_RE`.
+          - Files whose stems don't match `_HASH_RE` or whose suffix isn't `.json`.
+        """
+        if not self.root.exists():
+            return []
+        entries: list[CacheEntry] = []
+        for profile_dir in self.root.iterdir():
+            if not profile_dir.is_dir():
+                continue
+            if not _PROFILE_RE.match(profile_dir.name):
+                continue
+            for cache_file in profile_dir.iterdir():
+                if cache_file.suffix != ".json":
+                    continue
+                stem = cache_file.stem
+                if not _HASH_RE.match(stem):
+                    continue
+                entries.append(
+                    CacheEntry(profile=profile_dir.name, schema_hash=stem, path=cache_file)
+                )
+        return entries
+
+    def _path_for(self, profile: str, schema_hash: str) -> Path:
+        return self.root / profile / f"{schema_hash}.json"
+
+    @staticmethod
+    def _validate_profile(profile: str) -> None:
+        if not _PROFILE_RE.match(profile):
+            raise ValueError(f"invalid profile name {profile!r}: must match {_PROFILE_RE.pattern}")
+
+
+ADHOC_PROFILE = "adhoc"
+"""Cache subdirectory name used by `nsc/cli/runtime.py` for env-var-only
+invocations (no profile in config). The prune logic must never delete it."""
+
+
+def _find_orphan_dirs(entries: list[CacheEntry], profile_names: set[str]) -> list[Path]:
+    """Type A: return one Path per profile directory not in config (adhoc excluded)."""
+    orphan_dirs: list[Path] = []
+    seen_dirs: set[Path] = set()
+    for entry in entries:
+        if entry.profile == ADHOC_PROFILE or entry.profile in profile_names:
+            continue
+        d = entry.path.parent
+        if d not in seen_dirs:
+            seen_dirs.add(d)
+            orphan_dirs.append(d)
+    return orphan_dirs
+
+
+def _find_stale_files(
+    entries: list[CacheEntry],
+    config: Config,
+    fetch_live_hash: Callable[[Profile], str],
+) -> list[Path]:
+    """Type B: return files whose hash doesn't match the live hash; skip on fetcher error."""
+    stale_files: list[Path] = []
+    for name in config.profiles:
+        try:
+            live_hash = fetch_live_hash(config.profiles[name])
+        except Exception:  # tolerated per-profile; caller skips unreachable instances
+            continue
+        for entry in entries:
+            if entry.profile == name and entry.schema_hash != live_hash:
+                stale_files.append(entry.path)
+    return stale_files
+
+
+def _find_aged_files(
+    entries: list[CacheEntry],
+    orphan_dirs: list[Path],
+    cutoff: float,
+) -> list[Path]:
+    """Type C: return files older than `cutoff`, excluding those inside orphan dirs."""
+    orphan_paths = set(orphan_dirs)
+    aged: list[Path] = []
+    for entry in entries:
+        if entry.path.parent in orphan_paths:
+            continue
+        try:
+            mtime = entry.path.stat().st_mtime
+        except FileNotFoundError:
+            continue
+        if mtime < cutoff:
+            aged.append(entry.path)
+    return aged
+
+
+def compute_prune_plan(
+    *,
+    config: Config,
+    store: CacheStore,
+    fetch_live_hash: Callable[[Profile], str] | None = None,
+    max_age_days: int | None = None,
+    now: float | None = None,
+) -> PrunePlan:
+    """Classify cache entries into the three prune categories.
+
+    Type A (orphan_profile_dirs): a profile directory whose name is not in
+    `config.profiles` (and is not the `adhoc` sentinel).
+
+    Type B (stale_hash_files): for an *active* profile, files whose
+    `<schema_hash>` does not match the live schema's current hash.
+    Requires `fetch_live_hash`. If the fetcher raises for a given profile,
+    type B is silently skipped for that profile only.
+
+    Type C (aged_files): files whose mtime is older than `max_age_days`.
+    Independent of A and B but deduplicated against A: a file inside an
+    orphan profile dir is reported under A only (the rmtree handles it).
+    """
+    entries = store.enumerate_caches()
+
+    orphan_dirs = _find_orphan_dirs(entries, set(config.profiles.keys()))
+
+    stale_files = (
+        _find_stale_files(entries, config, fetch_live_hash) if fetch_live_hash is not None else []
+    )
+
+    aged = (
+        _find_aged_files(
+            entries,
+            orphan_dirs,
+            (now if now is not None else time.time()) - max_age_days * 86400,
+        )
+        if max_age_days is not None
+        else []
+    )
+
+    return PrunePlan(
+        orphan_profile_dirs=orphan_dirs,
+        stale_hash_files=stale_files,
+        aged_files=aged,
+    )
+
+
+def prune_orphans(plan: PrunePlan) -> PruneResult:
+    """Delete every path in the plan; tolerant of paths deleted out-of-band.
+
+    Returns counts + freed bytes for output rendering. Bytes are measured
+    BEFORE deletion using `Path.stat()`; if a file vanished between
+    classification and apply, it contributes 0 bytes and 0 deletions.
+    """
+    deleted_dirs = 0
+    deleted_files = 0
+    freed = 0
+
+    for d in plan.orphan_profile_dirs:
+        if not d.exists():
+            continue
+        for f in d.rglob("*"):
+            if f.is_file():
+                with contextlib.suppress(FileNotFoundError):
+                    freed += f.stat().st_size
+        shutil.rmtree(d)
+        deleted_dirs += 1
+
+    for f in (*plan.stale_hash_files, *plan.aged_files):
+        if not f.exists():
+            continue
+        with contextlib.suppress(FileNotFoundError):
+            freed += f.stat().st_size
+            f.unlink()
+            deleted_files += 1
+
+    return PruneResult(
+        deleted_dirs=deleted_dirs,
+        deleted_files=deleted_files,
+        freed_bytes=freed,
+    )

nsc/cli/__init__.py

@@ -0,0 +1 @@
+"""Typer-based command-line interface."""

nsc/cli/aliases_commands.py

@@ -0,0 +1,264 @@
+"""`nsc ls / get / rm / search` — curated aliases over the dynamic command tree.
+
+Each verb resolves its term to a `(tag, resource, operation)` triple via
+`nsc.aliases.resolve` and delegates to the same handler the dynamic tree
+uses. The audit log is written by the handler (or by `NetBoxClient` for
+write methods), so alias and full-path invocations produce byte-identical
+`audit.jsonl` lines (modulo timestamp and duration_ms).
+"""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+
+from nsc.aliases import (
+    AliasVerb,
+    AmbiguousAlias,
+    ResolvedAlias,
+    UnknownAlias,
+    resolve,
+)
+from nsc.cli.handlers import handle_delete, handle_get, handle_list
+from nsc.cli.runtime import RuntimeContext, emit_envelope
+from nsc.config.models import OutputFormat
+from nsc.http.errors import NetBoxAPIError, NetBoxClientError
+from nsc.model.command_model import Operation
+from nsc.output.errors import (
+    ErrorEnvelope,
+    ErrorType,
+    ambiguous_alias_envelope,
+    client_envelope,
+    unknown_alias_envelope,
+)
+
+
+def _runtime_from_ctx(ctx: typer.Context) -> RuntimeContext:
+    """Extract the bootstrapped RuntimeContext from `ctx.obj`."""
+    obj = ctx.obj
+    if isinstance(obj, tuple) and len(obj) == 2:  # noqa: PLR2004
+        runtime = obj[1]
+        if isinstance(runtime, RuntimeContext):
+            return runtime
+    raise typer.Exit(2)
+
+
+def _emit_alias_envelope(env: ErrorEnvelope, ctx: RuntimeContext) -> int:
+    return emit_envelope(env, output_format=ctx.output_format)
+
+
+def _dereference_by_name(
+    runtime: RuntimeContext,
+    *,
+    list_op: Operation,
+    name: str,
+) -> int | ErrorEnvelope:
+    """List the resource filtered by `name=<name>` and return the single id.
+
+    Returns an `ErrorEnvelope` (already-shaped ambiguous_alias / unknown_alias)
+    if zero or >=2 records match. Caller emits and exits.
+    """
+    try:
+        rows = list(runtime.client.paginate(list_op.path, {"name": name}))
+    except (NetBoxAPIError, NetBoxClientError) as exc:
+        return client_envelope(
+            f"failed to dereference name {name!r}: {exc}",
+            operation_id=list_op.operation_id,
+        )
+    if len(rows) == 0:
+        return ErrorEnvelope(
+            error=f"no record matched name={name!r}",
+            type=ErrorType.UNKNOWN_ALIAS,
+            details={"verb": "rm", "term": name, "reason": "name_not_found"},
+        )
+    if len(rows) >= 2:  # noqa: PLR2004
+        return ErrorEnvelope(
+            error=f"{len(rows)} records matched name={name!r}; refuse to delete",
+            type=ErrorType.AMBIGUOUS_ALIAS,
+            details={
+                "verb": "rm",
+                "term": name,
+                "reason": "name_matched_multiple",
+                "matched_ids": [row["id"] for row in rows],
+            },
+        )
+    return int(rows[0]["id"])
+
+
+def register(app: typer.Typer) -> None:  # noqa: PLR0915
+    @app.command("ls", help="List records on a resource (alias for `<tag> <resource> list`).")
+    def ls_cmd(
+        ctx: typer.Context,
+        term: Annotated[str, typer.Argument(help="Resource name (plural, e.g. `devices`).")],
+        output: Annotated[str | None, typer.Option("--output", "-o")] = None,
+        compact: Annotated[bool, typer.Option("--compact")] = False,
+        columns: Annotated[str | None, typer.Option("--columns")] = None,
+        limit: Annotated[int | None, typer.Option("--limit")] = None,
+        all_: Annotated[bool, typer.Option("--all")] = False,
+        filter_: Annotated[list[str] | None, typer.Option("--filter")] = None,
+    ) -> None:
+        runtime = _runtime_from_ctx(ctx)
+        update: dict[str, object] = {
+            "compact": compact,
+            "columns_override": columns.split(",") if columns else None,
+            "limit": limit,
+            "fetch_all": all_,
+            "filters": [
+                (item.split("=", 1)[0], item.split("=", 1)[1])
+                for item in (filter_ or [])
+                if "=" in item
+            ],
+        }
+        if output:
+            update["output_format"] = OutputFormat(output)
+        runtime = runtime.model_copy(update=update)
+
+        result = resolve(AliasVerb.LS, term, runtime.command_model)
+        if isinstance(result, AmbiguousAlias):
+            env = ambiguous_alias_envelope(verb="ls", term=term, candidates=result.candidates)
+            raise typer.Exit(_emit_alias_envelope(env, runtime))
+        if isinstance(result, UnknownAlias):
+            env = unknown_alias_envelope(verb="ls", term=term, reason=result.reason)
+            raise typer.Exit(_emit_alias_envelope(env, runtime))
+        assert isinstance(result, ResolvedAlias)
+        handle_list(
+            result.operation,
+            op_tag=result.tag,
+            op_resource=result.resource_name,
+            ctx=runtime,
+        )
+
+    @app.command("rm", help="Delete one record (alias for `<tag> <resource> delete`).")
+    def rm_cmd(
+        ctx: typer.Context,
+        term: Annotated[str, typer.Argument(help="Resource name (plural).")],
+        id_or_name: Annotated[str, typer.Argument(help="Numeric id or unique name.")],
+        apply: Annotated[bool, typer.Option("--apply", "-a")] = False,
+        explain: Annotated[bool, typer.Option("--explain")] = False,
+        strict: Annotated[bool, typer.Option("--strict")] = False,
+        output: Annotated[str | None, typer.Option("--output", "-o")] = None,
+    ) -> None:
+        runtime = _runtime_from_ctx(ctx)
+        update: dict[str, object] = {
+            "apply": apply,
+            "explain": explain,
+            "strict": strict,
+        }
+        if output:
+            update["output_format"] = OutputFormat(output)
+        runtime = runtime.model_copy(update=update)
+
+        result = resolve(AliasVerb.RM, term, runtime.command_model)
+        if isinstance(result, AmbiguousAlias):
+            env = ambiguous_alias_envelope(verb="rm", term=term, candidates=result.candidates)
+            raise typer.Exit(_emit_alias_envelope(env, runtime))
+        if isinstance(result, UnknownAlias):
+            env = unknown_alias_envelope(verb="rm", term=term, reason=result.reason)
+            raise typer.Exit(_emit_alias_envelope(env, runtime))
+        assert isinstance(result, ResolvedAlias)
+
+        if id_or_name.isdigit():
+            resolved_id = int(id_or_name)
+        else:
+            resource = runtime.command_model.tags[result.tag].resources[result.resource_name]
+            list_op = resource.list_op
+            if list_op is None:
+                env = unknown_alias_envelope(
+                    verb="rm", term=term, reason="no_list_op_for_dereference"
+                )
+                raise typer.Exit(_emit_alias_envelope(env, runtime))
+            outcome = _dereference_by_name(runtime, list_op=list_op, name=id_or_name)
+            if isinstance(outcome, ErrorEnvelope):
+                raise typer.Exit(_emit_alias_envelope(outcome, runtime))
+            resolved_id = outcome
+
+        handle_delete(
+            result.operation,
+            op_tag=result.tag,
+            op_resource=result.resource_name,
+            ctx=runtime,
+            id=str(resolved_id),
+        )
+
+    @app.command("get", help="Get one record (alias for `<tag> <resource> get`).")
+    def get_cmd(
+        ctx: typer.Context,
+        term: Annotated[str, typer.Argument(help="Resource name (plural).")],
+        id_or_name: Annotated[str, typer.Argument(help="Numeric id or unique name.")],
+        output: Annotated[str | None, typer.Option("--output", "-o")] = None,
+        compact: Annotated[bool, typer.Option("--compact")] = False,
+        columns: Annotated[str | None, typer.Option("--columns")] = None,
+    ) -> None:
+        runtime = _runtime_from_ctx(ctx)
+        update: dict[str, object] = {
+            "compact": compact,
+            "columns_override": columns.split(",") if columns else None,
+        }
+        if output:
+            update["output_format"] = OutputFormat(output)
+        runtime = runtime.model_copy(update=update)
+
+        result = resolve(AliasVerb.GET, term, runtime.command_model)
+        if isinstance(result, AmbiguousAlias):
+            env = ambiguous_alias_envelope(verb="get", term=term, candidates=result.candidates)
+            raise typer.Exit(_emit_alias_envelope(env, runtime))
+        if isinstance(result, UnknownAlias):
+            env = unknown_alias_envelope(verb="get", term=term, reason=result.reason)
+            raise typer.Exit(_emit_alias_envelope(env, runtime))
+        assert isinstance(result, ResolvedAlias)
+
+        if id_or_name.isdigit():
+            resolved_id = int(id_or_name)
+        else:
+            list_op = runtime.command_model.tags[result.tag].resources[result.resource_name].list_op
+            if list_op is None:
+                env = unknown_alias_envelope(
+                    verb="get", term=term, reason="no_list_op_for_dereference"
+                )
+                raise typer.Exit(_emit_alias_envelope(env, runtime))
+            outcome = _dereference_by_name(runtime, list_op=list_op, name=id_or_name)
+            if isinstance(outcome, ErrorEnvelope):
+                outcome = outcome.model_copy(update={"details": {**outcome.details, "verb": "get"}})
+                raise typer.Exit(_emit_alias_envelope(outcome, runtime))
+            resolved_id = outcome
+
+        handle_get(
+            result.operation,
+            op_tag=result.tag,
+            op_resource=result.resource_name,
+            ctx=runtime,
+            id=str(resolved_id),
+        )
+
+    @app.command("search", help="Search NetBox via /api/search/?q=<query>.")
+    def search_cmd(
+        ctx: typer.Context,
+        query: Annotated[str, typer.Argument(help="Search query string.")],
+        output: Annotated[str | None, typer.Option("--output", "-o")] = None,
+        compact: Annotated[bool, typer.Option("--compact")] = False,
+        limit: Annotated[int | None, typer.Option("--limit")] = None,
+        all_: Annotated[bool, typer.Option("--all")] = False,
+    ) -> None:
+        runtime = _runtime_from_ctx(ctx)
+        update: dict[str, object] = {
+            "compact": compact,
+            "limit": limit,
+            "fetch_all": all_,
+            "filters": [("q", query)],
+        }
+        if output:
+            update["output_format"] = OutputFormat(output)
+        runtime = runtime.model_copy(update=update)
+
+        result = resolve(AliasVerb.SEARCH, query, runtime.command_model)
+        if isinstance(result, UnknownAlias):
+            env = unknown_alias_envelope(verb="search", term=query, reason=result.reason)
+            raise typer.Exit(_emit_alias_envelope(env, runtime))
+        assert isinstance(result, ResolvedAlias)
+        handle_list(
+            result.operation,
+            op_tag=result.tag,
+            op_resource=result.resource_name,
+            ctx=runtime,
+        )