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

nsc/output/flatten.py

@@ -0,0 +1,25 @@
+"""Shared dotted-path flattener used by table and csv formatters."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+
+def flatten(record: dict[str, Any], *, columns: list[str] | None = None) -> dict[str, Any]:
+    flat: dict[str, Any] = {}
+    _walk(record, "", flat)
+    if columns is None:
+        return flat
+    return {col: flat.get(col, "") for col in columns}
+
+
+def _walk(value: Any, prefix: str, out: dict[str, Any]) -> None:
+    if isinstance(value, dict):
+        for k, v in value.items():
+            child = f"{prefix}.{k}" if prefix else k
+            _walk(v, child, out)
+    elif isinstance(value, list):
+        out[prefix] = json.dumps(value)
+    else:
+        out[prefix] = value

nsc/output/headers.py

@@ -0,0 +1,9 @@
+"""Single source of truth for sensitive HTTP header names."""
+
+from __future__ import annotations
+
+SENSITIVE_HEADERS: frozenset[str] = frozenset(
+    {"authorization", "cookie", "x-api-key", "proxy-authorization"}
+)
+
+__all__ = ["SENSITIVE_HEADERS"]

nsc/output/json_.py

@@ -0,0 +1,21 @@
+"""JSON output formatter."""
+
+from __future__ import annotations
+
+import json
+import sys
+from typing import Any, TextIO
+
+
+def render(
+    data: list[dict[str, Any]] | dict[str, Any],
+    *,
+    stream: TextIO = sys.stdout,
+    compact: bool = False,
+) -> None:
+    if compact:
+        stream.write(json.dumps(data, separators=(",", ":")))
+        stream.write("\n")
+        return
+    json.dump(data, stream, indent=2, sort_keys=False)
+    stream.write("\n")

nsc/output/jsonl.py

@@ -0,0 +1,21 @@
+"""JSON Lines output formatter."""
+
+from __future__ import annotations
+
+import json
+import sys
+from typing import Any, TextIO
+
+
+def render(
+    data: list[dict[str, Any]] | dict[str, Any],
+    *,
+    stream: TextIO = sys.stdout,
+) -> None:
+    if isinstance(data, dict):
+        stream.write(json.dumps(data))
+        stream.write("\n")
+        return
+    for record in data:
+        stream.write(json.dumps(record))
+        stream.write("\n")

nsc/output/render.py

@@ -0,0 +1,47 @@
+"""Single output entry point + format selection."""
+
+from __future__ import annotations
+
+import sys
+from typing import Any, TextIO
+
+from nsc.config.models import OutputFormat
+from nsc.output import csv_, json_, jsonl, table, yaml_
+
+
+def render(
+    data: list[dict[str, Any]] | dict[str, Any],
+    *,
+    format: OutputFormat,
+    columns: list[str] | None = None,
+    stream: TextIO = sys.stdout,
+    compact: bool = False,
+) -> None:
+    if format is OutputFormat.JSON:
+        json_.render(data, stream=stream, compact=compact)
+    elif format is OutputFormat.JSONL:
+        jsonl.render(data, stream=stream)
+    elif format is OutputFormat.YAML:
+        yaml_.render(data, stream=stream)
+    elif format is OutputFormat.CSV:
+        csv_.render(data, stream=stream, columns=columns)
+    elif format is OutputFormat.TABLE:
+        table.render(data, stream=stream, columns=columns)
+    else:  # pragma: no cover  (StrEnum exhaustively covered above)
+        raise ValueError(f"unknown output format: {format!r}")
+
+
+def select_format(
+    *,
+    cli_value: str | None,
+    env_value: str | None,
+    is_tty: bool,
+    default: OutputFormat,
+) -> OutputFormat:
+    if cli_value is not None:
+        return OutputFormat(cli_value)
+    if env_value is not None:
+        return OutputFormat(env_value)
+    if not is_tty:
+        return OutputFormat.JSON
+    return default

nsc/output/table.py

@@ -0,0 +1,50 @@
+"""Rich table output formatter."""
+
+from __future__ import annotations
+
+import sys
+from typing import Any, TextIO
+
+from rich.console import Console
+from rich.table import Table
+
+from nsc.output.flatten import flatten
+
+
+def render(
+    data: list[dict[str, Any]] | dict[str, Any],
+    *,
+    stream: TextIO = sys.stdout,
+    columns: list[str] | None = None,
+) -> None:
+    records = [data] if isinstance(data, dict) else list(data)
+    if not records:
+        Console(file=stream, force_terminal=False).print("(no records)")
+        return
+
+    flat_records = [flatten(r, columns=columns) for r in records]
+    fieldnames = columns if columns is not None else _gather_fieldnames(flat_records)
+
+    table = Table(show_header=True, header_style="bold")
+    for col in fieldnames:
+        table.add_column(col)
+    for r in flat_records:
+        table.add_row(*[_format_cell(r.get(col, "")) for col in fieldnames])
+
+    Console(file=stream, force_terminal=False).print(table)
+
+
+def _gather_fieldnames(records: list[dict[str, Any]]) -> list[str]:
+    seen: dict[str, None] = {}
+    for r in records:
+        for k in r:
+            seen.setdefault(k, None)
+    return list(seen.keys())
+
+
+def _format_cell(value: Any) -> str:
+    if value is None:
+        return ""
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    return str(value)

nsc/output/yaml_.py

@@ -0,0 +1,28 @@
+"""YAML output formatter."""
+
+from __future__ import annotations
+
+import sys
+from typing import Any, TextIO
+
+from ruamel.yaml import YAML
+
+
+def _emitter() -> YAML:
+    """A safe-mode emitter configured for stable, block-style output.
+
+    ruamel.yaml's safe dumper preserves regular `dict` insertion order natively
+    (Python 3.7+), so no explicit `sort_keys=False` toggle is needed — and
+    `YAML.sort_keys` is not part of the public API anyway.
+    """
+    yaml = YAML(typ="safe", pure=True)
+    yaml.default_flow_style = False
+    return yaml
+
+
+def render(
+    data: list[dict[str, Any]] | dict[str, Any],
+    *,
+    stream: TextIO = sys.stdout,
+) -> None:
+    _emitter().dump(data, stream)

nsc/schema/__init__.py

@@ -0,0 +1 @@
+"""OpenAPI parsing layer."""

nsc/schema/hashing.py

@@ -0,0 +1,24 @@
+"""Canonical hashing for schema bodies.
+
+Two schema bodies that differ only in key ordering (or whitespace) hash to the
+same value. This is the cache key for generated command-models.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+
+
+def canonical_sha256(body: bytes) -> str:
+    """Return the SHA-256 of `body` after JSON canonicalization.
+
+    Raises:
+        ValueError: if `body` is not valid JSON.
+    """
+    try:
+        decoded = json.loads(body)
+    except json.JSONDecodeError as exc:
+        raise ValueError(f"schema body is not valid JSON: {exc}") from exc
+    canonical = json.dumps(decoded, sort_keys=True, separators=(",", ":")).encode("utf-8")
+    return hashlib.sha256(canonical).hexdigest()

