Ops Tools

This chapter documents the operational tooling suite for bloqr-backend / Bloqr. Each tool is a standalone Python script in tools/ and has a matching interactive Marimo runbook in tools/runbooks/.

Admin starting point: Run deno task runbook:pipeline to open the master health dashboard runbook in your browser. Everything you need is inside.

Quick Start

# One-time setup (from repo root)
uv sync --directory tools

# Launch the master pipeline runbook — the recommended admin entry point
deno task runbook:pipeline
# — or —
marimo run tools/runbooks/pipeline.py

The master pipeline runbook opens at http://localhost:2718 and shows:

Real-time health status for every tool (last run result)
Tool selector with per-tool flag configuration
Pipeline execution with live progress
Log browser for all tools
One-click log file copying for AI assistants

What Is Marimo?

Marimo is an open-source (Apache 2.0) reactive Python notebook that runs in your browser via a single command. Key advantages:

Property	Detail
Self-contained	One `.py` file per runbook — no JSON, no platform account
Git-friendly	Plain Python diffs cleanly — no notebook JSON merge conflicts
No learning curve	Run one command, get a browser UI
Reactive	Changing an input cell automatically updates all downstream cells
Free & local-first	`uv sync --directory tools` — nothing else required
CI/headless mode	`marimo run <file.py> --no-token` for scripted pipelines

Runbooks are entirely self-contained. All documentation, environment configuration, execution, log viewing, and AI log-sharing are embedded inside the .py file. No markdown files are required at runtime.

Available Tools

Tool	Script	Runbook	Docs
Auth Healthcheck	`tools/auth-healthcheck.py`	`deno task runbook:auth-healthcheck`	→

Future tools planned:

db-healthcheck.py — Neon / Prisma schema drift, row counts, replication lag

kv-inspector.py — Better Auth KV key explorer with TTL and prefix breakdown

worker-smoke-test.py — Smoke test all API endpoints and report status codes

d1-audit.py — D1 table structure, row counts, and index analysis

deployment-verify.py — Post-deploy validation: worker version, secrets present, bindings wired

Directory Structure

graph TD
    A["tools/"] --> B["auth-healthcheck.py — script"]
    A --> C["auth-healthcheck.env — local config (gitignored)"]
    A --> D["auth-healthcheck.env.example — committed template"]
    A --> F["runbooks/"]
    F --> G["pipeline.py — master runbook (admin entry point)"]
    F --> H["auth-healthcheck.py — per-tool runbook"]
    F --> I["shared/__init__.py — shared helper library"]
    A --> J["pyproject.toml — uv-managed dependencies"]
    A --> K["docs/"]
    K --> L["auth-healthcheck/README.md — in-depth reference"]
    A --> M["logs/"]
    M --> N["auth-healthcheck/ — per-tool logs & JSON reports"]
    A --> O["tests/"]
    O --> P["test_runbooks.py — pytest tests (57+ cases)"]
    O --> Q["conftest.py — pytest fixtures"]

Tool Conventions

Every tool follows these conventions for consistency and CI-pipeline compatibility:

Convention	Detail
Config file	`tools/<tool>.env` (gitignored — copy from `.env.example`)
Config template	`tools/<tool>.env.example` (committed — safe to share)
Dependencies	`tools/pyproject.toml` (uv-managed — `uv sync --directory tools` to install)
JSON report	`tools/logs/<tool>/<tool>-YYYYMMDD-HHMMSS.json`
Text log	`tools/logs/<tool>/<tool>-YYYYMMDD-HHMMSS.log`
Run modes	`--mode all` (checks + cleanup), `--mode checks`, `--mode cleanup`, `--dry-run`
Interactive menu	Shown when run without `--mode` (requires a TTY)
AI-ready output	JSON report contains full results, errors, and summary — paste to Copilot / Claude

Setup (one time)

# From repo root
uv sync --directory tools

# Verify (should print marimo version)
uv run --directory tools marimo --version

Add a shell alias for convenience:

