opskit 0.1.0__py3-none-any.whl

opskit/__init__.py

@@ -0,0 +1,16 @@
+"""opskit — cross-platform diagnostics for engineers, one toolkit for every OS.
+
+This is the package root. Public, category-scoped APIs (e.g. ``opskit.dns``) are added
+per feature; see the project constitution for the API-first design rules.
+"""
+
+from __future__ import annotations
+
+import logging
+
+__version__ = "0.1.0"  # x-release-please-version
+
+__all__ = ["__version__"]
+
+# Good-citizen library logging: silent unless the host app configures a handler.
+logging.getLogger("opskit").addHandler(logging.NullHandler())

opskit/__main__.py

@@ -0,0 +1,8 @@
+"""Enable ``python -m opskit``."""
+
+from __future__ import annotations
+
+from opskit.cli import main
+
+if __name__ == "__main__":  # pragma: no cover
+    main()

opskit/cli.py

@@ -0,0 +1,49 @@
+"""Root command-line interface for opskit.
+
+Per the constitution the CLI is a thin presentation layer: it parses arguments and
+renders results, holding no business logic. Categories (e.g. ``dns``) register
+themselves here as Typer sub-apps.
+"""
+
+from __future__ import annotations
+
+import typer
+
+from opskit import __version__
+from opskit.dns.cli import app as dns_app
+from opskit.tls.cli import app as tls_app
+
+app = typer.Typer(
+    name="opskit",
+    help="Cross-platform diagnostics for engineers — one toolkit, every OS.",
+    no_args_is_help=True,
+    add_completion=True,
+)
+app.add_typer(dns_app, name="dns")
+app.add_typer(tls_app, name="tls")
+
+
+def _version_callback(value: bool) -> None:
+    """Print the version and exit when ``--version`` was requested."""
+    if value:
+        typer.echo(f"opskit {__version__}")
+        raise typer.Exit
+
+
+@app.callback()
+def root(
+    version: bool = typer.Option(
+        False,
+        "--version",
+        "-V",
+        help="Show the opskit version and exit.",
+        callback=_version_callback,
+        is_eager=True,
+    ),
+) -> None:
+    """Top-level options shared by every opskit command."""
+
+
+def main() -> None:  # pragma: no cover
+    """Console-script entry point (``opskit``)."""
+    app()

opskit/core/__init__.py

@@ -0,0 +1,8 @@
+"""Shared cross-cutting concerns for opskit commands.
+
+Holds the pieces every diagnostic category reuses: the exit-code map, the base exception
+hierarchy, the versioned result envelope, and output rendering. Category packages (e.g.
+``opskit.dns``) build on these; nothing here is category-specific.
+"""
+
+from __future__ import annotations

opskit/core/cliutils.py