nsc/schema/loader.py

@@ -0,0 +1,66 @@
+"""Load an OpenAPI schema from a URL or local file path."""
+
+from __future__ import annotations
+
+import gzip
+from dataclasses import dataclass
+from pathlib import Path
+
+import httpx
+
+from nsc.schema.hashing import canonical_sha256
+from nsc.schema.models import OpenAPIDocument
+
+_HTTP_ERROR_THRESHOLD = 400
+
+
+class SchemaLoadError(Exception):
+    """Raised when a schema cannot be loaded or parsed."""
+
+
+@dataclass(frozen=True, slots=True)
+class LoadedSchema:
+    """A parsed OpenAPI document plus the hash of its canonical body."""
+
+    source: str
+    body: bytes
+    hash: str
+    document: OpenAPIDocument
+
+
+def load_schema(source: str, *, verify_ssl: bool = True, timeout: float = 30.0) -> LoadedSchema:
+    """Load and parse the schema at `source`.
+
+    `source` is either an `http(s)://` URL or a local filesystem path. The path
+    can be absolute or relative to the current working directory.
+    """
+    body = _fetch_body(source, verify_ssl=verify_ssl, timeout=timeout)
+    if source.endswith(".gz"):
+        try:
+            body = gzip.decompress(body)
+        except gzip.BadGzipFile as exc:
+            raise SchemaLoadError(f"{source}: not valid gzip ({exc})") from exc
+    try:
+        h = canonical_sha256(body)
+    except ValueError as exc:
+        raise SchemaLoadError(f"{source}: not valid JSON ({exc})") from exc
+    try:
+        doc = OpenAPIDocument.model_validate_json(body)
+    except Exception as exc:  # pydantic.ValidationError
+        raise SchemaLoadError(f"{source}: schema does not match expected shape: {exc}") from exc
+    return LoadedSchema(source=source, body=body, hash=h, document=doc)
+
+
+def _fetch_body(source: str, *, verify_ssl: bool, timeout: float) -> bytes:
+    if source.startswith(("http://", "https://")):
+        try:
+            response = httpx.get(source, verify=verify_ssl, timeout=timeout, follow_redirects=True)
+        except httpx.HTTPError as exc:
+            raise SchemaLoadError(f"{source}: request failed ({exc})") from exc
+        if response.status_code >= _HTTP_ERROR_THRESHOLD:
+            raise SchemaLoadError(f"{source}: HTTP {response.status_code}")
+        return response.content
+    p = Path(source)
+    if not p.exists():
+        raise SchemaLoadError(f"{source}: not found")
+    return p.read_bytes()

