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

nsc/model/command_model.py

@@ -0,0 +1,125 @@
+"""The normalized command-model.
+
+This module imports nothing from `nsc.cli`, `nsc.http`, Typer, Rich, or any
+other framework. It is pure data plus a few traversal helpers. Anything else
+in `nsc/` that needs the command tree depends on this module — and only this
+module — for it.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from enum import StrEnum
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class HttpMethod(StrEnum):
+    GET = "GET"
+    POST = "POST"
+    PATCH = "PATCH"
+    PUT = "PUT"
+    DELETE = "DELETE"
+    OPTIONS = "OPTIONS"
+    HEAD = "HEAD"
+
+
+class ParameterLocation(StrEnum):
+    QUERY = "query"
+    PATH = "path"
+    HEADER = "header"
+    COOKIE = "cookie"
+    BODY = "body"
+
+
+class PrimitiveType(StrEnum):
+    STRING = "string"
+    INTEGER = "integer"
+    NUMBER = "number"
+    BOOLEAN = "boolean"
+    ARRAY = "array"
+    OBJECT = "object"
+    UNKNOWN = "unknown"
+
+
+class _Frozen(BaseModel):
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+
+class Parameter(_Frozen):
+    name: str
+    location: ParameterLocation
+    primitive: PrimitiveType = PrimitiveType.UNKNOWN
+    required: bool = False
+    description: str | None = None
+    enum: list[str] | None = None
+
+
+class FieldShape(_Frozen):
+    primitive: PrimitiveType = PrimitiveType.UNKNOWN
+    enum: list[str] | None = None
+    nullable: bool = False
+
+
+class RequestBodyShape(_Frozen):
+    top_level: Literal["object", "array", "object_or_array"]
+    required: list[str] = Field(default_factory=list)
+    fields: dict[str, FieldShape] = Field(default_factory=dict)
+    sensitive_paths: tuple[str, ...] = ()
+
+
+class Operation(_Frozen):
+    operation_id: str
+    http_method: HttpMethod
+    path: str
+    summary: str | None = None
+    description: str | None = None
+    parameters: list[Parameter] = Field(default_factory=list)
+    request_body: RequestBodyShape | None = None
+    default_columns: list[str] | None = None
+
+
+class Resource(_Frozen):
+    name: str
+    list_op: Operation | None = None
+    get_op: Operation | None = None
+    create_op: Operation | None = None
+    update_op: Operation | None = None
+    replace_op: Operation | None = None
+    delete_op: Operation | None = None
+    custom_actions: list[Operation] = Field(default_factory=list)
+
+
+class Tag(_Frozen):
+    name: str
+    description: str | None = None
+    resources: dict[str, Resource] = Field(default_factory=dict)
+
+
+class CommandModel(_Frozen):
+    """The full normalized tree: tags → resources → operations."""
+
+    info_title: str
+    info_version: str
+    schema_hash: str
+    tags: dict[str, Tag] = Field(default_factory=dict)
+
+    def iter_operations(self) -> Iterator[tuple[str, str, Operation]]:
+        """Yield `(tag, resource, operation)` triples in deterministic order."""
+        for tag_name in sorted(self.tags):
+            tag = self.tags[tag_name]
+            for resource_name in sorted(tag.resources):
+                resource = tag.resources[resource_name]
+                for op in (
+                    resource.list_op,
+                    resource.get_op,
+                    resource.create_op,
+                    resource.update_op,
+                    resource.replace_op,
+                    resource.delete_op,
+                ):
+                    if op is not None:
+                        yield (tag_name, resource_name, op)
+                for op in resource.custom_actions:
+                    yield (tag_name, resource_name, op)

nsc/output/__init__.py

@@ -0,0 +1 @@
+"""Output formatters: flatten + json/jsonl/yaml/csv. Table + dispatch land in Task 9."""

nsc/output/csv_.py

@@ -0,0 +1,34 @@
+"""CSV output formatter (with nested-field flattening)."""
+
+from __future__ import annotations
+
+import csv
+import sys
+from typing import Any, TextIO
+
+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:
+        return
+    flat_records = [flatten(r, columns=columns) for r in records]
+    fieldnames = columns if columns is not None else _gather_fieldnames(flat_records)
+    writer = csv.DictWriter(stream, fieldnames=fieldnames, extrasaction="ignore")
+    writer.writeheader()
+    for row in flat_records:
+        writer.writerow({k: ("" if v is None else v) for k, v in row.items()})
+
+
+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())

nsc/output/errors.py

@@ -0,0 +1,346 @@
+"""Stable JSON error envelope and exit-code mapping for Phase 3+.
+
+This module is the agent contract. Field names, values of `ErrorType`, and the
+`EXIT_CODES` table must never change once shipped.
+"""
+
+from __future__ import annotations
+
+from enum import Enum, StrEnum
+from typing import Any, Literal, TextIO
+
+from pydantic import BaseModel, ConfigDict, Field
+from rich.console import Console
+from rich.panel import Panel
+
+from nsc.config.models import OutputFormat
+from nsc.model.command_model import HttpMethod
+
+
+class ErrorType(StrEnum):
+    AUTH = "auth"
+    NOT_FOUND = "not_found"
+    VALIDATION = "validation"
+    CONFLICT = "conflict"
+    RATE_LIMITED = "rate_limited"
+    SERVER = "server"
+    TRANSPORT = "transport"
+    SCHEMA = "schema"
+    CONFIG = "config"
+    CLIENT = "client"
+    INTERNAL = "internal"
+    AMBIGUOUS_ALIAS = "ambiguous_alias"
+    UNKNOWN_ALIAS = "unknown_alias"
+    INPUT_ERROR = "input_error"
+
+
+EXIT_CODES: dict[ErrorType, int] = {
+    ErrorType.INTERNAL: 1,
+    ErrorType.SCHEMA: 3,
+    ErrorType.VALIDATION: 4,
+    ErrorType.INPUT_ERROR: 4,
+    ErrorType.SERVER: 5,
+    ErrorType.CLIENT: 6,
+    ErrorType.TRANSPORT: 7,
+    ErrorType.AUTH: 8,
+    ErrorType.NOT_FOUND: 9,
+    ErrorType.CONFLICT: 10,
+    ErrorType.RATE_LIMITED: 11,
+    ErrorType.CONFIG: 12,
+    ErrorType.AMBIGUOUS_ALIAS: 13,
+    ErrorType.UNKNOWN_ALIAS: 14,
+}
+
+
+class _Frozen(BaseModel):
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+
+class ErrorEnvelope(_Frozen):
+    error: str
+    type: ErrorType
+    endpoint: str | None = None
+    method: HttpMethod | None = None
+    operation_id: str | None = None
+    status_code: int | None = None
+    attempt_n: int | None = None
+    audit_log_path: str | None = None
+    record_index: int | None = None
+    details: dict[str, Any] = Field(default_factory=dict)
+
+
+def render_to_json(env: ErrorEnvelope) -> str:
+    """Serialize the envelope as compact, one-line JSON for stdout."""
+    return env.model_dump_json()
+
+
+class RenderTarget(Enum):
+    JSON_STDOUT = "json_stdout"
+    JSON_STDERR = "json_stderr"
+    RICH_STDERR = "rich_stderr"
+
+
+def select_render_target(*, output_format: OutputFormat, stdout_is_tty: bool) -> RenderTarget:
+    """Decide where the error envelope should render.
+
+    Spec §4.2.3:
+      - --output json (or table-piped, which falls back to json) → JSON to stdout.
+      - --output table on a TTY → Rich panel to stderr.
+      - Any other piped format (csv/yaml/jsonl) → JSON to stderr; stdout
+        reserved for partial-success records produced by the formatter.
+    """
+    if output_format is OutputFormat.JSON:
+        return RenderTarget.JSON_STDOUT
+    if output_format is OutputFormat.TABLE:
+        if stdout_is_tty:
+            return RenderTarget.RICH_STDERR
+        return RenderTarget.JSON_STDOUT
+    return RenderTarget.JSON_STDERR
+
+
+def render_to_rich_stderr(env: ErrorEnvelope, *, stream: TextIO) -> None:
+    """Render the envelope as a Rich panel to the given stream (stderr in prod)."""
+    console = Console(file=stream, soft_wrap=True, force_terminal=False)
+    body_lines = [
+        f"[bold red]{env.type.value}[/]: {env.error}",
+    ]
+    if env.endpoint:
+        body_lines.append(f"endpoint: {env.endpoint}")
+    if env.method is not None:
+        body_lines.append(f"method:   {env.method.value}")
+    if env.status_code is not None:
+        body_lines.append(f"status:   {env.status_code}")
+    if env.operation_id:
+        body_lines.append(f"op:       {env.operation_id}")
+    if env.attempt_n is not None:
+        body_lines.append(f"attempt:  {env.attempt_n}")
+    if env.audit_log_path:
+        body_lines.append(f"audit:    {env.audit_log_path}")
+    if env.details:
+        body_lines.append(f"details:  {env.details}")
+    console.print(Panel("\n".join(body_lines), title="nsc error", border_style="red"))
+
+
+class ClientError(Exception):
+    """A user-facing CLI usage error that should map directly to an ErrorEnvelope.
+
+    Carries a fully-shaped envelope so the handler can re-emit it without
+    re-classifying.
+    """
+
+    def __init__(self, envelope: ErrorEnvelope) -> None:
+        super().__init__(envelope.error)
+        self.envelope = envelope
+
+
+def client_envelope(
+    message: str, *, operation_id: str | None = None, **details: Any
+) -> ErrorEnvelope:
+    return ErrorEnvelope(
+        error=message,
+        type=ErrorType.CLIENT,
+        operation_id=operation_id,
+        details=details,
+    )
+
+
+def input_error_envelope(
+    *,
+    message: str,
+    bad_lines: list[dict[str, Any]],
+    operation_id: str | None = None,
+) -> ErrorEnvelope:
+    """Build the structured envelope for NDJSON parse failures.
+
+    `bad_lines` is a list of `{"line": int, "reason": str}` dicts. The caller
+    is responsible for capping the list at 20 entries (spec §4.4).
+    """
+    return ErrorEnvelope(
+        error=message,
+        type=ErrorType.INPUT_ERROR,
+        operation_id=operation_id,
+        details={"bad_lines": bad_lines},
+    )
+
+
+_VERB_TO_FULL_PATH_VERB: dict[str, str] = {
+    "ls": "list",
+    "get": "get",
+    "rm": "delete",
+}
+
+
+def ambiguous_alias_envelope(
+    *,
+    verb: str,
+    term: str,
+    candidates: list[tuple[str, str]],
+) -> ErrorEnvelope:
+    """Build the envelope for an alias term that resolves to ≥2 resources.
+
+    `candidates` is a list of `(tag, resource)` pairs; the envelope renders
+    them as a list of `{"tag": ..., "resource": ...}` objects so JSON
+    consumers don't have to parse positional pairs.
+    """
+    if verb not in _VERB_TO_FULL_PATH_VERB:
+        raise ValueError(
+            f"ambiguous_alias_envelope does not support verb={verb!r} "
+            f"(supported: {sorted(_VERB_TO_FULL_PATH_VERB)})"
+        )
+    rendered = [{"tag": t, "resource": r} for t, r in candidates]
+    pretty = ", ".join(f"`{t} {r}`" for t, r in candidates)
+    return ErrorEnvelope(
+        error=(
+            f"`nsc {verb} {term}` is ambiguous — matches: {pretty}. "
+            f"Use the full path: `nsc <tag> <resource> {_VERB_TO_FULL_PATH_VERB[verb]}`."
+        ),
+        type=ErrorType.AMBIGUOUS_ALIAS,
+        details={"verb": verb, "term": term, "candidates": rendered},
+    )
+
+
+def unknown_alias_envelope(
+    *,
+    verb: str,
+    term: str,
+    reason: str = "no_such_resource",
+) -> ErrorEnvelope:
+    """Build the envelope for an alias term that resolves to zero resources.
+
+    `reason="no_such_resource"` is the standard ls/get/rm case; the message
+    suggests `nsc commands` for resource discovery. `reason="search_endpoint_unavailable"`
+    is the search-specific case (schema does not expose `/api/search/`); the
+    message must not suggest `nsc commands` since that wouldn't help.
+    """
+    if reason == "search_endpoint_unavailable":
+        message = (
+            "this NetBox schema does not expose `/api/search/`; "
+            "`nsc search` is unavailable for this server"
+        )
+    else:
+        message = (
+            f"unknown resource `{term}` for `nsc {verb}`; "
+            f"run `nsc commands` to list known resources"
+        )
+    return ErrorEnvelope(
+        error=message,
+        type=ErrorType.UNKNOWN_ALIAS,
+        details={"verb": verb, "term": term, "reason": reason},
+    )
+
+
+ERROR_TYPE_PRECEDENCE: list[ErrorType] = [
+    ErrorType.INTERNAL,
+    ErrorType.TRANSPORT,
+    ErrorType.SERVER,
+    ErrorType.VALIDATION,
+    ErrorType.CONFLICT,
+    ErrorType.RATE_LIMITED,
+    ErrorType.NOT_FOUND,
+    ErrorType.AUTH,
+    ErrorType.INPUT_ERROR,
+    ErrorType.CLIENT,
+    ErrorType.SCHEMA,
+    ErrorType.CONFIG,
+    ErrorType.AMBIGUOUS_ALIAS,
+    ErrorType.UNKNOWN_ALIAS,
+]
+"""Strict ordering for picking a single exit code from a mixed-failure run.
+
+Used by `--on-error continue` to map a list of per-record failures to one
+final exit code. Spec §4.5.
+"""
+
+
+def worst_error_type(types: list[ErrorType]) -> ErrorType:
+    if not types:
+        raise ValueError("worst_error_type called with empty list")
+    return next(t for t in ERROR_TYPE_PRECEDENCE if t in types)
+
+
+def summary_envelope(
+    *,
+    attempted: int,
+    failures: list[ErrorEnvelope],
+    on_error: Literal["stop", "continue"],
+    operation_id: str | None,
+    total_records: int,
+) -> ErrorEnvelope:
+    """Build the final envelope for a multi-record loop (spec §4.5, §7.3).
+
+    Args:
+        attempted: Number of records the loop reached (success + failure).
+        failures: Per-record failure envelopes (one per failed attempt).
+        on_error: "stop" or "continue" — controls envelope shape.
+        operation_id: Operation that the loop ran.
+        total_records: Total records in the input (for partial_progress.remaining).
+
+    Returns:
+        ErrorEnvelope whose `type` equals the worst failure type by
+        precedence, with `details.partial_progress = {success, failed, remaining}`.
+        On "stop" sets `record_index` to the first failure's index. On "continue"
+        adds `details.failures: [{record_index, type, status_code, error}, ...]`.
+    """
+    if not failures:
+        raise ValueError("summary_envelope requires at least one failure")
+    failed = len(failures)
+    success = attempted - failed
+    remaining = max(0, total_records - attempted)
+    chosen_type = worst_error_type([f.type for f in failures])
+
+    details: dict[str, Any] = {
+        "partial_progress": {
+            "success": success,
+            "failed": failed,
+            "remaining": remaining,
+        },
+        "on_error": on_error,
+        "applied": True,
+    }
+
+    if on_error == "stop":
+        first = failures[0]
+        return ErrorEnvelope(
+            error=first.error,
+            type=chosen_type,
+            operation_id=operation_id,
+            status_code=first.status_code,
+            record_index=first.record_index,
+            details=details,
+        )
+
+    details["failures"] = [
+        {
+            "record_index": f.record_index,
+            "type": f.type.value,
+            "status_code": f.status_code,
+            "error": f.error,
+        }
+        for f in failures
+    ]
+    return ErrorEnvelope(
+        error=(f"{failed} of {attempted} records failed (worst type: {chosen_type.value})"),
+        type=chosen_type,
+        operation_id=operation_id,
+        record_index=None,
+        details=details,
+    )
+
+
+__all__ = [
+    "ERROR_TYPE_PRECEDENCE",
+    "EXIT_CODES",
+    "ClientError",
+    "ErrorEnvelope",
+    "ErrorType",
+    "RenderTarget",
+    "ambiguous_alias_envelope",
+    "client_envelope",
+    "input_error_envelope",
+    "render_to_json",
+    "render_to_rich_stderr",
+    "select_render_target",
+    "summary_envelope",
+    "unknown_alias_envelope",
+    "worst_error_type",
+]

nsc/output/explain.py

@@ -0,0 +1,194 @@
+"""ExplainTrace and FieldDecision — agent contract for `--explain`.
+
+Phase 3a defined the types; Phase 3b adds `build_for(...)` and renderers.
+
+The schema_version on ExplainTrace is part of the agent contract: bump it on
+any breaking change to the JSON shape.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Literal, TextIO
+
+from pydantic import BaseModel, ConfigDict, Field
+from rich.console import Console
+from rich.panel import Panel
+
+from nsc.cli.writes.apply import ResolvedRequest
+from nsc.cli.writes.bulk import RoutingDecision
+from nsc.cli.writes.input import RawWriteInput
+from nsc.cli.writes.preflight import PreflightResult
+from nsc.model.command_model import Operation
+
+DECISION_CAP = 200
+
+
+class _Frozen(BaseModel):
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+
+class FieldDecision(_Frozen):
+    field_path: str
+    source: Literal["file", "field_flag", "default", "schema_cast"]
+    raw_value: Any
+    resolved_value: Any
+    note: str | None = None
+
+
+class ExplainTrace(_Frozen):
+    schema_version: int = 1
+    operation_id: str
+    operation_summary: str | None = None
+    method_reasoning: str
+    url_reasoning: str
+    bulk_reasoning: str | None = None
+    decisions: list[FieldDecision] = Field(default_factory=list)
+    decisions_truncated: bool = False
+    requests: list[ResolvedRequest] = Field(default_factory=list)
+    preflight: PreflightResult | None = None
+
+    @classmethod
+    def build_for(
+        cls,
+        operation: Operation,
+        raw: RawWriteInput,
+        preflight: PreflightResult,
+        requests: list[ResolvedRequest],
+        *,
+        field_overrides: set[str],
+        routing_decision: RoutingDecision | None = None,
+    ) -> ExplainTrace:
+        decisions, truncated = _build_decisions(raw, requests, field_overrides)
+        return cls(
+            operation_id=operation.operation_id,
+            operation_summary=operation.summary,
+            method_reasoning=_method_reasoning(operation),
+            url_reasoning=_url_reasoning(operation, requests),
+            bulk_reasoning=routing_decision.reasoning if routing_decision else None,
+            decisions=decisions,
+            decisions_truncated=truncated,
+            requests=list(requests),
+            preflight=preflight,
+        )
+
+
+def _build_decisions(
+    raw: RawWriteInput,
+    requests: list[ResolvedRequest],
+    field_overrides: set[str],
+) -> tuple[list[FieldDecision], bool]:
+    decisions: list[FieldDecision] = []
+    for index, record in enumerate(raw.records):
+        resolved_body = _resolved_body_for_record(requests, index)
+        for key, raw_value in record.items():
+            if len(decisions) >= DECISION_CAP:
+                return decisions, True
+            resolved_value = (
+                resolved_body.get(key) if isinstance(resolved_body, dict) else raw_value
+            )
+            source = _decide_source(key, field_overrides, raw)
+            note = _decide_note(raw_value, resolved_value, key, field_overrides)
+            decisions.append(
+                FieldDecision(
+                    field_path=_record_path(index, key, raw),
+                    source=source,
+                    raw_value=raw_value,
+                    resolved_value=resolved_value,
+                    note=note,
+                )
+            )
+    return decisions, False
+
+
+def _resolved_body_for_record(
+    requests: list[ResolvedRequest], record_index: int
+) -> dict[str, Any] | None:
+    for r in requests:
+        if record_index in r.record_indices and isinstance(r.body, dict):
+            return r.body
+    return None
+
+
+def _decide_source(
+    key: str, field_overrides: set[str], raw: RawWriteInput
+) -> Literal["file", "field_flag", "default", "schema_cast"]:
+    if key in field_overrides:
+        return "field_flag"
+    if raw.source == "fields_only":
+        return "field_flag"
+    return "file"
+
+
+def _decide_note(
+    raw_value: Any, resolved_value: Any, key: str, field_overrides: set[str]
+) -> str | None:
+    parts: list[str] = []
+    if key in field_overrides and raw_value is not None:
+        parts.append("override from --field flag")
+    if raw_value != resolved_value:
+        parts.append(f"schema_cast: {type(raw_value).__name__} → {type(resolved_value).__name__}")
+    return "; ".join(parts) if parts else None
+
+
+def _record_path(index: int, key: str, raw: RawWriteInput) -> str:
+    return f"records[{index}].{key}" if raw.is_explicit_list else key
+
+
+def _method_reasoning(operation: Operation) -> str:
+    return f"{operation.http_method.value} per OpenAPI operation {operation.operation_id!r}"
+
+
+def _url_reasoning(operation: Operation, requests: list[ResolvedRequest]) -> str:
+    if not requests:
+        return f"path template {operation.path!r}; no path vars resolved"
+    request = requests[0]
+    if request.path_vars:
+        return f"path template {operation.path!r} with vars {request.path_vars}"
+    return f"path template {operation.path!r}; no path vars"
+
+
+def render_to_json(trace: ExplainTrace) -> str:
+    return trace.model_dump_json()
+
+
+def render_to_rich_stdout(trace: ExplainTrace, *, stream: TextIO) -> None:
+    console = Console(file=stream, soft_wrap=True, force_terminal=False)
+    body = [
+        f"[bold cyan]operation:[/] {trace.operation_id}",
+    ]
+    if trace.operation_summary:
+        body.append(f"summary:   {trace.operation_summary}")
+    body.append(f"method:    {trace.method_reasoning}")
+    body.append(f"url:       {trace.url_reasoning}")
+    if trace.bulk_reasoning:
+        body.append(f"bulk:      {trace.bulk_reasoning}")
+    for r in trace.requests:
+        body.append(f"  → {r.method.value} {r.url}")
+        if r.body is not None:
+            body.append(f"    body: {r.body}")
+    if trace.preflight is not None and not trace.preflight.ok:
+        body.append("preflight: [red]FAIL[/]")
+        for issue in trace.preflight.issues:
+            loc = f"records[{issue.record_index}].{issue.field_path}"
+            body.append(f"  [{issue.kind}] {loc}: {issue.message}")
+    elif trace.preflight is not None:
+        body.append("preflight: [green]OK[/]")
+    if trace.decisions:
+        body.append("decisions:")
+        for d in trace.decisions:
+            extra = f" — {d.note}" if d.note else ""
+            body.append(
+                f"  {d.field_path}  [{d.source}]  {d.raw_value!r} → {d.resolved_value!r}{extra}"
+            )
+        if trace.decisions_truncated:
+            body.append(f"  … truncated at {DECISION_CAP} entries")
+    console.print(Panel("\n".join(body), title="nsc explain", border_style="cyan"))
+
+
+__all__ = [
+    "DECISION_CAP",
+    "ExplainTrace",
+    "FieldDecision",
+    "render_to_json",
+    "render_to_rich_stdout",
+]