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

nsc/cli/runtime.py

@@ -0,0 +1,290 @@
+"""Runtime context, profile resolution, exit-code mapping.
+
+`RuntimeContext` carries the live `NetBoxClient`, command model, config, and
+output preferences for a single invocation. It is populated by the bootstrap
+pipeline in the root Typer callback (Task 12) and consumed by the dynamic
+read handlers.
+"""
+
+from __future__ import annotations
+
+import sys
+import uuid
+from collections.abc import Iterable, Iterator, Mapping
+from typing import Any, Literal
+
+from pydantic import BaseModel, ConfigDict, HttpUrl, SkipValidation
+
+from nsc.cache.store import ADHOC_PROFILE
+from nsc.config.models import Config, OutputFormat, Profile
+from nsc.config.settings import default_paths
+from nsc.http.client import NetBoxClient
+from nsc.http.errors import NetBoxAPIError, NetBoxClientError
+from nsc.model.command_model import CommandModel, Operation
+from nsc.output.errors import (
+    EXIT_CODES,
+    ErrorEnvelope,
+    ErrorType,
+    RenderTarget,
+    render_to_json,
+    render_to_rich_stderr,
+    select_render_target,
+)
+
+# Named constants to satisfy PLR2004 (no magic numbers in comparisons).
+_STATUS_UNAUTHORIZED = 401
+_STATUS_FORBIDDEN = 403
+_STATUS_NOT_FOUND = 404
+_STATUS_CONFLICT = 409
+_STATUS_TOO_MANY = 429
+_STATUS_4XX_MIN = 400
+_STATUS_5XX_MIN = 500
+
+
+class _Frozen(BaseModel):
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+
+class CLIOverrides(_Frozen):
+    profile: str | None = None
+    url: str | None = None
+    token: str | None = None
+    insecure: bool | None = None
+    schema_override: str | None = None
+    output: str | None = None
+
+
+class ResolvedProfile(_Frozen):
+    name: str
+    url: HttpUrl
+    token: str
+    verify_ssl: bool
+    timeout: float
+    schema_url: HttpUrl | None
+
+
+class NoProfileError(Exception):
+    """No URL/token available from any source."""
+
+
+class UnknownProfileError(Exception):
+    """A profile was requested by name but is not in the config."""
+
+
+def resolve_profile(
+    config: Config,
+    overrides: CLIOverrides,
+    env: Mapping[str, str],
+) -> ResolvedProfile:
+    base, base_name = _select_base_profile(config, overrides, env)
+
+    url = _first_set(overrides.url, env.get("NSC_URL"), str(base.url) if base else None)
+    token = _first_set(overrides.token, env.get("NSC_TOKEN"), base.token if base else None)
+    if url is None or token is None:
+        raise NoProfileError(
+            "no NetBox URL/token configured (set NSC_URL+NSC_TOKEN, "
+            "pass --url and --token, or configure a profile in ~/.nsc/config.yaml)"
+        )
+
+    insecure_env = _bool_env(env.get("NSC_INSECURE"))
+    if overrides.insecure is not None:
+        verify_ssl = not overrides.insecure
+    elif insecure_env is not None:
+        verify_ssl = not insecure_env
+    elif base is not None:
+        verify_ssl = base.verify_ssl
+    else:
+        verify_ssl = True
+
+    timeout = base.timeout if (base and base.timeout is not None) else config.defaults.timeout
+
+    schema_url_raw = _first_set(
+        _url_only(overrides.schema_override),
+        _url_only(env.get("NSC_SCHEMA")),
+        str(base.schema_url) if base and base.schema_url else None,
+    )
+
+    return ResolvedProfile(
+        name=base_name,
+        url=HttpUrl(url),
+        token=token,
+        verify_ssl=verify_ssl,
+        timeout=timeout,
+        schema_url=HttpUrl(schema_url_raw) if schema_url_raw else None,
+    )
+
+
+def _select_base_profile(
+    config: Config, overrides: CLIOverrides, env: Mapping[str, str]
+) -> tuple[Profile | None, str]:
+    name = overrides.profile or env.get("NSC_PROFILE") or config.default_profile
+    if name is None:
+        return None, ADHOC_PROFILE
+    if name not in config.profiles:
+        raise UnknownProfileError(f"profile {name!r} is not defined in ~/.nsc/config.yaml")
+    return config.profiles[name], name
+
+
+def _first_set(*values: str | None) -> str | None:
+    for v in values:
+        if v is not None and v != "":
+            return v
+    return None
+
+
+def _bool_env(raw: str | None) -> bool | None:
+    if raw is None:
+        return None
+    return raw.strip().lower() in {"1", "true", "yes", "on"}
+
+
+def _url_only(value: str | None) -> str | None:
+    """Return the value only if it looks like an HTTP(S) URL; else None.
+
+    `--schema`/`NSC_SCHEMA` may be a local path, in which case it should not
+    populate the profile's `schema_url` (which is HttpUrl-validated). The
+    schema_override flow consumes the raw value directly from `CLIOverrides`.
+    """
+    if value is None or not value:
+        return None
+    if value.startswith(("http://", "https://")):
+        return value
+    return None
+
+
+class RuntimeContext(BaseModel):
+    """Per-invocation runtime state.
+
+    Not frozen because `client` (a NetBoxClient wrapping httpx.Client) is mutable.
+    """
+
+    model_config = ConfigDict(arbitrary_types_allowed=True, extra="forbid")
+
+    resolved_profile: ResolvedProfile
+    config: Config
+    command_model: SkipValidation[CommandModel]
+    client: SkipValidation[NetBoxClient]
+    output_format: OutputFormat
+    debug: bool = False
+    page_size: int = 50
+    columns_override: list[str] | None = None
+    filters: list[tuple[str, str]] = []
+    limit: int | None = None
+    fetch_all: bool = False
+    compact: bool = False
+    apply: bool = False
+    explain: bool = False
+    strict: bool = False
+    file: str | None = None
+    fields: list[str] = []
+    file_format: str | None = None
+    bulk: bool | None = None
+    no_bulk: bool | None = None
+    on_error: Literal["stop", "continue"] = "stop"
+
+    def resolve_columns(self, tag: str, resource: str, operation: Operation) -> list[str] | None:
+        if self.columns_override is not None:
+            return self.columns_override
+        per_tag = self.config.columns.get(tag, {})
+        configured = per_tag.get(resource)
+        if configured is not None:
+            return configured
+        return operation.default_columns
+
+
+def apply_limit(
+    iterator: Iterable[dict[str, Any]],
+    *,
+    limit: int | None,
+    fetch_all: bool,
+    page_size: int,
+) -> Iterator[dict[str, Any]]:
+    cap: int | None
+    if limit is not None:
+        cap = limit
+    elif fetch_all:
+        cap = None
+    else:
+        cap = page_size
+    for n, record in enumerate(iterator):
+        if cap is not None and n >= cap:
+            return
+        yield record
+
+
+def _audit_log_path() -> str | None:
+    p = default_paths().logs_dir / "audit.jsonl"
+    return str(p) if p.exists() else None
+
+
+def _api_error_type(status_code: int) -> ErrorType:
+    if status_code in (_STATUS_UNAUTHORIZED, _STATUS_FORBIDDEN):
+        return ErrorType.AUTH
+    if status_code == _STATUS_NOT_FOUND:
+        return ErrorType.NOT_FOUND
+    if status_code == _STATUS_CONFLICT:
+        return ErrorType.CONFLICT
+    if status_code == _STATUS_TOO_MANY:
+        return ErrorType.RATE_LIMITED
+    if _STATUS_4XX_MIN <= status_code < _STATUS_5XX_MIN:
+        return ErrorType.VALIDATION
+    return ErrorType.SERVER
+
+
+def map_error(
+    exc: BaseException,
+    *,
+    operation_id: str | None = None,
+    attempt_n: int | None = None,
+) -> ErrorEnvelope:
+    """Translate a known nsc exception into an ErrorEnvelope. Unknown → internal."""
+    if isinstance(exc, NetBoxAPIError):
+        et = _api_error_type(exc.status_code)
+        details: dict[str, Any] = {}
+        if et is ErrorType.SERVER:
+            details = {"body_excerpt": exc.body_snippet, "retry_safe": False}
+        elif et is ErrorType.AUTH:
+            details = {"reason": "rejected"}
+        elif et is ErrorType.VALIDATION:
+            details = {"source": "server", "body_excerpt": exc.body_snippet}
+        return ErrorEnvelope(
+            error=str(exc),
+            type=et,
+            endpoint=exc.url,
+            status_code=exc.status_code,
+            attempt_n=attempt_n,
+            audit_log_path=_audit_log_path(),
+            operation_id=operation_id,
+            details=details,
+        )
+    if isinstance(exc, NetBoxClientError):
+        return ErrorEnvelope(
+            error=str(exc),
+            type=ErrorType.TRANSPORT,
+            endpoint=exc.url,
+            attempt_n=attempt_n,
+            audit_log_path=_audit_log_path(),
+            operation_id=operation_id,
+            details={"cause": "connect", "retry_safe": True},
+        )
+    if isinstance(exc, NoProfileError):
+        return ErrorEnvelope(error=str(exc), type=ErrorType.CONFIG)
+    if isinstance(exc, UnknownProfileError):
+        return ErrorEnvelope(error=str(exc), type=ErrorType.CONFIG)
+    return ErrorEnvelope(
+        error=f"internal error: {exc}",
+        type=ErrorType.INTERNAL,
+        details={"traceback_id": str(uuid.uuid4())},
+    )
+
+
+def emit_envelope(env: ErrorEnvelope, *, output_format: OutputFormat) -> int:
+    """Write the envelope to the right target and return the exit code."""
+    target = select_render_target(output_format=output_format, stdout_is_tty=sys.stdout.isatty())
+    if target is RenderTarget.JSON_STDOUT:
+        print(render_to_json(env), file=sys.stdout)
+    elif target is RenderTarget.JSON_STDERR:
+        print(render_to_json(env), file=sys.stderr)
+    else:
+        render_to_rich_stderr(env, stream=sys.stderr)
+    return EXIT_CODES.get(env.type, 1)

