borescope 1.0.0__tar.gz → 1.0.2__tar.gz

{borescope-1.0.0 → borescope-1.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: borescope
-Version: 1.0.0
+Version: 1.0.2
 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
@@ -54,10 +54,26 @@ 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
+```
+
+A few things to know about the snap:
+
+- It bundles its own juju (currently `juju/4/stable`), so it works
+  even without juju installed on the host.
+- It reads your `~/.local/share/juju` (JUJU_DATA) read-only via the
+  auto-connecting `juju-client-observe` interface, then copies it into
+  a writable per-snap directory at startup. **Run `juju login` /
+  `juju switch` outside borescope** — changes made inside a borescope
+  session don't propagate back to the host JUJU_DATA.
+
+Or from [PyPI](https://pypi.org/project/borescope/):
+
+```console
+uv tool install borescope    # or: uvx borescope, pipx install borescope
 ```
 
 ## Usage

{borescope-1.0.0 → borescope-1.0.2}/README.md

@@ -23,10 +23,26 @@ 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
+```
+
+A few things to know about the snap:
+
+- It bundles its own juju (currently `juju/4/stable`), so it works
+  even without juju installed on the host.
+- It reads your `~/.local/share/juju` (JUJU_DATA) read-only via the
+  auto-connecting `juju-client-observe` interface, then copies it into
+  a writable per-snap directory at startup. **Run `juju login` /
+  `juju switch` outside borescope** — changes made inside a borescope
+  session don't propagate back to the host JUJU_DATA.
+
+Or from [PyPI](https://pypi.org/project/borescope/):
+
+```console
+uv tool install borescope    # or: uvx borescope, pipx install borescope
 ```
 
 ## Usage

{borescope-1.0.0 → borescope-1.0.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "borescope"
-version = "1.0.0"
+version = "1.0.2"
 description = "A natural shell for debugging Juju Kubernetes workload containers via Pebble"
 readme = "README.md"
 requires-python = ">=3.11"

{borescope-1.0.0 → borescope-1.0.2}/src/borescope/cli.py

@@ -107,6 +107,14 @@ def main(argv: list[str] | None = None) -> int:
         return 0
 
     args = build_parser().parse_args(argv)
+
+    # When running as a snap, stage the host's JUJU_DATA into the snap's
+    # writable home so the bundled juju can refresh macaroons/cookies. No-op
+    # outside the snap. See borescope.snap for the trade-offs.
+    from .snap import stage_juju_data
+
+    stage_juju_data()
+
     if not args.unit and not args.socket and not args.here:
         print(
             "borescope: A unit reference is required (for example 'borescope myapp/0'), "

borescope-1.0.2/src/borescope/snap.py

@@ -0,0 +1,62 @@
+# Copyright 2026 Tony Meyer
+# SPDX-License-Identifier: Apache-2.0
+
+"""Snap-environment helpers.
+
+Under strict confinement, the snap can only *read* the host's Juju
+configuration directory via the ``juju-client-observe`` interface — it
+cannot write to it. Borescope's bundled juju, however, refreshes
+macaroons and cookies on the fly and will fail the moment it tries to
+update ``cookies.yaml`` or ``accounts.yaml``.
+
+Personal-files would grant write access but pushes the snap into manual
+store review on every revision until an auto-connect declaration is
+granted. To stay on auto-connecting interfaces, we instead stage a copy
+of the host's ``~/.local/share/juju`` into the snap's writable
+``$SNAP_USER_COMMON/juju`` on every invocation, point ``JUJU_DATA`` at
+the copy, and let the bundled juju write freely to it.
+
+Trade-offs of staging:
+
+* The copy is one-way (host → snap). Logins/model-switches you do
+  *inside* a borescope session never write back to the host, so they
+  vanish at the end of the session. Do ``juju login`` / ``juju
+  switch`` *outside* borescope.
+* The copy happens at every borescope invocation, so host-side changes
+  are picked up on the next run. For typical use (debug a workload,
+  exit, move on) this is invisible.
+
+This module is a no-op outside the snap, so unit tests and PyPI
+installs are unaffected.
+"""
+
+from __future__ import annotations
+
+import os
+import pwd
+import shutil
+
+
+def stage_juju_data() -> None:
+    """If running inside the borescope snap, copy host JUJU_DATA into writable storage.
+
+    The snap's ``apps.borescope.environment`` block sets
+    ``JUJU_DATA=$SNAP_USER_COMMON/juju``; this function populates that
+    directory by copying ``~/.local/share/juju`` (read-only via
+    ``juju-client-observe``) into it on every invocation. The bundled
+    juju then reads and writes the copy freely.
+
+    No-op outside the snap, and no-op if the host has no JUJU_DATA
+    (the bundled juju will surface "no controllers registered" itself).
+    """
+    if os.environ.get('SNAP_NAME') != 'borescope':
+        return
+    snap_user_common = os.environ.get('SNAP_USER_COMMON')
+    if not snap_user_common:
+        return
+    real_home = pwd.getpwuid(os.getuid()).pw_dir
+    source = os.path.join(real_home, '.local', 'share', 'juju')
+    if not os.path.isdir(source):
+        return
+    target = os.path.join(snap_user_common, 'juju')
+    shutil.copytree(source, target, dirs_exist_ok=True, symlinks=True)

borescope-1.0.2/tests/test_snap.py

@@ -0,0 +1,90 @@
+# Copyright 2026 Tony Meyer
+# SPDX-License-Identifier: Apache-2.0
+
+"""Tests for the snap startup hook that stages JUJU_DATA."""
+
+from __future__ import annotations
+
+import pwd
+
+import pytest
+
+from borescope.snap import stage_juju_data
+
+
+@pytest.fixture
+def in_snap(monkeypatch, tmp_path):
+    """Pretend we're running inside the borescope snap."""
+    real_home = tmp_path / 'home'
+    snap_common = tmp_path / 'snap-common'
+    source = real_home / '.local' / 'share' / 'juju'
+    target = snap_common / 'juju'
+
+    source.mkdir(parents=True)
+    snap_common.mkdir()
+    (source / 'controllers.yaml').write_text('controllers:\n  k8s: {}\n')
+    (source / 'cookies.yaml').write_text('cookies: []\n')
+
+    monkeypatch.setenv('SNAP_NAME', 'borescope')
+    monkeypatch.setenv('SNAP_USER_COMMON', str(snap_common))
+    monkeypatch.setattr(
+        pwd,
+        'getpwuid',
+        lambda _uid: pwd.struct_passwd(('u', 'x', 0, 0, '', str(real_home), '/bin/sh')),
+    )
+    return source, target
+
+
+def test_noop_outside_snap(monkeypatch, tmp_path):
+    monkeypatch.delenv('SNAP_NAME', raising=False)
+    target = tmp_path / 'juju'
+    stage_juju_data()
+    assert not target.exists()
+
+
+def test_noop_when_snap_name_is_something_else(monkeypatch):
+    monkeypatch.setenv('SNAP_NAME', 'jhack')
+    stage_juju_data()  # must not raise
+
+
+def test_stages_when_host_juju_data_exists(in_snap):
+    source, target = in_snap
+    stage_juju_data()
+    assert (target / 'controllers.yaml').read_text() == (source / 'controllers.yaml').read_text()
+    assert (target / 'cookies.yaml').read_text() == (source / 'cookies.yaml').read_text()
+
+
+def test_noop_when_host_juju_data_missing(monkeypatch, tmp_path):
+    real_home = tmp_path / 'home'
+    snap_common = tmp_path / 'snap-common'
+    real_home.mkdir()
+    snap_common.mkdir()
+    monkeypatch.setenv('SNAP_NAME', 'borescope')
+    monkeypatch.setenv('SNAP_USER_COMMON', str(snap_common))
+    monkeypatch.setattr(
+        pwd,
+        'getpwuid',
+        lambda _uid: pwd.struct_passwd(('u', 'x', 0, 0, '', str(real_home), '/bin/sh')),
+    )
+    stage_juju_data()
+    assert not (snap_common / 'juju').exists()
+
+
+def test_subsequent_runs_pick_up_host_changes(in_snap):
+    source, target = in_snap
+    stage_juju_data()
+    assert (target / 'controllers.yaml').read_text().startswith('controllers:\n  k8s')
+    (source / 'controllers.yaml').write_text('controllers:\n  prod: {}\n')
+    stage_juju_data()
+    assert 'prod' in (target / 'controllers.yaml').read_text()
+
+
+def test_inside_snap_writes_bundled_juju_cookies_to_copy(in_snap):
+    """Writes by the bundled juju into the snap copy must not leak back to host."""
+    source, target = in_snap
+    stage_juju_data()
+    (target / 'cookies.yaml').write_text('cookies:\n  - inside-snap\n')
+    # Re-run: host source is unchanged, target gets overwritten with host data.
+    stage_juju_data()
+    assert (source / 'cookies.yaml').read_text() == 'cookies: []\n'
+    assert (target / 'cookies.yaml').read_text() == 'cookies: []\n'