nsc/schema/models.py

@@ -0,0 +1,109 @@
+"""Pydantic models for the OpenAPI 3.x subset that NetBox emits and we consume.
+
+Anything we don't explicitly model is tolerated via `extra="allow"` on root
+container types, so vendor extensions and OpenAPI features we don't use can't
+break parsing.
+"""
+
+from __future__ import annotations
+
+from enum import StrEnum
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class _Tolerant(BaseModel):
+    """Base for models that should accept unknown fields."""
+
+    model_config = ConfigDict(extra="allow", populate_by_name=True)
+
+
+class ParameterIn(StrEnum):
+    QUERY = "query"
+    PATH = "path"
+    HEADER = "header"
+    COOKIE = "cookie"
+
+
+class SchemaObject(_Tolerant):
+    """A JSON Schema fragment as it appears inside an OpenAPI document.
+
+    We only model the fields we use; the rest is preserved via `extra="allow"`.
+    """
+
+    type: str | None = None
+    format: str | None = None
+    enum: list[Any] | None = None
+    items: SchemaObject | None = None
+    properties: dict[str, SchemaObject] | None = None
+    required: list[str] | None = None
+    description: str | None = None
+    ref: str | None = Field(default=None, alias="$ref")
+
+
+class MediaType(_Tolerant):
+    schema_: SchemaObject | None = Field(default=None, alias="schema")
+
+
+class RequestBody(_Tolerant):
+    description: str | None = None
+    required: bool = False
+    content: dict[str, MediaType] = Field(default_factory=dict)
+
+
+class Response(_Tolerant):
+    description: str | None = None
+    content: dict[str, MediaType] = Field(default_factory=dict)
+
+
+class Parameter(_Tolerant):
+    name: str
+    in_: ParameterIn = Field(alias="in")
+    description: str | None = None
+    required: bool = False
+    schema_: SchemaObject | None = Field(default=None, alias="schema")
+
+
+class Operation(_Tolerant):
+    operation_id: str | None = Field(default=None, alias="operationId")
+    summary: str | None = None
+    description: str | None = None
+    tags: list[str] = Field(default_factory=list)
+    parameters: list[Parameter] = Field(default_factory=list)
+    request_body: RequestBody | None = Field(default=None, alias="requestBody")
+    responses: dict[str, Response] = Field(default_factory=dict)
+
+
+class PathItem(_Tolerant):
+    get: Operation | None = None
+    put: Operation | None = None
+    post: Operation | None = None
+    delete: Operation | None = None
+    patch: Operation | None = None
+    options: Operation | None = None
+    head: Operation | None = None
+    parameters: list[Parameter] = Field(default_factory=list)
+
+
+class Info(_Tolerant):
+    title: str
+    version: str
+    description: str | None = None
+
+
+class Tag(_Tolerant):
+    name: str
+    description: str | None = None
+
+
+class Components(_Tolerant):
+    schemas: dict[str, SchemaObject] = Field(default_factory=dict)
+
+
+class OpenAPIDocument(_Tolerant):
+    openapi: str
+    info: Info
+    paths: dict[str, PathItem] = Field(default_factory=dict)
+    components: Components = Field(default_factory=Components)
+    tags: list[Tag] = Field(default_factory=list)

nsc/schema/source.py