# Add to ~/.zshrc or ~/.bashrc
alias bloqr-tools='cd /path/to/bloqr-compiler && uv sync --directory tools'
alias bloqr-runbooks='cd /path/to/bloqr-compiler && uv run --directory tools marimo run runbooks/pipeline.py'

Deno Shortcut Tasks

Run mode (view-only, cells execute immediately)

Task	Command	Description
`deno task runbook:setup`	`uv sync --directory tools`	Install all dependencies (one-time)
`deno task runbook:pipeline`	`marimo run runbooks/pipeline.py`	Master pipeline runbook — recommended admin entry point
`deno task runbook:auth-healthcheck`	`marimo run runbooks/auth-healthcheck.py`	Auth healthcheck runbook
`deno task runbook:dashboard`	`marimo run runbooks/dashboard.py`	Health dashboard runbook
`deno task runbook:error-analysis`	`marimo run runbooks/error-analysis.py`	Error analysis runbook
`deno task runbook:gallery-demo`	`marimo run runbooks/gallery-demo.py`	Gallery / component demo runbook

Edit mode (live-editable, hot-reload on save)

Task	Command	Description
`deno task runbook:edit:pipeline`	`marimo edit runbooks/pipeline.py`	Edit the master pipeline runbook
`deno task runbook:edit:auth-healthcheck`	`marimo edit runbooks/auth-healthcheck.py`	Edit the auth healthcheck runbook
`deno task runbook:edit:dashboard`	`marimo edit runbooks/dashboard.py`	Edit the dashboard runbook
`deno task runbook:edit:error-analysis`	`marimo edit runbooks/error-analysis.py`	Edit the error analysis runbook
`deno task runbook:edit:gallery-demo`	`marimo edit runbooks/gallery-demo.py`	Edit the gallery demo runbook
`deno task runbook:edit:mcp`	`marimo edit --mcp --no-token`	Start marimo as an MCP server for AI tool integration (no specific file — opens the editor home)

Server / utility

Task	Description
`deno task runbook:server`	Run the pipeline runbook on `127.0.0.1:2718` (fixed host/port for scripted access)
`deno task runbook:server:pipeline`	Alias for `runbook:server` with an explicit name
`deno task runbook:convert`	Convert between Jupyter notebook (`.ipynb`) and marimo script (`.py`) formats
`deno task runbook:test`	Run all runbook tests with pytest
`deno task runbook:lint`	Lint runbook Python files with ruff
`deno task runbook:fmt`	Format runbook Python files with ruff
`deno task runbook:typecheck`	Type-check runbook files with `ty`

Edit vs. Run Mode

Marimo has two distinct modes that behave very differently:

Mode	Command	Code visible?	Cells auto-run?	Use when
Run	`marimo run <file>`	❌ Hidden	✅ On load	Using the runbook as a tool in production
Edit	`marimo edit <file>`	✅ Visible	⚡ Reactive (initial run via ▶ or `auto_instantiate`)	Developing or debugging a runbook
MCP	`marimo edit --mcp --no-token`	✅ Visible	⚡ Reactive (initial run via ▶ or `auto_instantiate`)	Connecting AI tools (Copilot, Claude) via Model Context Protocol

Important: In Edit and MCP modes, cells react to upstream changes automatically, but the initial execution on open only happens if auto_instantiate = true is set in tools/.marimo.toml (it is — so cells run on open by default in this project). If a cell appears to do nothing, check the terminal output for Python errors — a cell with an import or syntax error will silently block execution.

MCP mode (runbook:edit:mcp) starts marimo as a Model Context Protocol server. This allows AI assistants to call marimo tools programmatically. It does NOT replace the browser UI — the notebook is still fully interactive in the browser.

Pipeline Chaining

Tools can be chained together in a bash pipeline by using --mode all and reading the JSON report that each tool writes to tools/logs/<tool>/.

Example: Auth check → DB check (future)

# Step 1: Run auth healthcheck
uv run --directory tools python auth-healthcheck.py --mode all