nsc/cli/skill_commands.py

@@ -0,0 +1,186 @@
+"""`nsc skill` — install the bundled portable Skill into agent harnesses.
+
+Phase 5c ships `install`. Default behavior is dry-run; `--apply` copies the
+bundled `SKILL.md` to each target's documented Skills directory. Targets
+whose convention is unknown print actionable manual instructions instead of
+guessing a path silently.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+from dataclasses import dataclass
+from enum import StrEnum
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from nsc.skill import BUNDLE_NAME, bundle_path
+
+
+class _Target(StrEnum):
+    CLAUDE_CODE = "claude-code"
+    CODEX = "codex"
+    GEMINI = "gemini"
+    COPILOT = "copilot"
+
+
+class _OutputFormat(StrEnum):
+    TABLE = "table"
+    JSON = "json"
+
+
+@dataclass(frozen=True, slots=True)
+class _Resolution:
+    target: _Target
+    path: Path | None
+    manual_instructions: str | None
+
+
+def _home() -> Path:
+    return Path(os.environ.get("HOME") or os.path.expanduser("~"))
+
+
+def _resolve_claude_code() -> _Resolution:
+    return _Resolution(
+        target=_Target.CLAUDE_CODE,
+        path=_home() / ".claude" / "skills" / BUNDLE_NAME / "SKILL.md",
+        manual_instructions=None,
+    )
+
+
+def _resolve_codex() -> _Resolution:
+    # Per T1 research (developers.openai.com/codex/skills): Codex CLI loads
+    # user-scoped skills from $HOME/.agents/skills/<name>/SKILL.md. The
+    # `.agents/` prefix is agent-tool-neutral, not codex-specific.
+    return _Resolution(
+        target=_Target.CODEX,
+        path=_home() / ".agents" / "skills" / BUNDLE_NAME / "SKILL.md",
+        manual_instructions=None,
+    )
+
+
+def _resolve_gemini() -> _Resolution:
+    return _Resolution(
+        target=_Target.GEMINI,
+        path=None,
+        manual_instructions=(
+            "Gemini CLI does not document a programmatic Skill install path "
+            "as of this nsc release. To use the bundled Skill: paste its "
+            "content into a project-scoped GEMINI.md or your Gemini system "
+            "prompt."
+        ),
+    )
+
+
+def _resolve_copilot() -> _Resolution:
+    return _Resolution(
+        target=_Target.COPILOT,
+        path=None,
+        manual_instructions=(
+            "GitHub Copilot CLI does not document a stable user-scoped Skill "
+            "install path as of this nsc release. To use the bundled Skill: "
+            "paste its content into .github/copilot-instructions.md or your "
+            "team's Copilot configuration."
+        ),
+    )
+
+
+_RESOLVERS = {
+    _Target.CLAUDE_CODE: _resolve_claude_code,
+    _Target.CODEX: _resolve_codex,
+    _Target.GEMINI: _resolve_gemini,
+    _Target.COPILOT: _resolve_copilot,
+}
+
+
+def _resolve(target: _Target) -> _Resolution:
+    return _RESOLVERS[target]()
+
+
+def _render_table(resolution: _Resolution, mode: str, written: bool, source: Path) -> str:
+    lines: list[str] = []
+    if resolution.path is None:
+        lines.append(f"nsc skill install --target {resolution.target.value}")
+        lines.append("")
+        assert resolution.manual_instructions is not None
+        lines.append(resolution.manual_instructions)
+        lines.append("")
+        lines.append(f"  source SKILL.md: {source}")
+        return "\n".join(lines)
+
+    if mode == "dry-run":
+        lines.append(
+            f"nsc skill install --target {resolution.target.value} (dry-run) "
+            "— pass --apply to install"
+        )
+        lines.append(f"  would write to {resolution.path}")
+        lines.append(f"  source: {source}")
+    elif written:
+        lines.append(f"✓ installed netbox-super-cli skill at {resolution.path}")
+    else:
+        lines.append(f"nsc skill install --target {resolution.target.value} (no-op)")
+    return "\n".join(lines)
+
+
+def _render_json(resolution: _Resolution, mode: str, written: bool, source: Path) -> str:
+    payload: dict[str, object] = {
+        "mode": mode,
+        "target": resolution.target.value,
+        "source": str(source),
+        "destination": str(resolution.path) if resolution.path else None,
+        "manual": resolution.path is None,
+    }
+    if resolution.manual_instructions is not None:
+        payload["instructions"] = resolution.manual_instructions
+    if mode == "apply":
+        payload["written"] = written
+    return json.dumps(payload)
+
+
+def register(app: typer.Typer) -> None:
+    skill_app = typer.Typer(
+        name="skill",
+        help="Manage the bundled portable Skill for AI agent harnesses.",
+        no_args_is_help=True,
+    )
+
+    @skill_app.command("install")
+    def install_cmd(
+        target: Annotated[
+            _Target,
+            typer.Option(
+                "--target",
+                "-t",
+                help="Which agent harness to install the Skill into.",
+                case_sensitive=False,
+            ),
+        ],
+        apply_: Annotated[
+            bool,
+            typer.Option("--apply", help="Actually copy the file (default: dry-run)."),
+        ] = False,
+        output: Annotated[
+            _OutputFormat,
+            typer.Option("--output", "-o", help="table|json"),
+        ] = _OutputFormat.TABLE,
+    ) -> None:
+        resolution = _resolve(target)
+        mode = "apply" if apply_ else "dry-run"
+        written = False
+
+        with bundle_path() as source:
+            if apply_ and resolution.path is not None:
+                resolution.path.parent.mkdir(parents=True, exist_ok=True)
+                shutil.copy2(source, resolution.path)
+                written = True
+
+            if output is _OutputFormat.JSON:
+                typer.echo(_render_json(resolution, mode, written, source))
+            else:
+                typer.echo(_render_table(resolution, mode, written, source))
+
+    app.add_typer(skill_app, name="skill")

nsc/cli/writes/__init__.py

@@ -0,0 +1,10 @@
+"""Write pipeline (Phase 3b/3c).
+
+Stages:
+  input.collect()      → RawWriteInput
+  preflight.check()    → PreflightResult
+  apply.resolve()      → ResolvedRequest
+  confirmation.*       → flag-conflict gating helpers
+"""
+
+from __future__ import annotations

nsc/cli/writes/apply.py

@@ -0,0 +1,177 @@
+"""Stage 3 of the write pipeline: build the wire-shape ResolvedRequest.
+
+3b emits one ResolvedRequest per input record (single-record loop shape).
+3c adds a bulk variant gated by ``mode=RoutingMode.BULK`` that produces a
+single request with a list-shaped body and ``record_indices=[0..N)``.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from nsc.cli.writes.bulk import RoutingMode
+from nsc.cli.writes.coercion import FALSY as _FALSY
+from nsc.cli.writes.coercion import TRUTHY as _TRUTHY
+from nsc.cli.writes.input import RawWriteInput
+from nsc.model.command_model import FieldShape, HttpMethod, Operation, PrimitiveType
+from nsc.output.headers import SENSITIVE_HEADERS
+
+_REDACTED_AUTH = "Token <redacted>"
+
+
+class _Frozen(BaseModel):
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+
+class ResolvedRequest(_Frozen):
+    method: HttpMethod
+    url: str
+    headers: dict[str, str] = Field(default_factory=dict)
+    query: dict[str, Any] = Field(default_factory=dict)
+    body: dict[str, Any] | list[dict[str, Any]] | None = None
+    path_vars: dict[str, str] = Field(default_factory=dict)
+    operation_id: str
+    record_indices: list[int] = Field(default_factory=list)
+
+
+def resolve(
+    raw: RawWriteInput,
+    operation: Operation,
+    *,
+    path_vars: dict[str, str],
+    base_url: str,
+    headers: dict[str, str] | None = None,
+    mode: RoutingMode = RoutingMode.SINGLE,
+) -> list[ResolvedRequest]:
+    """Build wire-shape requests.
+
+    Mode drives the body shape:
+      SINGLE / LOOP -> one ResolvedRequest per record, body=dict, record_indices=[i].
+      BULK          -> one ResolvedRequest, body=list[dict], record_indices=[0..N).
+
+    SINGLE and LOOP differ only in caller intent (single record vs. multiple
+    records that the user opted out of bulk for). The wire shape is identical
+    per request.
+    """
+    base = base_url.rstrip("/")
+    url = base + operation.path.format(**path_vars)
+    visible_headers = _redact(headers or {})
+    records = raw.records or [{}]
+
+    if mode is RoutingMode.BULK:
+        body_list: list[dict[str, Any]] = []
+        for record in records:
+            shaped = _shape_body(record, operation)
+            assert shaped is not None, "bulk path requires non-None body shape"
+            body_list.append(shaped)
+        return [
+            ResolvedRequest(
+                method=operation.http_method,
+                url=url,
+                headers=visible_headers,
+                query={},
+                body=body_list,
+                path_vars=dict(path_vars),
+                operation_id=operation.operation_id,
+                record_indices=list(range(len(records))),
+            )
+        ]
+
+    out: list[ResolvedRequest] = []
+    for index, record in enumerate(records):
+        body = _shape_body(record, operation)
+        out.append(
+            ResolvedRequest(
+                method=operation.http_method,
+                url=url,
+                headers=visible_headers,
+                query={},
+                body=body,
+                path_vars=dict(path_vars),
+                operation_id=operation.operation_id,
+                record_indices=[index],
+            )
+        )
+    return out
+
+
+def _shape_body(record: dict[str, Any], operation: Operation) -> dict[str, Any] | None:
+    if operation.http_method is HttpMethod.DELETE:
+        return None
+    if operation.request_body is None:
+        return record or None
+    cast_record: dict[str, Any] = {}
+    for key, value in record.items():
+        shape = operation.request_body.fields.get(key)
+        cast_record[key] = _cast(value, shape)
+    return cast_record
+
+
+def _cast(value: Any, shape: FieldShape | None) -> Any:
+    if shape is None or value is None:
+        return value
+    match shape.primitive:
+        case PrimitiveType.INTEGER:
+            return _cast_int(value)
+        case PrimitiveType.NUMBER:
+            return _cast_number(value)
+        case PrimitiveType.BOOLEAN:
+            return _cast_bool(value)
+        case _:
+            return value
+
+
+def _cast_int(value: Any) -> Any:
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, str):
+        try:
+            return int(value)
+        except ValueError:
+            return value
+    return value
+
+
+def _cast_number(value: Any) -> Any:
+    if isinstance(value, str):
+        try:
+            return float(value)
+        except ValueError:
+            return value
+    return value
+
+
+def _cast_bool(value: Any) -> Any:
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, str):
+        lowered = value.strip().lower()
+        if lowered in _TRUTHY:
+            return True
+        if lowered in _FALSY:
+            return False
+    return value
+
+
+_OTHER_SENSITIVE_HEADERS = SENSITIVE_HEADERS - {"authorization"}
+
+
+def _redact(headers: dict[str, str]) -> dict[str, str]:
+    out: dict[str, str] = {}
+    for k, v in headers.items():
+        if k.lower() == "authorization":
+            out[k] = _REDACTED_AUTH
+        elif k.lower() in _OTHER_SENSITIVE_HEADERS:
+            out[k] = "<redacted>"
+        else:
+            out[k] = v
+    return out
+
+
+CastSource = Literal["file", "field_flag", "default", "schema_cast"]
+"""Reserved for ExplainTrace consumers. Defined here so apply.py owns the type."""
+
+
+__all__ = ["CastSource", "ResolvedRequest", "resolve"]