borescope 0.1.0.dev1__tar.gz → 1.0.1__tar.gz

borescope-1.0.1/.gitignore

@@ -0,0 +1,38 @@
+__pycache__
+/sandbox
+.idea
+*~
+.venv
+venv
+.vscode
+.coverage
+coverage.xml
+htmlcov
+/.tox
+.*.swp
+.ruff_cache
+.pytest_cache
+
+# Tokens and settings for `act` to run GHA locally
+.env
+.envrc
+.secrets
+
+# Build artifacts
+/cascade.egg-info
+/dist
+/build
+
+# Agents
+.claude/*local*
+
+# Local docs-preview tooling writes this when viewing the page
+/docs/localStorage.json
+
+# Workshop tool's per-checkout runtime lock; not source.
+/.workshop.lock
+
+# libFuzzer-generated corpus entries (SHA1-named).
+# The hand-written seeds use descriptive names and stay tracked; ignore the
+# auto-discovered ones that accumulate during local fuzz runs.
+tests/fuzz/corpus/[0-9a-f]*

{borescope-0.1.0.dev1 → borescope-1.0.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: borescope
-Version: 0.1.0.dev1
+Version: 1.0.1
 Summary: A natural shell for debugging Juju Kubernetes workload containers via Pebble
 Project-URL: Homepage, https://github.com/tonyandrewmeyer/borescope
 Project-URL: Repository, https://github.com/tonyandrewmeyer/borescope
@@ -9,7 +9,7 @@ Author-email: Tony Meyer <borescope@aotearoa.dev>
 License-Expression: Apache-2.0
 License-File: LICENSE
 Keywords: charm,debugging,juju,kubernetes,pebble,shell
-Classifier: Development Status :: 3 - Alpha
+Classifier: Development Status :: 5 - Production/Stable
 Classifier: Environment :: Console
 Classifier: Intended Audience :: Developers
 Classifier: Intended Audience :: System Administrators
@@ -24,7 +24,7 @@ Classifier: Topic :: System :: Systems Administration
 Classifier: Topic :: Utilities
 Requires-Python: >=3.11
 Requires-Dist: ops<4,>=2.0.0
-Requires-Dist: pebble-shimmer>=1.0.0b2
+Requires-Dist: pebble-shimmer>=1.0.0
 Requires-Dist: prompt-toolkit>=3.0
 Requires-Dist: pyyaml>=6.0
 Description-Content-Type: text/markdown
@@ -54,10 +54,23 @@ can't, it fails the same way.
 
 ## Install
 
-> v1 is under active development. For now, from a checkout:
+From the [snap store](https://snapcraft.io/borescope):
 
 ```console
-uv tool install .        # or: pipx install .
+sudo snap install borescope
+sudo snap connect borescope:dot-local-share-juju
+```
+
+The `dot-local-share-juju` connection is required: the snap bundles its
+own juju, but it needs access to your `~/.local/share/juju` (JUJU_DATA)
+to know which controller and model you're talking to. The `ssh-keys`
+plug auto-connects for `juju ssh`; if it doesn't, run
+`sudo snap connect borescope:ssh-keys` as well.
+
+Or from [PyPI](https://pypi.org/project/borescope/):
+
+```console
+uv tool install borescope    # or: uvx borescope, pipx install borescope
 ```
 
 ## Usage
@@ -70,6 +83,20 @@ borescope <unit> --command "services"  # one-shot, no REPL (for scripts)
 borescope <unit> --snapshot            # dump container state as JSON
 ```
 
+## Documentation
+
+Full documentation — a tutorial, how-to guides, and CLI/command reference — is
+at **<https://tonyandrewmeyer.github.io/borescope/>**.
+
+The docs are plain Markdown under [`docs/src/`](docs/src/), built into static
+HTML with a small script (no docs framework). To build them locally:
+
+```console
+uv run python docs/src/_build.py     # or: tox -e docs
+```
+
+See [`docs/README.md`](docs/README.md) for the authoring rules.
+
 ## How it works
 
 borescope is three thin, independently-testable layers:

{borescope-0.1.0.dev1 → borescope-1.0.1}/README.md

@@ -23,10 +23,23 @@ can't, it fails the same way.
 
 ## Install
 
-> v1 is under active development. For now, from a checkout:
+From the [snap store](https://snapcraft.io/borescope):
 
 ```console
-uv tool install .        # or: pipx install .
+sudo snap install borescope
+sudo snap connect borescope:dot-local-share-juju
+```
+
+The `dot-local-share-juju` connection is required: the snap bundles its
+own juju, but it needs access to your `~/.local/share/juju` (JUJU_DATA)
+to know which controller and model you're talking to. The `ssh-keys`
+plug auto-connects for `juju ssh`; if it doesn't, run
+`sudo snap connect borescope:ssh-keys` as well.
+
+Or from [PyPI](https://pypi.org/project/borescope/):
+
+```console
+uv tool install borescope    # or: uvx borescope, pipx install borescope
 ```
 
 ## Usage
@@ -39,6 +52,20 @@ borescope <unit> --command "services"  # one-shot, no REPL (for scripts)
 borescope <unit> --snapshot            # dump container state as JSON
 ```
 
+## Documentation
+
+Full documentation — a tutorial, how-to guides, and CLI/command reference — is
+at **<https://tonyandrewmeyer.github.io/borescope/>**.
+
+The docs are plain Markdown under [`docs/src/`](docs/src/), built into static
+HTML with a small script (no docs framework). To build them locally:
+
+```console
+uv run python docs/src/_build.py     # or: tox -e docs
+```
+
+See [`docs/README.md`](docs/README.md) for the authoring rules.
+
 ## How it works
 
 borescope is three thin, independently-testable layers:

{borescope-0.1.0.dev1 → borescope-1.0.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "borescope"
-version = "0.1.0.dev1"
+version = "1.0.1"
 description = "A natural shell for debugging Juju Kubernetes workload containers via Pebble"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -10,7 +10,7 @@ authors = [
 ]
 keywords = ["juju", "pebble", "kubernetes", "charm", "shell", "debugging"]
 classifiers = [
-    "Development Status :: 3 - Alpha",
+    "Development Status :: 5 - Production/Stable",
     "Environment :: Console",
     "Intended Audience :: Developers",
     "Intended Audience :: System Administrators",
@@ -26,21 +26,27 @@ classifiers = [
 ]
 dependencies = [
     "ops>=2.0.0,<4",
-    "pebble-shimmer>=1.0.0b2",
+    "pebble-shimmer>=1.0.0",
     "prompt_toolkit>=3.0",
     "PyYAML>=6.0",
 ]
 
 [dependency-groups]
 dev = [
+    "atheris>=2.3.0",
     "pytest>=7.0.0",
     "pytest-cov>=4.0.0",
     "pytest-mock>=3.10.0",
     "ruff==0.15.14",
     "ty==0.0.38",
-    "tox>=4.22.0",
     "pre-commit>=3.0.0",
 ]
+docs = [
+    "jinja2>=3.1",
+    "markdown-it-py>=3.0",
+    "mdit-py-plugins>=0.4",
+    "PyYAML>=6.0",
+]
 
 [project.scripts]
 borescope = "borescope.cli:main"
@@ -67,29 +73,110 @@ include = [
 
 # Ruff configuration
 [tool.ruff]
-line-length = 88
+line-length = 99
 target-version = "py311"
 src = ["src", "tests"]
 
+[tool.ruff.format]
+quote-style = "single"
+
 [tool.ruff.lint]
+# CPY (flake8-copyright) currently requires preview mode.
+preview = true
+explicit-preview-rules = true
 select = [
-    "E",  # pycodestyle errors
-    "W",  # pycodestyle warnings
-    "F",  # pyflakes
-    "I",  # isort
-    "B",  # flake8-bugbear
-    "C4", # flake8-comprehensions
-    "UP", # pyupgrade
-    "N",  # pep8-naming
+    # Pyflakes
+    "F",
+    # Pycodestyle
+    "E",
+    "W",
+    # isort
+    "I001",
+    # pep8-naming
+    "N",
+    # flake8-builtins
+    "A",
+    # flake8-copyright
+    "CPY001",
+    # pyupgrade
+    "UP",
+    # flake8-2020
+    "YTT",
+    # flake8-bandit
+    "S",
+    # flake8-bugbear
+    "B",
+    # flake8-simplify
+    "SIM",
+    # Ruff-specific
+    "RUF",
+    # Perflint
+    "PERF",
+    # pydocstyle
+    "D",
+    # flake8-future-annotations
+    "FA",
+    # flake8-type-checking
+    "TC",
 ]
 ignore = [
-    "E501",  # line too long, handled by formatter
-    "B008",  # do not perform function calls in argument defaults
-    "C901",  # too complex
+    # Line too long: handled by the formatter.
+    "E501",
+    # Don't force imports into TYPE_CHECKING blocks.
+    "TC001",
+    "TC002",
+    "TC003",
+    # assert is fine.
+    "S101",
+    # Magic methods and __init__ don't need docstrings.
+    "D105",
+    "D107",
+    # subprocess call: check for execution of untrusted input. False-positive heavy.
+    "S603",
 ]
 
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.lint.flake8-builtins]
+builtins-ignorelist = ["id", "min", "map", "range", "type", "input", "format", "exit", "help"]
+
+[tool.ruff.lint.flake8-copyright]
+notice-rgx = "(?i)Copyright \\d{4} Tony Meyer"
+
 [tool.ruff.lint.per-file-ignores]
-"tests/*" = ["N802", "N803", "N806"]
+# Command classes are self-documenting via their ``name``/``summary``/``usage``
+# attributes; a docstring would only restate ``summary``.
+"src/borescope/shell/commands/*.py" = [
+    "D101",
+    "D102",
+]
+# Transport is a structural ``Protocol`` mirroring ``ops.pebble.Client``; the
+# upstream API is the docstring.
+"src/borescope/transport/__init__.py" = [
+    "D102",
+]
+"tests/*" = [
+    # Docstrings aren't required in tests.
+    "D",
+    # Hard-coded "secrets" are fine in tests.
+    "S105",
+    "S106",
+]
+"tests/**/*" = [
+    "D",
+    "S105",
+    "S106",
+]
+# The docs build script intentionally keeps two things ruff would flag:
+"docs/src/_build.py" = [
+    # The entity-rewrite table maps literal "ambiguous" Unicode characters
+    # (en dash, curly quotes, ...) to HTML entities — they must stay as-is.
+    "RUF001",
+    # Jinja2 autoescape is deliberately off: the body is trusted, already-
+    # rendered HTML, and escaping it would double-encode the docs.
+    "S701",
+]
 
 [tool.ruff.lint.isort]
 known-first-party = ["borescope"]

