docker-orb 1.0.0__tar.gz

docker_orb-1.0.0/.gitignore

@@ -0,0 +1,9 @@
+*.egg-info/
+*.pyc
+.DS_Store
+.fuse_hidden*
+.git-broken-lockissue/
+.pytest_cache/
+.venv/
+__pycache__/
+dist/

docker_orb-1.0.0/CLAUDE.md

@@ -0,0 +1,134 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Commands
+
+```bash
+# Install in editable mode (sets up both entry points)
+# NOTE: dev deps are a PEP 735 dependency group, not an extra — `.[dev]`
+# silently installs nothing (pip just warns "does not provide the extra").
+pip install -e . --group dev
+# or with uv:
+uv pip install -e . --group dev
+
+# Run the TUI app (dev mode with live reload via textual-dev)
+hatch run dev
+# or directly:
+textual run --dev src/docker_orb/__main__.py
+
+# Run the app normally
+docker-orb
+
+# Run all tests
+pytest
+# or via hatch:
+hatch run test
+
+# Run a single test file
+pytest tests/test_config.py
+
+# Run a single test class or method
+pytest tests/test_config.py::TestParseStringInput::test_comma_separated
+```
+
+### Test infrastructure (local Compose stack)
+
+```bash
+cd infra
+make up                 # one-shot: build + start 8 fake log-generating services
+make status              # docker compose ps
+make logs                 # tail all services
+make logs SERVICE=worker  # tail one service
+make restart              # recreate all services (picks up code changes)
+make teardown             # stop and remove everything
+```
+
+The stack runs under the fixed Compose project name `logviewer-demo` (8
+services: `api-gateway`, `auth-service`, `user-service`,
+`notification-service`, `worker`, `database`, `cache`, `scheduler` — the
+busier five run 2 containers each). It's deliberately not named
+`docker-orb-*` — docker-orb doesn't prepend its own name to anything, and
+container names here (`logviewer-demo-api-gateway-1`, etc.) are just this
+demo's own Compose project name, same as any other stack. It also stops
+itself automatically after 4 hours by default (a `reaper` service in
+`docker-compose.yml`, socket-mounted, `docker stop`s the project's
+containers on a timer — see `infra/README.md#auto-shutdown-after-4-hours`
+for overriding/disabling it) so it's never left running unattended
+indefinitely. Point docker-orb at it with:
+
+```bash
+docker-orb -n logviewer-demo --all-containers --health
+docker-orb-inject -n logviewer-demo -d worker -m "ERROR: test error"
+```
+
+`docker-orb-inject` writes directly to a container's PID 1 stdout via
+`docker exec ... sh -c "echo ... > /proc/1/fd/1"`, so injected messages show
+up in the live stream exactly like real application logs — handy for
+exercising filters/highlights/monitors without waiting for a real error.
+
+This is a straight Compose port of kube-orb's k3d test cluster: same
+Python log-generator scripts under `infra/services/`, unchanged (none of
+them depended on anything Kubernetes-specific), just wired up with
+`infra/docker-compose.yml` instead of k3d + k8s manifests. It also still
+works fine, of course, to point docker-orb at any other real
+`docker-compose.yml` project you have running.
+
+## Architecture
+
+docker-orb is a **Textual TUI** app with two entry points:
+
+- `docker-orb` (`src/docker_orb/cli.py`) — main CLI. If enough args are provided, launches the viewer directly; otherwise falls through to the wizard.
+- `docker-orb-inject` (`src/docker_orb/inject.py`) — test utility that writes messages to a container's stdout via `docker exec`, causing them to appear in the live log stream.
+
+### Data flow
+
+```
+CLI args / Wizard
+       ↓
+  SessionConfig          (models.py)
+       ↓
+  ViewerApp              (viewer/app.py)
+       ↓ asyncio workers (one per container)
+  compose.stream_logs()  (compose.py)  — async subprocess, `docker logs -f`
+       ↓ LogLine objects
+  _ingest() → filter → _deliver_to_panels()
+       ↓
+  MainStreamPanel / MonitorPanel / HealthPanel / SearchPanel
+```
+
+### Key modules
+
+| Module | Purpose |
+|---|---|
+| `models.py` | All shared dataclasses: `SessionConfig`, `LogLine`, `Service`, `Container`, `ContainerStatus`, `HealthConfig` |
+| `compose.py` | All Docker/Compose interaction via subprocess (`docker`, `docker compose`). No Python Docker SDK. `stream_logs()` runs `docker logs -f --timestamps <container>` per container (one coroutine per container, same fan-out pattern as kube-orb's per-pod streaming) rather than a single multiplexed `docker compose logs -f`; `dump_logs()` is one-shot. `stream_logs()` normalizes `since` to `"1s"` when unset/zero (`_normalize_since()`) so a live session only collects new lines instead of replaying history. **Untested against a live Docker daemon in the environment this was written in** — verify service/container discovery (`docker compose ps --format json` shape) and the `--since` normalization against a real Compose project before relying on it. |
+| `config.py` | Persists session configs to `~/.config/docker-orb/projects/<project>/<name>.yaml` and global saved strings to `~/.config/docker-orb/strings.yaml`. Also owns pattern compilation: plain strings are `re.escape`d; `/regex/`-wrapped strings compile as real regex. |
+| `colors.py` | Assigns a distinct ANSI/CSS color to each container name. |
+| `jsonlog.py` | Detects single-JSON-object log lines and extracts level/message/timestamp (checking a few conventional key names) for the optional readable-formatting toggle. Detection runs regardless of the toggle, since the Enter-for-detail view needs it too. |
+| `viewer/app.py` | `ViewerApp` — the main Textual `App`. Owns the log buffer, pause state, pattern state, and container/service lifecycle. |
+| `viewer/panels/` | Four panels: `MainStreamPanel` (primary log display), `SearchPanel` (live search), `MonitorPanel` (passive pattern accumulation), `HealthPanel` (restart/health alerts). |
+| `viewer/widgets.py` | Shared widgets: `StringEditModal` (F/H/M editing), `SaveDialog`, `ContainerSelectorModal`, `PaneSizeModal`, `JsonDetailModal`, `MonitorContextModal`. |
+| `wizard/` | Three-tab Textual wizard (`SinglePageWizard` screen) — Targets → Strings → Options — produces a `SessionConfig`. |
+
+### Pattern matching
+
+Filters, highlights, and monitors all share the same matching syntax (in `config.py`):
+- Plain strings are matched as literals (dots and special chars are escaped).
+- `/pattern/` strings are compiled as regex.
+- Comma-separated input is parsed by `parse_string_input()`.
+
+### Package layout
+
+`src/docker_orb/` is the canonical source package.
+
+### Provenance
+
+docker-orb started as a sibling port of [kube-orb](https://github.com/adlidev/kube-orb):
+the Textual viewer/wizard/panel layer (~3900 lines) was carried over largely
+unchanged since it only ever depended on generic `LogLine`/container-name
+concepts, not Kubernetes specifics. The Kubernetes-coupled layer — `kubectl.py`, the `Deployment`/`Pod` models, and
+the k3d test infra — was replaced with `compose.py`, `Service`/`Container`
+models, and an `infra/docker-compose.yml` port of the same test-log
+services. The two projects are maintained independently going forward;
+changes to one don't automatically apply to the other.

docker_orb-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Adli Waziri
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

docker_orb-1.0.0/PKG-INFO

@@ -0,0 +1,192 @@
+Metadata-Version: 2.4
+Name: docker-orb
+Version: 1.0.0
+Summary: Interactive terminal UI for streaming and filtering Docker Compose container logs across multiple services
+Project-URL: Homepage, https://github.com/adlidev/docker-orb
+Project-URL: Repository, https://github.com/adlidev/docker-orb
+Project-URL: Documentation, https://github.com/adlidev/docker-orb/blob/main/docs/USER_GUIDE.md
+Project-URL: Issues, https://github.com/adlidev/docker-orb/issues
+Author-email: Adli Waziri <boulderadli@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2026 Adli Waziri
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: compose,devops,docker,docker-compose,logs,observability,sre,textual,tui
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: System :: Logging
+Classifier: Topic :: System :: Monitoring
+Classifier: Topic :: System :: Systems Administration
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Requires-Dist: click>=8.1
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: textual>=0.61.0
+Description-Content-Type: text/markdown
+
+# docker-orb
+
+Watching logs across a multi-container Compose stack usually means juggling
+multiple `docker compose logs` windows and grepping after the fact, or
+writing complex regex just to add a couple of filters. docker-orb streams
+logs from every container in your selected services into one merged,
+colorized view — and lets you filter, highlight, and search *while it's
+streaming*.
+
+Built with [Textual](https://textual.textualize.io/), docker-orb is a full
+terminal UI: an interactive setup wizard walks you through picking a
+project, services, and filter patterns — no flags required — or skip
+straight to the viewer with CLI arguments if you prefer. Save named session
+configs to reload your exact setup later; passively collect rare events in
+a monitor panel without losing your scroll position; get alerted when
+containers restart or go unhealthy; and add or remove services from the
+live stream without restarting.
+
+![docker-orb viewer](docs/screenshot-viewer.png)
+
+## Features
+
+- **Multi-container live tail** — stream logs from any number of
+  containers/services at once, each with a distinct color.
+- **Filters** — hide lines matching a pattern, live-editable mid-session.
+- **Highlights** — emphasize lines matching a pattern without hiding anything else.
+- **Monitors** — passively collect matching lines into a separate panel so you
+  can watch for rare events (e.g. `job failed`) without losing your scroll
+  position in the main stream.
+- **Live search** — search the whole buffered session, jump to a result, and
+  keep streaming.
+- **Container health panel** — flags containers that aren't `Running` or have
+  crossed a restart threshold; restart a container or recreate a service from
+  inside the app.
+- **Dump mode** — fetch existing logs once (with `--tail`/`--since`) and exit,
+  for scripting or one-off inspection, instead of a live stream.
+- **Saved configs** — save a named combination of project, services, and
+  patterns, and reload it later by name.
+- **JSON log formatting** — auto-detects structured JSON log lines and shows
+  `time  LEVEL  message  key=value ...` instead of a raw JSON blob, with a
+  toggle back to raw and a detail view (Enter on a clicked line) for the full
+  pretty-printed object.
+- **Collapse repeated lines** — journalctl-style: consecutive identical lines
+  from the same container fold into a single "last line repeated N times"
+  marker, toggleable, so a crash-looping container doesn't flood the stream.
+
+## Installation
+
+Requires Python 3.10+, and `docker` with the Compose v2 plugin on your
+`PATH` (i.e. `docker compose` works). docker-orb shells out to your existing
+`docker` CLI and inherits its context/auth — no separate credentials or
+Docker SDK involved.
+
+```bash
+# Recommended — pipx keeps CLI tools in isolated environments. Not on PyPI
+# yet, so install straight from GitHub:
+pipx install git+https://github.com/adlidev/docker-orb
+
+# Or with plain pip, inside your own venv:
+git clone https://github.com/adlidev/docker-orb.git
+cd docker-orb
+pip install -e .
+```
+
+This installs two commands: `docker-orb` and `docker-orb-inject` (a small
+test utility for injecting fake log lines into a running container — see
+the [User Guide](docs/USER_GUIDE.md#docker-orb-inject)).
+
+**For development / contributing:**
+
+```bash
+git clone https://github.com/adlidev/docker-orb.git
+cd docker-orb
+pip install -e . --group dev
+```
+
+## Quick start
+
+```bash
+# No arguments — launches the interactive setup wizard
+docker-orb
+
+# Skip the wizard: watch two services live
+docker-orb -n myapp -p api -p worker
+
+# Watch every service in a project
+docker-orb -n myapp --all-containers
+
+# One-shot dump instead of a live stream
+docker-orb -n myapp --dump --tail 500
+
+# Pre-filter/highlight from the command line
+docker-orb -n myapp -p worker -f DEBUG -H ERROR --health
+```
+
+`-n/--project` takes the Compose project name (what `docker compose -p`
+expects — usually the directory name your `docker-compose.yml` lives in,
+unless overridden by a top-level `name:` key or `COMPOSE_PROJECT_NAME`). If
+omitted, docker-orb resolves it the same way `docker compose` does for the
+current directory.
+
+Once you're in the viewer, press `F` / `H` / `M` to edit filters, highlights,
+or monitors live, `/` to search, `P` to add/remove streamed services, and
+`Space` to pause. See the [User Guide](docs/USER_GUIDE.md) for the full
+keybinding reference and pattern syntax.
+
+## Development
+
+```bash
+pip install -e . --group dev
+pytest                    # run the test suite
+textual run --dev src/docker_orb/__main__.py   # live-reload dev mode
+```
+
+A local Compose stack with 8 fake log-generating services is included for
+manual testing:
+
+```bash
+cd infra
+make up
+docker-orb -n logviewer-demo --all-containers --health
+```
+
+See [`infra/README.md`](infra/README.md) for the service list and good
+filter/monitor test patterns, and [`CLAUDE.md`](CLAUDE.md) for architecture
+notes.
+
+## Relationship to kube-orb
+
+docker-orb is a sibling project to [kube-orb](https://github.com/adlidev/kube-orb),
+Adli's Kubernetes-flavored log viewer. They share a UI architecture (Textual
+viewer, wizard, filters/highlights/monitors, JSON formatting) but each talks
+to its own backend directly — docker-orb shells out to `docker`/`docker
+compose`, kube-orb shells out to `kubectl` — and they're maintained as
+independent tools rather than one project trying to do both.
+
+## License
+
+[MIT License](LICENSE)

docker_orb-1.0.0/README.md

@@ -0,0 +1,139 @@
+# docker-orb
+
+Watching logs across a multi-container Compose stack usually means juggling
+multiple `docker compose logs` windows and grepping after the fact, or
+writing complex regex just to add a couple of filters. docker-orb streams
+logs from every container in your selected services into one merged,
+colorized view — and lets you filter, highlight, and search *while it's
+streaming*.
+
+Built with [Textual](https://textual.textualize.io/), docker-orb is a full
+terminal UI: an interactive setup wizard walks you through picking a
+project, services, and filter patterns — no flags required — or skip
+straight to the viewer with CLI arguments if you prefer. Save named session
+configs to reload your exact setup later; passively collect rare events in
+a monitor panel without losing your scroll position; get alerted when
+containers restart or go unhealthy; and add or remove services from the
+live stream without restarting.
+
+![docker-orb viewer](docs/screenshot-viewer.png)
+
+## Features
+
+- **Multi-container live tail** — stream logs from any number of
+  containers/services at once, each with a distinct color.
+- **Filters** — hide lines matching a pattern, live-editable mid-session.
+- **Highlights** — emphasize lines matching a pattern without hiding anything else.
+- **Monitors** — passively collect matching lines into a separate panel so you
+  can watch for rare events (e.g. `job failed`) without losing your scroll
+  position in the main stream.
+- **Live search** — search the whole buffered session, jump to a result, and
+  keep streaming.
+- **Container health panel** — flags containers that aren't `Running` or have
+  crossed a restart threshold; restart a container or recreate a service from
+  inside the app.
+- **Dump mode** — fetch existing logs once (with `--tail`/`--since`) and exit,
+  for scripting or one-off inspection, instead of a live stream.
+- **Saved configs** — save a named combination of project, services, and
+  patterns, and reload it later by name.
+- **JSON log formatting** — auto-detects structured JSON log lines and shows
+  `time  LEVEL  message  key=value ...` instead of a raw JSON blob, with a
+  toggle back to raw and a detail view (Enter on a clicked line) for the full
+  pretty-printed object.
+- **Collapse repeated lines** — journalctl-style: consecutive identical lines
+  from the same container fold into a single "last line repeated N times"
+  marker, toggleable, so a crash-looping container doesn't flood the stream.
+
+## Installation
+
+Requires Python 3.10+, and `docker` with the Compose v2 plugin on your
+`PATH` (i.e. `docker compose` works). docker-orb shells out to your existing
+`docker` CLI and inherits its context/auth — no separate credentials or
+Docker SDK involved.
+
+```bash
+# Recommended — pipx keeps CLI tools in isolated environments. Not on PyPI
+# yet, so install straight from GitHub:
+pipx install git+https://github.com/adlidev/docker-orb
+
+# Or with plain pip, inside your own venv:
+git clone https://github.com/adlidev/docker-orb.git
+cd docker-orb
+pip install -e .
+```
+
+This installs two commands: `docker-orb` and `docker-orb-inject` (a small
+test utility for injecting fake log lines into a running container — see
+the [User Guide](docs/USER_GUIDE.md#docker-orb-inject)).
+
+**For development / contributing:**
+
+```bash
+git clone https://github.com/adlidev/docker-orb.git
+cd docker-orb
+pip install -e . --group dev
+```
+
+## Quick start
+
+```bash
+# No arguments — launches the interactive setup wizard
+docker-orb
+
+# Skip the wizard: watch two services live
+docker-orb -n myapp -p api -p worker
+
+# Watch every service in a project
+docker-orb -n myapp --all-containers
+
+# One-shot dump instead of a live stream
+docker-orb -n myapp --dump --tail 500
+
+# Pre-filter/highlight from the command line
+docker-orb -n myapp -p worker -f DEBUG -H ERROR --health
+```
+
+`-n/--project` takes the Compose project name (what `docker compose -p`
+expects — usually the directory name your `docker-compose.yml` lives in,
+unless overridden by a top-level `name:` key or `COMPOSE_PROJECT_NAME`). If
+omitted, docker-orb resolves it the same way `docker compose` does for the
+current directory.
+
+Once you're in the viewer, press `F` / `H` / `M` to edit filters, highlights,
+or monitors live, `/` to search, `P` to add/remove streamed services, and
+`Space` to pause. See the [User Guide](docs/USER_GUIDE.md) for the full
+keybinding reference and pattern syntax.
+
+## Development
+
+```bash
+pip install -e . --group dev
+pytest                    # run the test suite
+textual run --dev src/docker_orb/__main__.py   # live-reload dev mode
+```
+
+A local Compose stack with 8 fake log-generating services is included for
+manual testing:
+
+```bash
+cd infra
+make up
+docker-orb -n logviewer-demo --all-containers --health
+```
+
+See [`infra/README.md`](infra/README.md) for the service list and good
+filter/monitor test patterns, and [`CLAUDE.md`](CLAUDE.md) for architecture
+notes.
+
+## Relationship to kube-orb
+
+docker-orb is a sibling project to [kube-orb](https://github.com/adlidev/kube-orb),
+Adli's Kubernetes-flavored log viewer. They share a UI architecture (Textual
+viewer, wizard, filters/highlights/monitors, JSON formatting) but each talks
+to its own backend directly — docker-orb shells out to `docker`/`docker
+compose`, kube-orb shells out to `kubectl` — and they're maintained as
+independent tools rather than one project trying to do both.
+
+## License
+
+[MIT License](LICENSE)