traceact 0.2.1__tar.gz → 0.3.0__tar.gz

{traceact-0.2.1/traceact.egg-info → traceact-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: traceact
-Version: 0.2.1
+Version: 0.3.0
 Summary: X-ray vision for your code. Lightweight action-level tracing for Python.
 Author: Mohammed Shehu
 License-Expression: MIT
@@ -127,6 +127,14 @@ The source modal (click the source name in the header) lets you:
 - **Drag and drop** a `.jsonl` file — saved as a static snapshot in `~/.traceact/imports/`
 - **Type a path** — collapsible fallback for pasting an absolute path
 
+### Health checks
+
+```bash
+traceact doctor [SOURCE]
+```
+
+Checks Python version, that `~/.traceact` is writable, whether a viewer is already running, and (if `SOURCE` is given) that the file or folder parses as valid trace data. Useful for ruling out setup problems before debugging your own code. The same checks are also available from the viewer itself — Settings > **Run diagnostics**. See [USAGE.md](USAGE.md#viewing-traces) for full output and exit-code details.
+
 ## Concepts
 
 | Concept | Meaning |
@@ -174,6 +182,13 @@ document.getElementById("btn-viewer").addEventListener("click", async () => {
 
 Python 3.9+. No runtime dependencies.
 
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
 ## Full reference
 
 See [USAGE.md](USAGE.md) for complete API documentation: all decorator and context manager parameters, helper methods (`trace.db`, `trace.http`, `trace.file`, `trace.model`), input capture, parent/child traces, sinks, budget configuration, the trace record schema, test isolation, and the full viewer server API.

{traceact-0.2.1 → traceact-0.3.0}/README.md

@@ -97,6 +97,14 @@ The source modal (click the source name in the header) lets you:
 - **Drag and drop** a `.jsonl` file — saved as a static snapshot in `~/.traceact/imports/`
 - **Type a path** — collapsible fallback for pasting an absolute path
 
+### Health checks
+
+```bash
+traceact doctor [SOURCE]
+```
+
+Checks Python version, that `~/.traceact` is writable, whether a viewer is already running, and (if `SOURCE` is given) that the file or folder parses as valid trace data. Useful for ruling out setup problems before debugging your own code. The same checks are also available from the viewer itself — Settings > **Run diagnostics**. See [USAGE.md](USAGE.md#viewing-traces) for full output and exit-code details.
+
 ## Concepts
 
 | Concept | Meaning |
@@ -144,6 +152,13 @@ document.getElementById("btn-viewer").addEventListener("click", async () => {
 
 Python 3.9+. No runtime dependencies.
 
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
 ## Full reference
 
 See [USAGE.md](USAGE.md) for complete API documentation: all decorator and context manager parameters, helper methods (`trace.db`, `trace.http`, `trace.file`, `trace.model`), input capture, parent/child traces, sinks, budget configuration, the trace record schema, test isolation, and the full viewer server API.

{traceact-0.2.1 → traceact-0.3.0}/USAGE.md

@@ -12,20 +12,27 @@ traceact/
   config.py       — TraceConfig, configure(), reset_config()
   budget.py       — TraceBudget, TraceBudget.production() preset
   context.py      — ContextVar for active trace, SKIP sentinel
-  sinks.py        — JsonlSink (thread-safe), ConsoleSink, AsyncSink (not yet public)
+  redaction.py    — SENSITIVE_PATTERNS baseline + REDACTION_PRESETS registry
+  sinks.py        — JsonlSink (thread-safe, rotation via max_bytes), ConsoleSink,
+                    AsyncSink (not yet public)
   helpers.py      — TraceHelpersMixin (trace.db, trace.http, trace.file, trace.model)
   ids.py          — ID generation (trc_, evt_, stp_, corr_ prefixes)
 
   viewer/
-    cli.py        — `traceact view` / `traceact show` CLI entry point; --new flag
+    cli.py        — `traceact view` / `traceact show` / `traceact doctor` CLI entry point
     server.py     — stdlib ThreadingHTTPServer; SPA + REST + SSE
-    reader.py     — SourceReader: JSONL snapshot + live byte-offset tail
+    reader.py     — SourceReader: JSONL snapshot + live byte-offset tail,
+                    with inode-based delete+recreate detection
+    doctor.py     — run_checks(): shared health-check logic behind both
+                    `traceact doctor` and GET /api/doctor (Settings > Run diagnostics)
     instance.py   — single-instance coordination (state file + HTTP probe);
                     launch_or_connect() for embedding in app backends
     static/
       index.html  — single-page app shell
       styles.css  — design system (dark theme, CSS custom properties)
       app.js      — all frontend logic (no framework, no build step)
+
+tests/            — pytest suite (pip install -e ".[dev]" && pytest)
 ```
 
 ## Contents
@@ -41,14 +48,16 @@ traceact/
 9. [Touches](#touches)
 10. [Errors](#errors)
 11. [Parent and child traces](#parent-and-child-traces)
-12. [Input capture](#input-capture)
-13. [Sinks](#sinks)
-14. [Budget configuration](#budget-configuration)
-15. [TraceConfig fields](#traceconfig-fields)
-16. [Test isolation](#test-isolation)
-17. [Trace record schema](#trace-record-schema)
-18. [Viewing traces](#viewing-traces)
-19. [Integrating the viewer into your app](#integrating-the-viewer-into-your-app)
+12. [Framework recipes](#framework-recipes)
+13. [Background jobs and correlation IDs](#background-jobs-and-correlation-ids)
+14. [Input capture](#input-capture)
+15. [Sinks](#sinks)
+16. [Budget configuration](#budget-configuration)
+17. [TraceConfig fields](#traceconfig-fields)
+18. [Test isolation](#test-isolation)
+19. [Trace record schema](#trace-record-schema)
+20. [Viewing traces](#viewing-traces)
+21. [Integrating the viewer into your app](#integrating-the-viewer-into-your-app)
 
 ---
 
@@ -127,7 +136,7 @@ from traceact import traced_action, TraceConfig, TraceBudget
     operation="insert",             # creates an initial event if provided with target
     target="notes",                 # the resource (table, endpoint, file, model)
     database="sqlite",              # for kind="db" traces
-    capture_inputs=False,           # False | True | ["field1", "field2"]
+    capture_inputs=True,             # None (defer to package config) | False | True | ["field1", "field2"]
     meta={"release": "v1.2"},       # arbitrary key-value data
     config=TraceConfig(strict=True),# override package config for this trace only
     budget=TraceBudget(max_events=50), # override budget for this trace only
@@ -393,9 +402,153 @@ When `sample_rate < 1.0` and a trace is sampled out, a skip sentinel is pushed o
 
 ---
 
+## Framework recipes
+
+`@traced_action` and `ActionTrace` work on any callable — there's no framework integration to install. The only decision per framework is *where* to call `configure()` and *which* functions to wrap. These are patterns, not new API surface.
+
+### FastAPI
+
+Call `configure()` once, at import time or in a startup event, then wrap your route handlers or (more usefully) the service functions they call:
+
+```python
+# app/tracing.py — imported once, before routes are registered
+from traceact import configure, TraceConfig, JsonlSink
+
+configure(
+    config=TraceConfig(sink_mode="blocking"),
+    sinks=[JsonlSink("data/traces/traces.jsonl")],
+)
+```
+
+```python
+# app/routers/notes.py
+from fastapi import APIRouter
+from traceact import traced_action
+
+router = APIRouter()
+
+@traced_action(action="note.create", kind="app", actor="user")
+async def _create_note(title: str, body: str) -> dict:
+    ...
+    return {"note_id": "note_123"}
+
+@router.post("/notes")
+async def create_note(payload: dict):
+    return await _create_note(payload["title"], payload["body"])
+```
+
+Wrapping the inner service function (not the route handler directly) keeps the trace's `action` name stable even if you later rename the route or move it behind a different path. `correlation_id` is a good place to pass FastAPI's request ID if you have request-ID middleware:
+
+```python
+@traced_action(action="note.create", kind="app", correlation_id=request.state.request_id)
+```
+
+### Django
+
+Django's request/response cycle is a natural boundary for `correlation_id`, and views or service functions are the natural place for `@traced_action`:
+
+```python
+# myapp/apps.py — configure once when the app is ready
+from django.apps import AppConfig
+from traceact import configure, TraceConfig, JsonlSink
+
+class MyAppConfig(AppConfig):
+    name = "myapp"
+
+    def ready(self):
+        configure(
+            config=TraceConfig(sink_mode="blocking"),
+            sinks=[JsonlSink("data/traces/traces.jsonl")],
+        )
+```
+
+```python
+# myapp/services.py
+from traceact import traced_action
+
+@traced_action(action="order.process", kind="app", actor="user")
+def process_order(order_id: int) -> None:
+    ...
+```
+
+```python
+# myapp/views.py
+from django.http import JsonResponse
+from myapp.services import process_order
+
+def process_order_view(request, order_id):
+    process_order(order_id)
+    return JsonResponse({"status": "ok"})
+```
+
+If you want every request to carry a correlation ID automatically (so all traces from one request share it), set it from middleware using Python's `contextvars` and read it in the view before calling the traced function — TraceAct doesn't read Django's request object itself, so the ID has to be passed explicitly into `correlation_id=`.
+
+---
+
+## Background jobs and correlation IDs
+
+`correlation_id` links traces that belong to the same logical unit of work — a request, a job, a batch run — even when they happen across different function calls or processes. TraceAct doesn't generate or propagate it automatically across a queue boundary; the queue's message *is* the propagation mechanism, so you pass the ID through it like any other job argument.
+
+**Enqueuing** — generate (or reuse) a correlation ID before the job goes on the queue:
+
+```python
+import uuid
+from myqueue import enqueue
+
+def start_export(user_id: int):
+    correlation_id = f"corr_{uuid.uuid4().hex[:12]}"
+    enqueue("export_report", user_id=user_id, correlation_id=correlation_id)
+    return correlation_id  # e.g. return to the client so it can poll status
+```
+
+**Celery:**
+
+```python
+from celery import shared_task
+from traceact import traced_action
+
+@shared_task(name="export_report")
+@traced_action(action="report.export", kind="job", actor="worker")
+def export_report(user_id: int, correlation_id: str = None):
+    # correlation_id is picked up automatically by @traced_action's
+    # correlation_id kwarg only if passed through explicitly:
+    ...
+```
+
+`@traced_action`'s `correlation_id` parameter isn't populated from task kwargs automatically — pass it explicitly so the decorator sees it:
+
+```python
+@shared_task(name="export_report")
+def export_report(user_id: int, correlation_id: str = None):
+    _export_report(user_id, correlation_id=correlation_id)
+
+@traced_action(action="report.export", kind="job", actor="worker")
+def _export_report(user_id: int, correlation_id: str = None):
+    ...
+```
+
+**RQ:**
+
+```python
+from rq import Queue
+from traceact import traced_action
+
+@traced_action(action="report.export", kind="job", actor="worker")
+def export_report(user_id: int, correlation_id: str = None):
+    ...
+
+queue.enqueue(export_report, user_id=42, correlation_id="corr_abc123")
+```
+
+**Why this can't be automatic:** `contextvars.ContextVar` (which powers automatic parent/child linking within one process) does not cross a queue boundary — the worker that picks up the job runs in a different process with a fresh, empty context. The correlation ID has to travel as ordinary job data, the same way you'd pass any other argument the job needs.
+
+Traces from the enqueue side and the worker side won't share a `parent_trace_id` (they're different processes, so there's no shared ContextVar to link them), but they will share `correlation_id`. The viewer's search box doesn't currently filter by `correlation_id` (it matches on action, kind, status, and touched targets); to pull together one job's traces today, use "Copy JSON" on a trace to get its `correlation_id`, then `grep` or `jq` the JSONL file for it: `jq 'select(.correlation_id == "corr_abc123")' data/traces/traces.jsonl`.
+
+---
+
 ## Input capture
 
-By default, `@traced_action` doesn't capture function arguments.
+By default, `@traced_action` doesn't capture function arguments — `capture_inputs` defaults to `None`, which means "defer to the package-level setting from `configure()`, or no capture if that isn't set either."
 
 **Capture selected fields (recommended):**
 
@@ -409,7 +562,7 @@ def create_note(title, body, user_id):
     ...
 ```
 
-**Capture all arguments:**
+**Capture all arguments (per decorator):**
 
 ```python
 @traced_action(action="note.create", kind="app", capture_inputs=True)
@@ -417,7 +570,19 @@ def create_note(title, body, user_id):
     ...
 ```
 
-**Global kill switch** (overrides all decorator-level settings):
+**Capture all arguments (package-wide default):**
+
+```python
+configure(config=TraceConfig(capture_inputs=True))
+
+@traced_action(action="note.create", kind="app")  # no capture_inputs needed here
+def create_note(title, body, user_id):
+    ...
+```
+
+`capture_inputs=` on the decorator is shorthand for `config=TraceConfig(capture_inputs=...)` — both resolve through the same package-default → `configure()` → decorator-override chain, so a package-level default set via `configure()` is honoured by any decorator that doesn't explicitly override it.
+
+**Global kill switch** (cannot be re-enabled by any decorator, not even one that explicitly passes `capture_inputs=True`):
 
 ```python
 configure(config=TraceConfig(capture_inputs=False))
@@ -427,12 +592,59 @@ configure(config=TraceConfig(capture_inputs=False))
 **What TraceAct does when capture is enabled:**
 1. Maps positional args to parameter names using `inspect.signature()`.
 2. Skips `self` and `cls`.
-3. Redacts arguments whose names match sensitive patterns: `password`, `passwd`, `secret`, `token`, `api_key`, `apikey`, `private_key`, `privatekey`, `access_key`, `accesskey`, `auth`, `credential`, `credentials`, `credit_card`, `card_number`, `cvv`, `ssn`.
-4. Truncates values larger than `max_payload_bytes`.
-5. Converts non-serialisable types to `[TypeName]`.
+3. Redacts arguments whose names match sensitive patterns: `password`, `passwd`, `pwd`, `secret`, `token`, `api_key`, `apikey`, `private_key`, `privatekey`, `access_key`, `accesskey`, `auth`, `credential`, `credentials`, `credit_card`, `card_number`, `cvv`, `ssn`.
+4. Recurses into nested dicts and lists-of-dicts, so a sensitive field buried inside a request body or config object is also redacted — not just top-level keys (see below).
+5. Truncates values larger than `max_payload_bytes`.
+6. Converts non-serialisable types to `[TypeName]`.
 
 **`trace.input()` always works** regardless of the `capture_inputs` setting.
 
+### Redaction presets
+
+The pattern list above is always on. Layer additional field-name patterns on top of it with `redaction_presets`:
+
+```python
+from traceact import configure, TraceConfig, REDACTION_PRESETS
+
+print(sorted(REDACTION_PRESETS))
+# ['api_keys', 'env_vars', 'filesystem_paths', 'http']
+
+configure(config=TraceConfig(redaction_presets=["filesystem_paths", "env_vars"]))
+```
+
+| Preset | Extra patterns |
+|---|---|
+| `"api_keys"` | `jwt`, `bearer`, `signing_key`, `encryption_key`, `hmac_key`, `master_key` |
+| `"http"` | `cookie`, `set_cookie`, `session_id`, `csrf_token`, `x_forwarded_for`, `remote_addr`, `client_ip` |
+| `"filesystem_paths"` | `path`, `filepath`, `file_path`, `dir`, `directory`, `workdir`, `cwd`, `home_dir`, `homedir` |
+| `"env_vars"` | `env`, `environ`, `environment`, `envvar`, `env_var`, `dotenv` |
+
+An unknown preset name raises `ValueError` immediately at `TraceConfig(...)` construction, not later at trace time.
+
+Also settable per-decorator, same as any other `TraceConfig` field — but note that a decorator-level `redaction_presets` **replaces** the package-level list rather than adding to it, exactly like `capture_inputs` does:
+
+```python
+@traced_action(action="report.export", kind="app",
+               config=TraceConfig(redaction_presets=["api_keys"]))
+def export_report(...):
+    ...
+```
+
+**These are field-name patterns, not content scanning.** A value is redacted because of what its *key* is called, not what it contains. `trace.input({"path": "/Users/mo/secret"})` is redacted by the `filesystem_paths` preset; `trace.input({"location": "/Users/mo/secret"})` is not, because `"location"` doesn't match any active pattern. This mirrors the baseline mechanism exactly (same substring, case-insensitive matching) — it's simple and has no false-positive risk from scanning arbitrary string content, at the cost of missing secrets stored under an unexpected field name.
+
+**Nested redaction example:**
+
+```python
+trace.input({
+    "request": {
+        "headers": {"authorization": "Bearer abc123"},
+        "body": {"user_id": 42},
+    },
+})
+# stored as:
+# {"request": {"headers": {"authorization": "[redacted]"}, "body": {"user_id": 42}}}
+```
+
 ---
 
 ## Sinks
@@ -448,6 +660,14 @@ JsonlSink("data/traces/traces.jsonl")
 JsonlSink("/absolute/path/to/traces.jsonl")
 ```
 
+**Rotation (`max_bytes`):** by default the file grows without limit. Pass `max_bytes` to cap the active file's size — once the next write would exceed it, the current file is renamed to `<path>.<UTC timestamp>` and a fresh file starts at `path`:
+
+```python
+JsonlSink("data/traces/traces.jsonl", max_bytes=50_000_000)  # cap ~50 MB per file
+```
+
+Rotation renames rather than deletes, so history isn't lost — it's just no longer at `path`. Point the viewer at the containing **folder** rather than the single file to see the active file plus every rotated segment merged together: `traceact view data/traces/`. TraceAct doesn't currently delete old rotated segments on a schedule; clean them up yourself (e.g. a cron job or a retention script) if disk usage matters.
+
 ### ConsoleSink
 
 Prints traces to stdout.
@@ -592,6 +812,13 @@ def test_create_note():
         reset_config()
 ```
 
+**TraceAct's own test suite** lives in `tests/` at the repo root and follows this exact pattern — a `_clean_config` autouse fixture in `tests/conftest.py` calls `reset_config()` before and after every test. Run it with:
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
 ---
 
 ## Trace record schema
@@ -704,6 +931,34 @@ The viewer reads any line that parses as JSON and looks like a trace; malformed
 
 You can also run it as a module: `python -m traceact.viewer.cli view SOURCE`.
 
+### Health checks (`traceact doctor`)
+
+```bash
+traceact doctor [SOURCE]
+```
+
+Runs a handful of local checks and prints a pass/fail report — useful when tracing "isn't working" and you want to rule out setup problems before debugging your own code:
+
+- Python version meets the 3.9 minimum
+- the `~/.traceact` state directory exists and is writable (single-instance coordination and drag-drop imports depend on this)
+- whether a viewer is currently running (informational only — `doctor` doesn't require one)
+- if `SOURCE` is given: that the path exists and its lines parse as valid trace records
+
+```
+$ traceact doctor data/traces/traces.jsonl
+traceact doctor
+
+  ✓  Python 3.11 (OK, 3.9+ required)
+  ·  traceact 0.3.0
+  ✓  State directory (/Users/you/.traceact) is writable
+  ·  No viewer currently running (not required).
+  ✓  data/traces/traces.jsonl: 42/42 line(s) look like valid traces across 1 file(s)
+
+All checks passed.
+```
+
+Exits `0` if every check that can fail passed, `1` otherwise. A missing running viewer is never treated as a failure.
+
 ### Single-instance behaviour
 
 Running `traceact view` a second time — even for a different source — reuses a viewer that is already running rather than spawning a second server. The new source is added to the running viewer and a browser tab is opened on it. This avoids accumulating background processes across repeated launches during a dev session.
@@ -734,10 +989,14 @@ The Terminal window stays open so Ctrl+C stops the viewer cleanly. To pass a sou
 
 ### What the viewer shows
 
-- **Trace log** — a live, newest-first table of traces (time, action, status, duration, and touch/error/budget counts). A search box filters by action, kind, status, or touched target. The row count is capped (25 / 50 / 100 / 250, default 100) and paired with live tailing, so the newest traces are always in view.
-- **Trace inspector** — selecting a trace shows its own ID, its parent and root trace IDs (when it is a child trace), kind, duration, and touch/error counts. "Copy JSON" copies the full record.
+- **Trace log** — a live, newest-first table of traces (time, action, status, duration, and touch/error/budget counts). A search box filters by action, kind, status, correlation ID, or touched target. The row count is capped (25 / 50 / 100 / 250, default 100) and paired with live tailing, so the newest traces are always in view.
+- **Trace inspector** — selecting a trace shows its own ID, its parent and root trace IDs (when it is a child trace), correlation ID (when present, shown in full), kind, duration, and touch/error counts. "Copy JSON" copies the full record.
 - **Trace map** — a visual of one trace: the action as origin, its events and resources as connected nodes, with per-node status and a red marker on failures. Plays as a sequential step-through replay, with a speed slider (1×–10×, live, persisted) and pause/play.
-- **Settings** — accent colour, display density, default trace view, row count, and default replay speed — all persisted to `localStorage`.
+- **Settings** — accent colour, display density, default trace view, row count, default replay speed, and a **Run diagnostics** button — all persisted to `localStorage` except diagnostics, which runs fresh each time.
+
+### Run diagnostics (Settings)
+
+The Settings page has a "Run diagnostics" button that runs the exact same checks as `traceact doctor` on the command line, via `GET /api/doctor` — Python version, state directory writability, whether a viewer is running, and (if a source is loaded) whether its trace data looks valid. Results appear as a checklist with a short progress indicator, and each failing check shows a one-line explanation of what it means and what to do about it. Useful when something isn't showing up in the log and you want to rule out a setup problem without opening a terminal.
 
 ### Viewer server API
 
@@ -745,13 +1004,16 @@ These endpoints are available while a viewer is running. Apps and scripts can ca
 
 | Method | Path | Request | Response |
 |---|---|---|---|
-| `GET` | `/api/health` | — | `{"status":"ok","version":"0.2.1","sources":N}` |
+| `GET` | `/api/health` | — | `{"status":"ok","version":"0.3.0","sources":N}` |
+| `GET` | `/api/doctor?source=` | — | `{"ok":bool,"version":"...","checks":[{"label","status","message","hint"?}]}` |
 | `GET` | `/api/sources` | — | `[{"name":"...","path":"..."}]` |
 | `POST` | `/api/sources` | `{"path":"..."}` | `{"name":"...","path":"..."}` |
 | `GET` | `/api/pick?type=file\|folder` | — | `{"path":"...","cancelled":bool}` |
 | `POST` | `/api/import` | `{"name":"file.jsonl","content":"..."}` | `{"name":"...","path":"...","imported":true}` |
 | `GET` | `/api/stream?source=NAME&limit=N` | — | SSE stream: `snapshot` then `append` events |
 
+`/api/doctor`'s `status` is `"pass"`, `"fail"`, or `"info"`; `hint` is present only on `"fail"` checks. `ok` is `true` only if every `"pass"`/`"fail"` check passed — `"info"` checks (traceact's version, whether a viewer is running) never affect it.
+
 The SSE stream delivers one `snapshot` message (the last N traces as a JSON array) then `append` messages for each newly-written trace. A `": keepalive"` comment is sent every 0.5 s when nothing new arrives, to keep the connection alive through proxies.
 
 ### Notes
@@ -843,6 +1105,33 @@ async function openViewer() {
 
 Note: cross-origin `fetch` to the viewer will always be blocked by CORS unless the viewer adds an `Access-Control-Allow-Origin` header (it doesn't, by design). Use `mode: "no-cors"` only to warm up the connection; don't try to read the response. The backend-route approach above is cleaner because it doesn't depend on the client being on the same machine as the viewer.
 
+### Admin-safe viewer pattern
+
+**The viewer has no authentication of its own** — no login, no token, no session check. This is intentional: it's a local dev tool, and adding auth would mean TraceAct owning credential storage, which it explicitly doesn't want to do. That means access control is entirely your responsibility if more than one trusted person can reach the machine it runs on.
+
+**Rule of thumb:** never bind the viewer to a non-localhost host (`--host 0.0.0.0` or similar) unless you put your own authentication in front of it. Binding `127.0.0.1` (the default) means only processes on the same machine can reach it, which is the safe default for local development.
+
+If you want a "traceact viewer" button inside an internal team tool (like the FastAPI/Flask examples above), gate the *button and the route*, not the viewer itself:
+
+```python
+# The route that launches/connects to the viewer sits behind your app's
+# own admin-only auth dependency — the viewer itself stays on localhost
+# and is never exposed directly.
+from fastapi import Depends
+from traceact.viewer.instance import launch_or_connect
+
+@router.get("/api/launch-viewer")
+async def launch_viewer(user=Depends(require_admin)):
+    loop = asyncio.get_event_loop()
+    url = await loop.run_in_executor(None, launch_or_connect,
+                                     "data/traces/traces.jsonl")
+    return {"url": url}
+```
+
+Because `launch_or_connect` starts the viewer on `127.0.0.1` by default, the returned URL only works for someone on the same machine as the server process — appropriate for a local dev box, not for handing a link to a remote teammate. If your team needs to view traces from a shared/remote environment, don't punch the viewer through to the network; instead have each person run `traceact view` against a synced or shared copy of the trace file on their own machine, or wait for a future TraceAct release aimed at that use case (see Notes above — network-exposed viewing is explicitly out of scope for the current local-only design).
+
+**Trace data itself may be sensitive.** Traces can contain request bodies, resource identifiers, and (if `capture_inputs` is misconfigured) unredacted arguments. Treat a running viewer, and the JSONL files it reads, with the same access discipline as application logs.
+
 ---
 
 ## Quick reference

{traceact-0.2.1 → traceact-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "traceact"
-version = "0.2.1"
+version = "0.3.0"
 description = "X-ray vision for your code. Lightweight action-level tracing for Python."
 readme = "README.md"
 requires-python = ">=3.9"
@@ -57,3 +57,7 @@ include = ["traceact*"]
 # Ship the viewer's static frontend (HTML/CSS/JS) inside the wheel.
 [tool.setuptools.package-data]
 "traceact.viewer" = ["static/*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"