@@ -0,0 +1,171 @@
+"""Category-agnostic CLI plumbing shared by every command group.
+
+Batch-input reading, outcome collection with per-target failure tolerance, aggregate
+exit-code derivation, JSON-envelope emission, and the ``--watch`` loop. Imports only
+``opskit.core`` — no category models (constitution Art. VII).
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from collections.abc import Callable, Sequence
+from datetime import datetime
+from pathlib import Path
+from typing import Any, TypeVar
+
+import typer
+
+from opskit.core.errors import OpskitError, UsageError
+from opskit.core.exit_codes import ExitCode, exit_code_for
+from opskit.core.output import make_console
+from opskit.core.result import to_json
+
+_T = TypeVar("_T")
+
+# (exit code, change-detection signature) returned by a command's single execution.
+ActionResult = tuple[ExitCode, str]
+
+
+def read_input_file(path: Path) -> list[str]:
+    """Read targets from a file, one per line, ignoring blanks and ``#`` comments."""
+    try:
+        raw = path.read_text(encoding="utf-8")
+    except OSError as exc:
+        raise UsageError(f"cannot read input file: {path}") from exc
+    targets: list[str] = []
+    for line in raw.splitlines():
+        stripped = line.strip()
+        if stripped and not stripped.startswith("#"):
+            targets.append(stripped)
+    return targets
+
+
+def collect_targets(positional: str | None, input_file: Path | None) -> list[str]:
+    """Combine a positional target with any from ``--input-file`` (positional first)."""
+    targets: list[str] = []
+    if positional:
+        targets.append(positional)
+    if input_file is not None:
+        targets.extend(read_input_file(input_file))
+    if not targets:
+        raise UsageError("provide a target argument or --input-file")
+    return targets
+
+
+def collect_outcomes(
+    targets: Sequence[str], run_one: Callable[[str], _T]
+) -> list[tuple[str, _T | None, OpskitError | None]]:
+    """Run ``run_one`` for each target, capturing its result or the raised OpskitError."""
+    outcomes: list[tuple[str, _T | None, OpskitError | None]] = []
+    for target in targets:
+        try:
+            outcomes.append((target, run_one(target), None))
+        except OpskitError as exc:
+            outcomes.append((target, None, exc))
+    return outcomes
+
+
+def echo_failures(
+    outcomes: Sequence[tuple[str, object, OpskitError | None]],
+) -> None:
+    """Print each failed target's error to stderr (human mode / no-success bail)."""
+    for target, _, error in outcomes:
+        if error is not None:
+            typer.echo(f"error: {target}: {error.message}", err=True)
+
+
+def aggregate_exit(codes: Sequence[ExitCode]) -> ExitCode:
+    """Batch rule (Art. IX): 0 if all succeed; the class code if uniform; else PARTIAL."""
+    if all(code is ExitCode.OK for code in codes):
+        return ExitCode.OK
+    distinct = {code for code in codes if code is not ExitCode.OK}
+    if len(distinct) == 1 and all(code is not ExitCode.OK for code in codes):
+        return next(iter(distinct))
+    return ExitCode.PARTIAL
+
+
+def aggregate_outcome_exit(
+    outcomes: Sequence[tuple[str, object, OpskitError | None]],
+) -> ExitCode:
+    """:func:`aggregate_exit` over (target, result, error) outcome tuples."""
+    return aggregate_exit(
+        [
+            ExitCode.OK if error is None else exit_code_for(error)
+            for _, _, error in outcomes
+        ]
+    )
+
+
+def emit_envelopes(envelopes: Sequence[dict[str, Any]], *, jsonl: bool) -> None:
+    """Emit JSON envelopes: NDJSON (one per line), a bare object, or an array."""
+    if jsonl:
+        for envelope in envelopes:
+            typer.echo(to_json(envelope, indent=None))
+    elif len(envelopes) == 1:
+        typer.echo(to_json(envelopes[0]))
+    else:
+        typer.echo(json.dumps(envelopes, indent=2))
+
+
+def parse_interval(text: str) -> float:
+    """Parse a --watch interval like '5', '5s', '250ms', or '2m' into seconds."""
+    value = text.strip().lower()
+    try:
+        if value.endswith("ms"):
+            seconds = float(value[:-2]) / 1000.0
+        elif value.endswith("s"):
+            seconds = float(value[:-1])
+        elif value.endswith("m"):
+            seconds = float(value[:-1]) * 60.0
+        else:
+            seconds = float(value)
+    except ValueError as exc:
+        raise UsageError(f"invalid --watch interval: {text}") from exc
+    if seconds <= 0:
+        raise UsageError("--watch interval must be positive")
+    return seconds
+
+
+def watch(
+    action: Callable[[], ActionResult],
+    *,
+    interval: float,
+    no_color: bool,
+) -> ExitCode:
+    """Re-run ``action`` every ``interval`` seconds until interrupted, flagging changes."""
+    console = make_console(no_color=no_color)
+    previous: str | None = None
+    code = ExitCode.OK
+    try:
+        while True:
+            code, signature = action()
+            if previous is None:
+                status = "initial"
+            elif signature != previous:
+                status = "changed"
+            else:
+                status = "no change"
+            stamp = datetime.now().strftime("%H:%M:%S")
+            console.print(
+                f"[dim]-- {stamp} - {status} - next in {interval:g}s (Ctrl-C to stop) --[/dim]"
+            )
+            previous = signature
+            time.sleep(interval)  # looked up at call time so tests can patch it
+    except KeyboardInterrupt:
+        return code
+
+
+def run_or_watch(
+    action: Callable[[], ActionResult], *, watch_spec: str | None, no_color: bool
+) -> None:
+    """Run ``action`` once, or repeatedly under --watch; then exit with its code."""
+    if watch_spec is not None:
+        try:
+            interval = parse_interval(watch_spec)
+        except UsageError as error:
+            typer.echo(f"error: {error.message}", err=True)
+            raise typer.Exit(int(ExitCode.USAGE)) from error
+        raise typer.Exit(int(watch(action, interval=interval, no_color=no_color)))
+    code, _ = action()
+    raise typer.Exit(int(code))

opskit/core/errors.py