{borescope-0.1.0.dev1 → borescope-1.0.1}/src/borescope/__init__.py

@@ -1,10 +1,13 @@
+# Copyright 2026 Tony Meyer
+# SPDX-License-Identifier: Apache-2.0
+
 """borescope - a natural shell for debugging Juju Kubernetes workload containers."""
 
 from importlib.metadata import PackageNotFoundError, version
 
 try:
-    __version__ = version("borescope")
+    __version__ = version('borescope')
 except PackageNotFoundError:  # pragma: no cover - running from an uninstalled tree
-    __version__ = "0.0.0+unknown"
+    __version__ = '0.0.0+unknown'
 
-__all__ = ["__version__"]
+__all__ = ['__version__']

{borescope-0.1.0.dev1 → borescope-1.0.1}/src/borescope/__main__.py

@@ -1,3 +1,6 @@
+# Copyright 2026 Tony Meyer
+# SPDX-License-Identifier: Apache-2.0
+
 """``python -m borescope`` entry point."""
 
 from __future__ import annotations
@@ -6,5 +9,5 @@ import sys
 
 from .cli import main
 
-if __name__ == "__main__":
+if __name__ == '__main__':
     sys.exit(main())

borescope-1.0.1/src/borescope/cli.py

@@ -0,0 +1,164 @@
+# Copyright 2026 Tony Meyer
+# SPDX-License-Identifier: Apache-2.0
+
+"""Command-line entry point for borescope.
+
+Deliberately *out* of scope for v1, and worth marking explicitly: borescope has
+no Canonical-spec verbosity ladder (`--quiet` / `--verbose` /
+`--verbosity=debug|trace`). The tool's primary output is the REPL or a single
+command's result, neither of which benefits from a five-level taxonomy, so we
+stay minimal until a concrete need shows up.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from . import __version__
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Build the top-level ``argparse`` parser."""
+    parser = argparse.ArgumentParser(
+        prog='borescope',
+        description=('A natural shell for debugging Juju Kubernetes workload containers.'),
+    )
+    parser.add_argument('unit', nargs='?', help="unit reference, for example 'myapp/0'")
+    parser.add_argument('--container', help='workload container name (default: first declared)')
+    # Canonical CLI guidance is "don't offer both short and long" for the same
+    # flag — `-m/--model` deliberately diverges to match `juju`'s own convention
+    # (`juju ssh -m <model> …`), which is what users muscle-memory their way to
+    # when reaching for borescope.
+    parser.add_argument('-m', '--model', help='Juju model (default: current)')
+    parser.add_argument(
+        '--command',
+        help='run a single command and exit (no REPL)',
+    )
+    parser.add_argument(
+        '--snapshot',
+        action='store_true',
+        help='dump container state as JSON and exit',
+    )
+    parser.add_argument(
+        '--socket',
+        help='talk directly to a Pebble unix socket (skip juju)',
+    )
+    parser.add_argument(
+        '--here',
+        action='store_true',
+        help=(
+            "run inside the charm container: auto-detect a workload's mounted "
+            'Pebble socket (use --container to pick when there are several)'
+        ),
+    )
+    parser.add_argument('--juju', default='juju', help='juju binary to invoke (default: juju)')
+    parser.add_argument(
+        '--via',
+        choices=('ssh', 'exec'),
+        default='ssh',
+        help=(
+            "Juju relay for Mode B: 'ssh' (default, streaming) or 'exec' "
+            '(request/response — for sites where ssh is disabled)'
+        ),
+    )
+    parser.add_argument('--version', action='version', version=f'borescope {__version__}')
+    return parser
+
+
+def _build_target(args: argparse.Namespace):
+    from .discovery import Target, resolve_local_target, resolve_target, validate_container_name
+
+    if args.container is not None:
+        validate_container_name(args.container)
+    if args.here:
+        return resolve_local_target(container=args.container)
+    if args.socket:
+        unit = args.unit or 'local'
+        app = unit.split('/')[0]
+        return Target(
+            unit=unit,
+            app=app,
+            container=args.container,
+            model=args.model,
+            juju_binary=args.juju,
+            socket_path=args.socket,
+        )
+    return resolve_target(
+        args.unit,
+        container=args.container,
+        model=args.model,
+        juju_binary=args.juju,
+        via=args.via,
+    )
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Run borescope from the command line and return the exit code."""
+    # Accept Canonical-style `help` / `version` subcommands as aliases for the
+    # Python-default `--help` / `--version`. Awkward to support both, but it
+    # means the tool matches the standard *and* what `argparse` users expect.
+    cli_args = sys.argv[1:] if argv is None else argv
+    if cli_args[:1] == ['help']:
+        build_parser().print_help()
+        return 0
+    if cli_args[:1] == ['version']:
+        print(f'borescope {__version__}')
+        return 0
+
+    args = build_parser().parse_args(argv)
+    if not args.unit and not args.socket and not args.here:
+        print(
+            "borescope: A unit reference is required (for example 'borescope myapp/0'), "
+            'or use --here when running inside a charm container.',
+            file=sys.stderr,
+        )
+        return 2
+
+    # Heavy imports happen only past argument parsing, keeping --help/--version fast.
+    from .errors import BorescopeError
+    from .shell import ShellContext
+    from .transport import open_transport
+
+    try:
+        target = _build_target(args)
+        transport = open_transport(
+            unit=target.unit,
+            container=target.container,
+            model=target.model,
+            juju_binary=target.juju_binary,
+            socket_path=target.socket_path,
+            via=target.via,
+        )
+        if args.snapshot:
+            from .snapshot import snapshot_json
+
+            print(snapshot_json(transport, target))
+            return 0
+
+        from .discovery import sanity_check
+
+        sanity_check(transport, target)
+    except BorescopeError as exc:
+        print(f'borescope: {exc}', file=sys.stderr)
+        return 1
+
+    from .shell import Shell
+
+    shell = Shell(ShellContext(transport=transport, target=target))
+
+    if args.command is not None:
+        return shell.execute_and_emit(args.command)
+
+    if not sys.stdin.isatty():
+        code = 0
+        for line in sys.stdin:
+            if line.strip():
+                code = shell.execute_and_emit(line.rstrip('\n'))
+        return code
+
+    return shell.loop()
+
+
+if __name__ == '__main__':  # pragma: no cover
+    sys.exit(main())