# Step 2: Grab the JSON report
AUTH_REPORT=$(ls -t tools/logs/auth-healthcheck/*.json | head -1)

# Step 3: Check overall status
FAILED=$(jq '.summary.failed' "$AUTH_REPORT")
if [ "$FAILED" -gt 0 ]; then
    echo "❌ Auth check failed — stopping pipeline"
    jq '.errors' "$AUTH_REPORT"
    exit 1
fi

# Step 4: Run next tool
python tools/db-healthcheck.py --mode all

# (and so on)

Using the Master Pipeline Runbook

The pipeline.py Marimo runbook provides a visual version of this flow:

Open deno task runbook:pipeline
Check the health dashboard — green/red/yellow status for each tool’s last run
Select the tools you want to chain using the checkbox UI
Optionally configure per-tool flags (mode, API base, etc.)
Click Run Pipeline — tools execute in sequence with a live progress tracker
Review the aggregate results summary
Browse log files inline or copy the JSON report path to paste into an AI assistant

Common Pipeline Patterns

Pattern	Tools	Use case
Auth smoke test	`auth-healthcheck`	Before any deploy or after auth config changes
Full stack check	`auth-healthcheck → db-healthcheck → worker-smoke-test`	Post-deploy validation
Cleanup only	`auth-healthcheck --mode cleanup`	After a failed check leaves test data
Dry run config check	`auth-healthcheck --dry-run`	Verify env file is correct without making requests

Log Files & AI Assistants

Every tool writes two output files:

JSON report (tools/logs/<tool>/<tool>-YYYYMMDD-HHMMSS.json) — machine-readable, structured, safe to paste into AI chats
Text log (tools/logs/<tool>/<tool>-YYYYMMDD-HHMMSS.log) — human-readable terminal output with ANSI codes stripped

To share with an AI assistant (Copilot, Claude, etc.):

# Print the latest report for copying
cat $(ls -t tools/logs/auth-healthcheck/*.json | head -1)

# Or let the Marimo runbook do it — the "📂 View Logs" section has a file picker
# that displays the log inline and gives you the file path to copy

Tests

Runbook tests live in tools/tests/ and are run with pytest. They do not require network access and do not start Marimo:

uv run --directory tools pytest tests/ -v
# or
deno task runbook:test

Tests validate:

All runbook .py files are valid Python syntax
Marimo App declaration and @app.cell structure are present
KNOWN_TOOLS registry is complete and correctly keyed
Shared helper library (shared/__init__.py) functions behave correctly
Directory structure is correct (logs, docs, pyproject.toml)
PR template exists

Marimo Configuration

Marimo behaviour for this project is controlled by tools/.marimo.toml. The file is committed to the repository — all contributors share the same configuration.

`.marimo.toml` — Section Reference

`[package_management]`

[package_management]
manager = "uv"                # Use uv for inline package management

Marimo uses uv to install missing packages declared via import when the notebook is run in an environment where they are absent. This is consistent with the project-wide uv toolchain.

`[formatting]`

[formatting]
line_length = 120             # Must match ruff line-length in pyproject.toml

Formatting is applied automatically on save (see [save] below).

`[save]`

[save]
autosave       = "after_delay"
autosave_delay = 1000
format_on_save = true

Notebooks are auto-formatted with ruff on every save, keeping cell code consistent with pyproject.toml lint rules.

`[completion]`

[completion]
activate_on_typing = true
copilot            = false    # Copilot completions are disabled to prevent
                              # AI-generated code from auto-running in cells

Copilot completions are disabled at the [completion] level to prevent AI-generated suggestions from executing automatically in reactive notebook cells.

`[runtime]`

[runtime]
auto_instantiate = true       # Run all cells on notebook load
auto_reload      = "lazy"     # Avoid re-running expensive cells on every import change

auto_instantiate = true is required for CI/headless mode — without it, cells wait for user interaction before executing. Set auto_reload = "autorun" if you prefer fully reactive notebooks.

`[language_servers]`

[language_servers.pylsp]
enabled = true                # Python Language Server (completions, hover, diagnostics)

[language_servers.ty]
enabled = true                # Astral ty type checker in the notebook editor

Both LSPs run in the Marimo browser editor. ty provides fast type inference (same as CI); pylsp provides hover docs and symbol search.

`[ai.anthropic]`

[ai.anthropic]
model = "claude-sonnet-4-5"
# api_key = ""  # Set via ANTHROPIC_API_KEY env var instead

Set the API key in your shell before running marimo (export ANTHROPIC_API_KEY="sk-ant-..."), or add it to tools/auth-healthcheck.env.

Python Version Pinning

tools/.python-version pins the exact Python version used by uv for this project:

3.11

This file is read by uv when creating or syncing the virtual environment. It ensures all contributors and CI use the same interpreter, regardless of which Python versions are installed system-wide.

To check the active version:

uv run --directory tools python --version
# Python 3.11.x

`runbook:edit:*` Tasks

See the Deno Shortcut Tasks and Edit vs. Run Mode sections above for a comprehensive reference of all available runbook task shortcuts and the difference between run, edit, and MCP modes.

Adding a New Tool

Create tools/<tool>.py — the script
Create tools/<tool>.env.example — config template
Add tools/<tool> to KNOWN_TOOLS in tools/runbooks/shared/__init__.py
Create tools/logs/<tool>/.gitkeep
Create tools/docs/<tool>/README.md — in-depth reference
Create tools/runbooks/<tool>.py — Marimo runbook
Add "runbook:<tool>" task to deno.json
Update this file (docs/tools/README.md) — add row to the Available Tools table
Run deno task runbook:test — all 57+ tests should still pass (plus any new ones you add)
Open a PR using the Tools / Runbooks PR template (.github/PULL_REQUEST_TEMPLATE/tools-runbooks.md)

Remote Access (Future)

The tooling is designed for local use first, but Marimo supports a remote mode via its built-in marimo server command. When remote access is needed (e.g., a CTO on a plane with only a tablet):

# Start Marimo in server mode (exposes all runbooks via browser)
marimo run tools/runbooks/pipeline.py --host 0.0.0.0 --port 2718

This can be exposed securely via:

Cloudflare Tunnel (cloudflared tunnel run) — zero-config, no firewall rules
Cloudflare Access policy on the tunnel — requires authentication before reaching Marimo
Potential future subdomain: tools.bloqr.dev

Important: Marimo does not natively run inside a Cloudflare Worker (Workers are JS/Wasm only and do not support Python). Remote access always requires a Python process (a VM, container, or developer laptop). The recommended pattern is Marimo + Cloudflare Tunnel + Cloudflare Access.

Troubleshooting the Tools

Symptom	Fix
`marimo: command not found`	Run `uv sync --directory tools` or `deno task runbook:setup`
`ModuleNotFoundError: No module named 'shared'`	Run from repo root: `cd /path/to/bloqr-compiler && uv run --directory tools marimo run runbooks/auth-healthcheck.py`
`psycopg2 not found`	Run `uv sync --directory tools` to install all dependencies
`wrangler: command not found`	`npm install -g wrangler` or use `deno run -A npm:wrangler`
Browser doesn’t open	Navigate to `http://localhost:2718` manually
Port 2718 in use	`marimo run tools/runbooks/pipeline.py --port 2719`

Ops Tools

Ops Tools

Quick Start

What Is Marimo?

Available Tools

Directory Structure

Tool Conventions

Setup (one time)

Deno Shortcut Tasks

Run mode (view-only, cells execute immediately)

Edit mode (live-editable, hot-reload on save)

Server / utility

Edit vs. Run Mode

Pipeline Chaining

Example: Auth check → DB check (future)

Using the Master Pipeline Runbook

Common Pipeline Patterns

Log Files & AI Assistants

Tests

Marimo Configuration

.marimo.toml — Section Reference

[package_management]

[formatting]

[save]

[completion]

[runtime]

[language_servers]

[ai.anthropic]

Python Version Pinning

runbook:edit:* Tasks

Adding a New Tool

Remote Access (Future)

Troubleshooting the Tools

`.marimo.toml` — Section Reference

`[package_management]`

`[formatting]`

`[save]`

`[completion]`

`[runtime]`

`[language_servers]`

`[ai.anthropic]`

`runbook:edit:*` Tasks