@@ -0,0 +1,120 @@
+"""Schema-source resolution chain (Phase 2).
+
+Order:
+  1. --schema flag (path or URL)
+  2. profile.schema_url
+  3. {profile.url}/api/schema/?format=json
+  4. cache hit (matched by profile name + schema hash)
+  5. bundled fallback
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import httpx
+
+from nsc.builder.build import build_command_model
+from nsc.cache.store import CacheStore
+from nsc.cli.runtime import ResolvedProfile
+from nsc.config.settings import Paths
+from nsc.model.command_model import CommandModel
+from nsc.schema.hashing import canonical_sha256
+from nsc.schema.loader import LoadedSchema, load_schema
+from nsc.schema.models import OpenAPIDocument
+from nsc.schemas import bundled as _bundled_pkg
+
+
+class SchemaSourceError(Exception):
+    """Raised when no schema source could be resolved."""
+
+
+def resolve_command_model(
+    *,
+    paths: Paths,
+    profile: ResolvedProfile,
+    schema_override: str | None,
+) -> CommandModel:
+    if schema_override is not None:
+        loaded = load_schema(
+            schema_override, verify_ssl=profile.verify_ssl, timeout=profile.timeout
+        )
+        return _build_and_cache(loaded, paths, profile)
+
+    schema_url = (
+        str(profile.schema_url)
+        if profile.schema_url is not None
+        else f"{str(profile.url).rstrip('/')}/api/schema/?format=json"
+    )
+
+    try:
+        loaded = _fetch_schema(schema_url, profile)
+    except (httpx.RequestError, httpx.HTTPStatusError) as exc:
+        cached = _find_any_cached(paths, profile.name)
+        if cached is not None:
+            print(
+                f"Could not reach NetBox ({exc}); using cached schema.",
+                file=sys.stderr,
+            )
+            return cached
+        bundled = _load_bundled_command_model()
+        if bundled is not None:
+            print(
+                f"Could not reach NetBox ({exc}) and no cache; using bundled schema.",
+                file=sys.stderr,
+            )
+            return bundled
+        raise SchemaSourceError(
+            f"could not reach NetBox at {schema_url}, no cache, no bundled fallback: {exc}"
+        ) from exc
+
+    return _build_and_cache(loaded, paths, profile)
+
+
+def _fetch_schema(url: str, profile: ResolvedProfile) -> LoadedSchema:
+    headers: dict[str, str] = {"Accept": "application/json"}
+    if profile.token:
+        headers["Authorization"] = f"Token {profile.token}"
+    with httpx.Client(verify=profile.verify_ssl, timeout=profile.timeout, headers=headers) as c:
+        response = c.get(url)
+        response.raise_for_status()
+        body = response.content
+    document = OpenAPIDocument.model_validate_json(body)
+    return LoadedSchema(source=url, body=body, hash=canonical_sha256(body), document=document)
+
+
+def _build_and_cache(loaded: LoadedSchema, paths: Paths, profile: ResolvedProfile) -> CommandModel:
+    store = CacheStore(root=paths.cache_dir)
+    cached = store.load(profile.name, loaded.hash)
+    if cached is not None:
+        return cached
+    model = build_command_model(loaded)
+    store.save(profile.name, model)
+    return model
+
+
+def _find_any_cached(paths: Paths, profile_name: str) -> CommandModel | None:
+    profile_dir = paths.cache_dir / profile_name
+    if not profile_dir.exists():
+        return None
+    candidates = sorted(
+        profile_dir.glob("*.json"),
+        key=lambda p: p.stat().st_mtime,
+        reverse=True,
+    )
+    for candidate in candidates:
+        try:
+            return CommandModel.model_validate_json(candidate.read_text())
+        except Exception:
+            continue
+    return None
+
+
+def _load_bundled_command_model() -> CommandModel | None:
+    pkg_dir = Path(_bundled_pkg.__file__).resolve().parent
+    candidates = sorted(list(pkg_dir.glob("*.json")) + list(pkg_dir.glob("*.json.gz")))
+    if not candidates:
+        return None
+    loaded = load_schema(str(candidates[0]))
+    return build_command_model(loaded)

nsc/schemas/__init__.py

@@ -0,0 +1 @@
+"""Bundled NetBox OpenAPI snapshots and helpers."""

nsc/schemas/bundled/__init__.py

@@ -0,0 +1 @@
+"""Versioned NetBox OpenAPI snapshots, used as offline fallback."""

nsc/schemas/bundled/manifest.yaml

@@ -0,0 +1,5 @@
+# Bundled NetBox OpenAPI snapshots.
+# Maintained by `just fetch-schemas` (added in Phase 4).
+schemas:
+  - version: "4.6.0-beta2"
+    file: "netbox-4.6.0-beta2.json.gz"

nsc/skill/__init__.py

@@ -0,0 +1,35 @@
+"""Access to the bundled portable Skill file.
+
+The canonical source of truth lives at `skills/netbox-super-cli/SKILL.md` at
+the repo root; `pyproject.toml`'s wheel `force-include` ships the same path
+inside the installed wheel. The helper below uses `importlib.resources` so
+both layouts work without special-casing.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from contextlib import contextmanager
+from importlib.resources import as_file, files
+from pathlib import Path
+
+__all__ = ["BUNDLE_NAME", "bundle_path"]
+
+BUNDLE_NAME = "netbox-super-cli"
+"""The bundled Skill's directory name; used by the install helper to derive
+the per-target destination directory."""
+
+
+@contextmanager
+def bundle_path() -> Iterator[Path]:
+    """Yield an on-disk Path to the bundled `SKILL.md`.
+
+    Works in both the source-tree layout (file lives at
+    `<repo>/skills/netbox-super-cli/SKILL.md`) and the installed-wheel layout
+    (same relative path inside the wheel; `importlib.resources.as_file` will
+    materialize a real file when reading from a zipped wheel).
+    """
+    nsc_root = files("nsc")
+    skill_md = nsc_root.joinpath("..", "skills", BUNDLE_NAME, "SKILL.md")
+    with as_file(skill_md) as p:
+        yield p