@@ -0,0 +1,37 @@
+"""Base exception hierarchy for opskit.
+
+The library layer raises these; only the CLI catches them and maps them to exit codes
+(see :mod:`opskit.core.exit_codes`). No raw third-party exception should reach the user.
+"""
+
+from __future__ import annotations
+
+from opskit.core.exit_codes import ExitCode
+
+
+class OpskitError(Exception):
+    """Base class for all opskit errors.
+
+    Each subclass declares the process ``exit_code`` it maps to, so the CLI's exit-code
+    resolution stays category-agnostic (see :func:`opskit.core.exit_codes.exit_code_for`).
+
+    Attributes:
+        message: Human-readable summary of what went wrong.
+        hint: Optional actionable next step for the user (e.g. "try a different --server").
+    """
+
+    code: str = "error"
+    exit_code: ExitCode = ExitCode.ERROR  # generic failure unless a subclass narrows it
+
+    def __init__(self, message: str, *, hint: str | None = None) -> None:
+        """Initialize the error with a message and an optional remediation hint."""
+        super().__init__(message)
+        self.message = message
+        self.hint = hint
+
+
+class UsageError(OpskitError):
+    """Invalid user input (bad name/IP, unknown option). Raised before any network I/O."""
+
+    code = "usage_error"
+    exit_code = ExitCode.USAGE

opskit/core/exit_codes.py

@@ -0,0 +1,39 @@
+"""Structured process exit codes and the exception-to-code mapping.
+
+Exit codes are part of the public, SemVer-governed contract (see contracts/cli.md) so scripts
+can branch on the outcome class without parsing text.
+"""
+
+from __future__ import annotations
+
+from enum import IntEnum
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from opskit.core.errors import OpskitError
+
+
+class ExitCode(IntEnum):
+    """Documented exit codes returned by the CLI."""
+
+    OK = 0
+    ERROR = 1
+    USAGE = 2
+    NXDOMAIN = 3
+    SERVFAIL = 4
+    REFUSED = 5
+    TIMEOUT = 6
+    PARTIAL = 7
+    CONNECT_FAILED = 8
+    HANDSHAKE_FAILED = 9
+    CERT_INVALID = 10
+    CERT_EXPIRING = 11
+
+
+def exit_code_for(error: OpskitError) -> ExitCode:
+    """Return the :class:`ExitCode` an error declares.
+
+    Each error type owns its ``exit_code`` (set on the class), so this mapping stays
+    category-agnostic — adding a new category (net/tls/ad) never touches ``core``.
+    """
+    return error.exit_code

opskit/core/output.py

@@ -0,0 +1,19 @@
+"""Shared, category-agnostic console setup.
+
+``rich.Console`` auto-detects a TTY (plain when piped) and honors ``NO_COLOR``; ``no_color``
+forces plain output regardless. Category-specific rendering lives with its category (e.g.
+:mod:`opskit.dns.output`) so ``core`` stays free of category models.
+"""
+
+from __future__ import annotations
+
+from rich.console import Console
+
+
+def make_console(*, no_color: bool = False) -> Console:
+    """Return a console configured for the current output context.
+
+    ``no_color`` forces plain output when set; when unset, ``Console`` is left to its default
+    (which honors the ``NO_COLOR`` environment variable and auto-detects a non-TTY).
+    """
+    return Console(no_color=True if no_color else None, highlight=False)

opskit/core/result.py

