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

nsc/cli/writes/preflight.py

@@ -0,0 +1,182 @@
+"""Stage 2 of the write pipeline: best-effort preflight validation.
+
+Three checks per record (spec §4.6):
+  1. required fields present (top-level only),
+  2. primitive type matches,
+  3. enum value is in the allowed set.
+
+Explicitly NOT validated: oneOf/anyOf/allOf, pattern/format/minLength/maxLength,
+foreign-key existence, cross-field rules. NetBox is the source of truth for
+those — server-side 400s surface as ErrorType.VALIDATION with source="server".
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from nsc.cli.writes.coercion import BOOL_STRINGS as _BOOL_STRINGS
+from nsc.cli.writes.input import RawWriteInput
+from nsc.model.command_model import (
+    FieldShape,
+    Operation,
+    PrimitiveType,
+    RequestBodyShape,
+)
+
+
+class _Frozen(BaseModel):
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+
+class Issue(_Frozen):
+    record_index: int
+    field_path: str
+    kind: Literal["missing_required", "type_mismatch", "enum_invalid"]
+    message: str
+    expected: str | None = None
+
+
+class PreflightResult(_Frozen):
+    ok: bool
+    issues: list[Issue] = Field(default_factory=list)
+
+
+def check(raw: RawWriteInput, operation: Operation) -> PreflightResult:
+    body = operation.request_body
+    if body is None:
+        return PreflightResult(ok=True)
+    issues: list[Issue] = []
+    for index, record in enumerate(raw.records):
+        issues.extend(_check_required(index, record, body))
+        issues.extend(_check_fields(index, record, body))
+    return PreflightResult(ok=not issues, issues=issues)
+
+
+def _check_required(index: int, record: dict[str, Any], body: RequestBodyShape) -> list[Issue]:
+    return [
+        Issue(
+            record_index=index,
+            field_path=name,
+            kind="missing_required",
+            message=f"required field {name!r} is missing",
+            expected=None,
+        )
+        for name in body.required
+        if name not in record
+    ]
+
+
+def _check_fields(index: int, record: dict[str, Any], body: RequestBodyShape) -> list[Issue]:
+    out: list[Issue] = []
+    for name, value in record.items():
+        shape = body.fields.get(name)
+        if shape is None:
+            continue
+        type_issue = _check_primitive(index, name, value, shape)
+        if type_issue is not None:
+            out.append(type_issue)
+            continue
+        enum_issue = _check_enum(index, name, value, shape)
+        if enum_issue is not None:
+            out.append(enum_issue)
+    return out
+
+
+def _check_primitive(index: int, name: str, value: Any, shape: FieldShape) -> Issue | None:
+    if value is None and shape.nullable:
+        return None
+    if _value_matches_primitive(value, shape.primitive):
+        return None
+    return Issue(
+        record_index=index,
+        field_path=name,
+        kind="type_mismatch",
+        message=(f"field {name!r} expected {shape.primitive.value}, got {type(value).__name__}"),
+        expected=shape.primitive.value,
+    )
+
+
+def _matches_string(value: Any) -> bool:
+    return isinstance(value, str)
+
+
+def _matches_integer(value: Any) -> bool:
+    if isinstance(value, bool):
+        return False
+    if isinstance(value, int):
+        return True
+    return isinstance(value, str) and _is_int_string(value)
+
+
+def _matches_number(value: Any) -> bool:
+    if isinstance(value, bool):
+        return False
+    if isinstance(value, (int, float)):
+        return True
+    return isinstance(value, str) and _is_float_string(value)
+
+
+def _matches_boolean(value: Any) -> bool:
+    if isinstance(value, bool):
+        return True
+    return isinstance(value, str) and value.strip().lower() in _BOOL_STRINGS
+
+
+def _matches_array(value: Any) -> bool:
+    return isinstance(value, list)
+
+
+def _matches_object(value: Any) -> bool:
+    return isinstance(value, dict)
+
+
+_PRIMITIVE_MATCHERS: dict[PrimitiveType, Callable[[Any], bool]] = {
+    PrimitiveType.STRING: _matches_string,
+    PrimitiveType.INTEGER: _matches_integer,
+    PrimitiveType.NUMBER: _matches_number,
+    PrimitiveType.BOOLEAN: _matches_boolean,
+    PrimitiveType.ARRAY: _matches_array,
+    PrimitiveType.OBJECT: _matches_object,
+}
+
+
+def _value_matches_primitive(value: Any, primitive: PrimitiveType) -> bool:
+    matcher = _PRIMITIVE_MATCHERS.get(primitive)
+    if matcher is None:
+        return True  # UNKNOWN — let the server arbitrate
+    return matcher(value)
+
+
+def _is_int_string(value: str) -> bool:
+    s = value.strip()
+    if s.startswith(("-", "+")):
+        s = s[1:]
+    return s.isdigit()
+
+
+def _is_float_string(value: str) -> bool:
+    try:
+        float(value)
+    except ValueError:
+        return False
+    return True
+
+
+def _check_enum(index: int, name: str, value: Any, shape: FieldShape) -> Issue | None:
+    if not shape.enum:
+        return None
+    if str(value) in shape.enum:
+        return None
+    return Issue(
+        record_index=index,
+        field_path=name,
+        kind="enum_invalid",
+        message=f"field {name!r}={value!r} not in allowed set",
+        expected=", ".join(shape.enum),
+    )
+
+
+__all__ = ["Issue", "PreflightResult", "check"]

nsc/config/__init__.py

@@ -0,0 +1,23 @@
+"""Configuration and on-disk paths."""
+
+from nsc.config.loader import ConfigParseError, load_config
+from nsc.config.models import (
+    Config,
+    Defaults,
+    OutputFormat,
+    Profile,
+    SchemaRefresh,
+)
+from nsc.config.settings import Paths, default_paths
+
+__all__ = [
+    "Config",
+    "ConfigParseError",
+    "Defaults",
+    "OutputFormat",
+    "Paths",
+    "Profile",
+    "SchemaRefresh",
+    "default_paths",
+    "load_config",
+]

nsc/config/loader.py

@@ -0,0 +1,69 @@
+"""Config loader for `~/.nsc/config.yaml`, backed by ruamel.yaml round-trip mode.
+
+ruamel.yaml's `YAML(typ="rt")` preserves comments, key order, anchors, and
+custom tags through subsequent writes (see `nsc/config/writer.py`). The parsed
+document is a `CommentedMap` (dict-compatible); we hand it to
+`Config.model_validate` for the structural validation gate.
+"""
+
+from __future__ import annotations
+
+import io
+import os
+from pathlib import Path
+from typing import Any
+
+from pydantic import ValidationError
+from ruamel.yaml import YAML
+from ruamel.yaml.constructor import BaseConstructor
+from ruamel.yaml.error import YAMLError
+from ruamel.yaml.nodes import ScalarNode
+
+from nsc.config.models import Config
+
+
+class ConfigParseError(Exception):
+    """Raised when ~/.nsc/config.yaml cannot be parsed or is structurally invalid."""
+
+
+def _construct_env(_loader: BaseConstructor, node: ScalarNode) -> str | None:
+    raw = str(node.value)
+    parts = raw.strip().split(maxsplit=1)
+    var = parts[0]
+    parts_count = 2
+    default = parts[1] if len(parts) == parts_count else None
+    return os.environ.get(var, default)
+
+
+def _round_trip_yaml() -> YAML:
+    """Build a fresh round-trip YAML parser shared in shape between loader and writer."""
+    yaml = YAML(typ="rt")
+    yaml.preserve_quotes = True
+    yaml.constructor.add_constructor("!env", _construct_env)
+    return yaml
+
+
+def load_config(path: Path) -> Config:
+    if not path.exists():
+        return Config()
+    try:
+        text = path.read_text(encoding="utf-8")
+    except OSError as exc:
+        raise ConfigParseError(f"could not read {path}: {exc}") from exc
+    try:
+        data: Any = _round_trip_yaml().load(io.StringIO(text))
+    except YAMLError as exc:
+        raise ConfigParseError(f"YAML parse error in {path}: {exc}") from exc
+    if data is None:
+        return Config()
+    if not isinstance(data, dict):
+        raise ConfigParseError(f"{path}: top-level value must be a mapping")
+    profiles = data.get("profiles") or {}
+    if isinstance(profiles, dict):
+        for pname, pbody in profiles.items():
+            if isinstance(pbody, dict):
+                pbody.setdefault("name", pname)
+    try:
+        return Config.model_validate(dict(data))
+    except ValidationError as exc:
+        raise ConfigParseError(f"{path}: {exc}") from exc

nsc/config/models.py

@@ -0,0 +1,54 @@
+"""Pydantic models for ~/.nsc/config.yaml.
+
+Phase 2 is read-only; these models describe the on-disk shape. The runtime view
+(`ResolvedProfile`) lives in `nsc/cli/runtime.py` and is built by overlaying
+flags + env vars on top of a selected `Profile`.
+"""
+
+from __future__ import annotations
+
+from enum import StrEnum
+
+from pydantic import BaseModel, ConfigDict, Field, HttpUrl
+
+
+class _Frozen(BaseModel):
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+
+class OutputFormat(StrEnum):
+    TABLE = "table"
+    JSON = "json"
+    JSONL = "jsonl"
+    YAML = "yaml"
+    CSV = "csv"
+
+
+class SchemaRefresh(StrEnum):
+    MANUAL = "manual"
+    ON_HASH_CHANGE = "on-hash-change"
+    DAILY = "daily"
+    WEEKLY = "weekly"
+
+
+class Defaults(_Frozen):
+    output: OutputFormat = OutputFormat.TABLE
+    page_size: int = 50
+    timeout: float = 30.0
+    schema_refresh: SchemaRefresh = SchemaRefresh.ON_HASH_CHANGE
+
+
+class Profile(_Frozen):
+    name: str
+    url: HttpUrl
+    token: str | None = None
+    verify_ssl: bool = True
+    schema_url: HttpUrl | None = None
+    timeout: float | None = None
+
+
+class Config(_Frozen):
+    default_profile: str | None = None
+    profiles: dict[str, Profile] = Field(default_factory=dict)
+    defaults: Defaults = Field(default_factory=Defaults)
+    columns: dict[str, dict[str, list[str]]] = Field(default_factory=dict)

nsc/config/settings.py

@@ -0,0 +1,36 @@
+"""On-disk locations.
+
+Phase 1 only models the paths under `~/.nsc/`. Profiles, tokens, defaults, and
+the YAML config file are added in Phase 4.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True, slots=True)
+class Paths:
+    root: Path
+
+    @property
+    def config_file(self) -> Path:
+        return self.root / "config.yaml"
+
+    @property
+    def cache_dir(self) -> Path:
+        return self.root / "cache"
+
+    @property
+    def logs_dir(self) -> Path:
+        return self.root / "logs"
+
+
+def default_paths() -> Paths:
+    """Return the default `~/.nsc/` Paths, honoring `NSC_HOME` if set."""
+    override = os.environ.get("NSC_HOME")
+    if override:
+        return Paths(root=Path(override).expanduser().resolve())
+    return Paths(root=Path.home() / ".nsc")

nsc/config/writer.py

@@ -0,0 +1,207 @@
+"""Round-trip-preserving writes for `~/.nsc/config.yaml`.
+
+This module is the write counterpart to `nsc/config/loader.py`. It exposes:
+
+* `load_round_trip(path)` / `dump_round_trip(doc)` — parse and serialize using
+  `YAML(typ="rt")`. Unlike the loader, the writer's YAML does NOT register an
+  `!env` constructor, so tagged scalars round-trip through unchanged.
+* `set_path(doc, dotted, value)` / `unset_path(doc, dotted)` — dotted-path
+  mutators that preserve comments and key order.
+* `atomic_write(path, text)` — tempfile + fsync + os.replace, 0600 mode.
+* `acquire_lock(path)` — best-effort `flock` context manager.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import io
+import logging
+import os
+import tempfile
+from collections.abc import Iterator
+from pathlib import Path
+from typing import Any
+
+from ruamel.yaml import YAML
+from ruamel.yaml.comments import CommentedMap, TaggedScalar
+from ruamel.yaml.constructor import BaseConstructor
+from ruamel.yaml.nodes import ScalarNode
+
+_log = logging.getLogger(__name__)
+_FILE_MODE = 0o600
+
+
+def atomic_write(path: Path, text: str) -> None:
+    """Write `text` to `path` atomically with 0600 permissions.
+
+    Strategy: create a sibling temp file in the same directory, fsync it,
+    chmod 0600, then `os.replace` it onto the target. On any failure
+    before or during `os.replace`, the original file is untouched and
+    the temp file is cleaned up.
+    """
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fd, tmp_path = tempfile.mkstemp(
+        prefix=f".{path.name}.",
+        suffix=".tmp",
+        dir=str(path.parent),
+    )
+    tmp = Path(tmp_path)
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as fh:
+            fh.write(text)
+            fh.flush()
+            os.fsync(fh.fileno())
+        os.chmod(tmp, _FILE_MODE)
+        os.replace(tmp, path)
+    except BaseException:
+        with contextlib.suppress(FileNotFoundError):
+            tmp.unlink()
+        raise
+
+
+@contextlib.contextmanager
+def acquire_lock(path: Path) -> Iterator[None]:
+    """Best-effort exclusive lock on `path`'s sidecar lock file.
+
+    Uses `fcntl.flock` on POSIX; on platforms without it (or on NFS-style
+    filesystems where it is a no-op), logs a debug note and yields without
+    blocking. The lock is sidecar-on-purpose (`<name>.lock`) so we never
+    truncate the target file via locking.
+    """
+    lock_path = path.with_suffix(path.suffix + ".lock")
+    lock_path.parent.mkdir(parents=True, exist_ok=True)
+    try:
+        import fcntl  # noqa: PLC0415  # platform-conditional: absent on Windows.
+    except ImportError:
+        _log.debug("fcntl unavailable; proceeding without flock on %s", path)
+        yield
+        return
+
+    fd = os.open(str(lock_path), os.O_CREAT | os.O_RDWR, 0o600)
+    locked = False
+    try:
+        try:
+            fcntl.flock(fd, fcntl.LOCK_EX)
+            locked = True
+        except OSError as exc:
+            _log.debug("flock failed on %s (%s); proceeding without it", lock_path, exc)
+        yield
+    finally:
+        if locked:
+            with contextlib.suppress(OSError):
+                fcntl.flock(fd, fcntl.LOCK_UN)
+        os.close(fd)
+
+
+class ConfigWriteError(Exception):
+    """Raised when a config write violates the dotted-path contract."""
+
+
+def _construct_env_tag(_loader: BaseConstructor, node: ScalarNode) -> TaggedScalar:
+    return TaggedScalar(value=str(node.value), style=None, tag="!env")
+
+
+def _writer_yaml() -> YAML:
+    """Round-trip YAML for the writer.
+
+    The writer round-trips the *file* surface, so a `!env FOO` scalar must
+    come back out as `!env FOO`, not as the resolved string. We override the
+    `!env` constructor with one that returns a `TaggedScalar`, preserving the
+    tag through dump.
+
+    ruamel.yaml's `add_constructor` registers at the class level on
+    `RoundTripConstructor`, so the most recent registration wins for every
+    later `YAML(typ="rt")` instance in the same process. Both this factory and
+    `nsc.config.loader._round_trip_yaml` register fresh on every call to
+    ensure the local intent wins, but tests that interleave loader and writer
+    parsers can still observe the cross-instance side effect — keep that in
+    mind when adding tests that depend on `!env` resolution semantics.
+    """
+    yaml = YAML(typ="rt")
+    yaml.preserve_quotes = True
+    yaml.constructor.add_constructor("!env", _construct_env_tag)
+    return yaml
+
+
+def load_round_trip(path: Path) -> CommentedMap:
+    """Parse `path` into a `CommentedMap` ready for in-place mutation.
+
+    Returns an empty `CommentedMap` if the file is missing or empty so callers
+    can `set_path` into a fresh doc.
+    """
+    if not path.exists():
+        return CommentedMap()
+    text = path.read_text(encoding="utf-8")
+    if not text.strip():
+        return CommentedMap()
+    doc = _writer_yaml().load(io.StringIO(text))
+    if doc is None:
+        return CommentedMap()
+    if not isinstance(doc, CommentedMap):
+        raise ConfigWriteError(f"{path}: top-level value must be a mapping")
+    return doc
+
+
+def dump_round_trip(doc: CommentedMap) -> str:
+    """Serialize `doc` back to YAML, preserving comments, order, and tags."""
+    buf = io.StringIO()
+    _writer_yaml().dump(doc, buf)
+    return buf.getvalue()
+
+
+def _split(dotted: str) -> list[str]:
+    parts = [p for p in dotted.split(".") if p]
+    if not parts:
+        raise ConfigWriteError("path must be non-empty")
+    return parts
+
+
+def set_path(doc: CommentedMap, dotted: str, value: Any) -> None:
+    """Set `doc[a][b]...[leaf] = value`, creating intermediate maps as needed.
+
+    Refuses to descend past a scalar (would discard data) or to overwrite a
+    map with a scalar at the leaf (likewise). Both raise `ConfigWriteError`.
+    """
+    parts = _split(dotted)
+    cursor: Any = doc
+    for i, key in enumerate(parts[:-1]):
+        nxt = cursor.get(key) if isinstance(cursor, CommentedMap) else None
+        if nxt is None:
+            nxt = CommentedMap()
+            cursor[key] = nxt
+        elif not isinstance(nxt, CommentedMap):
+            joined = ".".join(parts[: i + 1])
+            raise ConfigWriteError(
+                f"cannot descend into scalar at {joined!r}; "
+                f"refusing to overwrite a value with a map"
+            )
+        cursor = nxt
+    leaf_key = parts[-1]
+    existing = cursor.get(leaf_key) if isinstance(cursor, CommentedMap) else None
+    if isinstance(existing, CommentedMap):
+        raise ConfigWriteError(f"refusing to overwrite map at {dotted!r} with a scalar value")
+    cursor[leaf_key] = value
+
+
+def unset_path(doc: CommentedMap, dotted: str) -> None:
+    """Remove `doc[a][b]...[leaf]` and prune empty parent maps.
+
+    No-op if any segment is missing. Pruning stops at non-empty parents.
+    """
+    parts = _split(dotted)
+    chain: list[tuple[CommentedMap, str]] = []
+    cursor: Any = doc
+    for key in parts[:-1]:
+        if not isinstance(cursor, CommentedMap) or key not in cursor:
+            return
+        chain.append((cursor, key))
+        cursor = cursor[key]
+    leaf_key = parts[-1]
+    if not isinstance(cursor, CommentedMap) or leaf_key not in cursor:
+        return
+    del cursor[leaf_key]
+    for parent, key in reversed(chain):
+        if isinstance(parent[key], CommentedMap) and len(parent[key]) == 0:
+            del parent[key]
+        else:
+            break

nsc/http/__init__.py

@@ -0,0 +1,6 @@
+"""Sync HTTP client for NetBox."""
+
+from nsc.http.client import NetBoxClient
+from nsc.http.errors import NetBoxAPIError, NetBoxClientError
+
+__all__ = ["NetBoxAPIError", "NetBoxClient", "NetBoxClientError"]