@@ -0,0 +1,41 @@
+"""Versioned JSON output envelope shared by every command.
+
+The envelope shape is the public ``--json`` contract (contracts/json-envelope.md); its schema
+changes are governed by SemVer. The current ``schema_version`` is ``"1"``.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from opskit.core.errors import OpskitError
+
+SCHEMA_VERSION = "1"
+
+
+def build_envelope(
+    *,
+    command: str,
+    query: dict[str, Any],
+    result: dict[str, Any] | None,
+    error: OpskitError | None,
+    elapsed_ms: float,
+) -> dict[str, Any]:
+    """Assemble the versioned envelope for a single command invocation."""
+    error_obj: dict[str, Any] | None = None
+    if error is not None:
+        error_obj = {"code": error.code, "message": error.message, "hint": error.hint}
+    return {
+        "schema_version": SCHEMA_VERSION,
+        "command": command,
+        "query": query,
+        "result": result,
+        "error": error_obj,
+        "elapsed_ms": round(elapsed_ms, 3),
+    }
+
+
+def to_json(envelope: dict[str, Any], *, indent: int | None = 2) -> str:
+    """Serialize an envelope to a JSON string (single object)."""
+    return json.dumps(envelope, indent=indent)

opskit/dns/README.md

@@ -0,0 +1,205 @@
+# `opskit dns` — DNS diagnostics
+
+Read-only DNS troubleshooting that behaves **identically on Windows, macOS, and Linux** — a single
+replacement for `nslookup` / `dig` / `Resolve-DnsName`. Available both as CLI commands and as an
+importable Python API.
+
+> Part of [**opskit**](../../../README.md). See the root README for install and project-wide docs.
+
+---
+
+## Contents
+
+- [Commands](#commands)
+  - [`opskit dns lookup`](#opskit-dns-lookup)
+  - [`opskit dns reverse`](#opskit-dns-reverse)
+- [Modes](#modes) — `--all`, `--diff`, `--trace`, `--watch`
+- [Bulk lookups](#bulk-lookups) — `--input-file`
+- [Output & exit codes](#output--exit-codes)
+- [Use as a Python library](#use-as-a-python-library)
+
+---
+
+## Quick start
+
+```bash
+opskit dns lookup example.com                    # A records, pretty table
+opskit dns lookup example.com -t MX -t TXT       # specific record types
+opskit dns lookup example.com --all              # every common record type at once
+opskit dns reverse 8.8.8.8                       # PTR (IP → hostname)
+opskit dns lookup example.com --json             # machine-readable envelope
+```
+
+Help is grouped into panels (**Query**, **Modes**, **Query controls**, **Output**) with worked
+examples in the footer — think `man`, but organized and copy-pasteable:
+
+```bash
+opskit dns --help             # the DNS command group
+opskit dns lookup --help      # a specific command (grouped options + examples)
+```
+
+---
+
+## Commands
+
+### `opskit dns lookup`
+
+Forward DNS lookup for one or more hostnames.
+
+```bash
+opskit dns lookup TARGET [OPTIONS]
+```
+
+| Option | Description | Default |
+|---|---|---|
+| `TARGET` | Hostname to resolve (optional if `--input-file` is used) | — |
+| `-t, --type` | Record type(s): `A AAAA MX TXT CNAME NS SOA SRV CAA` (repeatable) | `A` |
+| `--all` | Query **all** common record types at once | off |
+| `--diff` | Query every `--server` and compare/diff answers | off |
+| `--trace` | Show the iterative resolution path (root → authoritative) | off |
+| `-s, --server` | Resolver(s) to query (repeatable); defaults to the system resolver | system |
+| `--transport` | `udp` \| `tcp` \| `auto` (UDP then TCP on truncation) | `auto` |
+| `--timeout` | Per-attempt timeout, seconds | `5.0` |
+| `--retries` | Retry count on timeout | `2` |
+| `--port` | Resolver port | `53` |
+| `-i, --input-file` | File of targets, one per line (`#` comments allowed) | — |
+| `--json` | Emit the versioned JSON envelope | off |
+| `--jsonl` | Emit one JSON envelope per line (NDJSON) | off |
+| `--watch` | Re-run every interval (e.g. `5s`, `2m`, `250ms`) until Ctrl-C | off |
+| `--no-color` | Disable colored output | off |
+
+### `opskit dns reverse`
+
+Reverse (PTR) lookup for one or more IP addresses. Accepts IPv4 and IPv6.
+
+```bash
+opskit dns reverse IP [OPTIONS]
+```
+
+Supports the same query controls, output, `--trace`, `--watch`, and `--input-file` options as
+`lookup` (record-type options don't apply).
+
+---
+
+## Modes
+
+### `--all` — one-stop lookup
+
+DNS `ANY` queries are deprecated (RFC 8482), so `--all` fans out across every common record type
+and aggregates the results. It's **resilient**: if a resolver refuses one type, that type is
+skipped rather than failing the whole lookup — you still get everything that exists.
+
+```bash
+opskit dns lookup cloudflare.com --all
+```
+
+### `--diff` — multi-resolver comparison
+
+Ask the same question of several resolvers and see **who returns what** — the differing resolver
+is highlighted. Great for propagation lag, split-horizon/GeoDNS, or spotting a broken/poisoned
+resolver.
+
+```bash
+opskit dns lookup example.com --diff -s 1.1.1.1 -s 8.8.8.8 -s 9.9.9.9
+```
+
+Exit code is `0` when all resolvers agree and `7` when they differ (TTLs are ignored — only real
+answer differences count), so you can alert on divergence in scripts.
+
+### `--trace` — the resolution path
+
+An iterative walk from the root servers, following each delegation down to the authoritative
+answer — like `dig +trace`, one row per hop.
+
+```bash
+opskit dns lookup www.wikipedia.org --trace
+opskit dns reverse 8.8.8.8 --trace
+```
+
+### `--watch` — live re-run
+
+Re-run on an interval until Ctrl-C, flagging when the **answer changes** (TTL changes are
+ignored). Ideal for watching propagation or failover.
+
+```bash
+opskit dns lookup example.com --watch 30s
+opskit dns lookup example.com --all --watch 10s     # modes compose
+```
+
+---
+
+## Bulk lookups
+
+Feed many targets from a file with `-i/--input-file` (one per line; blank lines and `#` comments
+are skipped). Combine with a positional target if you like.
+
+```bash
+opskit dns lookup -i hosts.txt                 # per-target tables
+opskit dns lookup -i hosts.txt --jsonl | jq .  # NDJSON, one object per line
+opskit dns reverse -i ips.txt --json           # JSON array
+```
+
+For a batch, the exit code is `0` only if **every** target succeeds; otherwise `7` (partial).
+
+---
+
+## Output & exit codes
+
+- **Human** (default): colorized tables, auto-plain when piped; honors `NO_COLOR` and `--no-color`.
+- **`--json`**: a stable, versioned envelope (`schema_version`, `command`, `query`, `result`,
+  `error`, `elapsed_ms`); an array for batches.
+- **`--jsonl`**: NDJSON — one envelope per line, ideal for `jq` / streaming.
+
+```json
+{
+  "schema_version": "1",
+  "command": "dns.lookup",
+  "query": { "target": "example.com", "record_types": ["A"], "servers": [], "transport": "auto" },
+  "result": { "outcome": "ok", "resolver": "1.1.1.1", "records": [ { "type": "A", "value": "93.184.216.34", "ttl": 300 } ] },
+  "error": null,
+  "elapsed_ms": 12.3
+}
+```
+
+Exit codes are documented and scriptable:
+
+| Code | Meaning |
+|---|---|
+| `0` | success |
+| `1` | generic error (uncategorized failure) |
+| `2` | usage error (bad input; before any network) |
+| `3` | NXDOMAIN (name does not exist) |
+| `4` | SERVFAIL |
+| `5` | REFUSED |
+| `6` | TIMEOUT / no response |
+| `7` | PARTIAL (batch had a failure, or resolvers disagreed) |
+
+---
+
+## Use as a Python library
+
+The DNS API is **API-first** — every capability is importable, returns typed results, and raises
+typed exceptions (it never prints or calls `sys.exit`). The package ships `py.typed`.
+
+```python
+from opskit.dns import lookup, reverse, lookup_all, compare, trace
+from opskit.dns import NxDomain, DnsTimeout
+
+result = lookup("example.com", ["A", "MX"], server="1.1.1.1", timeout=3)
+if result.ok:
+    for record in result:            # results are iterable
+        print(record.type.value, record.value, record.ttl)
+
+everything = lookup_all("example.com")             # all record types
+ptr = reverse("8.8.8.8")                            # PTR
+cmp = compare("example.com", ["1.1.1.1", "8.8.8.8"])   # multi-resolver
+print("consistent:", cmp.consistent)
+hops = trace("www.wikipedia.org")                   # resolution path
+
+try:
+    lookup("does-not-exist.invalid")
+except NxDomain as exc:
+    print(exc.message, "—", exc.hint)
+```
+
+Results serialize cleanly: `result.to_dict()` / the envelope shape match the CLI's `--json`.

opskit/dns/__init__.py

@@ -0,0 +1,61 @@
+"""DNS diagnostics — importable API and CLI sub-app.
+
+Public surface (SemVer-governed): :func:`lookup`, the typed models, and the DNS exception
+hierarchy. Failures raise; nothing here prints or exits the process.
+"""
+
+from __future__ import annotations
+
+from opskit.dns.api import (
+    compare,
+    lookup,
+    lookup_all,
+    reverse,
+    reverse_trace,
+    trace,
+)
+from opskit.dns.errors import (
+    DnsError,
+    DnsRefused,
+    DnssecError,
+    DnsTimeout,
+    NxDomain,
+    ServerFailure,
+)
+from opskit.dns.models import (
+    DnsQuery,
+    DnsRecord,
+    LookupResult,
+    Outcome,
+    RecordType,
+    Resolver,
+    ResolverAnswer,
+    ResolverComparison,
+    TraceStep,
+    Transport,
+)
+
+__all__ = [
+    "DnsError",
+    "DnsQuery",
+    "DnsRecord",
+    "DnsRefused",
+    "DnsTimeout",
+    "DnssecError",
+    "LookupResult",
+    "NxDomain",
+    "Outcome",
+    "RecordType",
+    "Resolver",
+    "ResolverAnswer",
+    "ResolverComparison",
+    "ServerFailure",
+    "TraceStep",
+    "Transport",
+    "compare",
+    "lookup",
+    "lookup_all",
+    "reverse",
+    "reverse_trace",
+    "trace",
+]