somnus-debug 0.1.0

What used to be four scripts copied by hand between projects, now one package with one CLI.

What this is

Somnus's project-agnostic Python dev tooling — production-readiness diagnostics, an AST class/definition indexer, bytecode-cache cleanup, and a portable single-test harness scaffold — packaged as one real pip-installable CLI instead of loose scripts.

Zero runtime dependencies beyond pyyaml, and that's only for pycache-clean — doctor and structure are stdlib-only.

Install

git clone <this repo>
cd somnus-debug
pip install -e .

pip install somnus-debug isn't live yet — the package is publish-ready (MIT-licensed, real PEP 621 metadata, verified build) but hasn't actually been uploaded anywhere. See docs/PUBLISHING.md for what that takes and what's still open before it happens.

The tools

Every tool is also installed as its own script for muscle memory: somnus-doctor, somnus-structure, somnus-pycache-clean.

somnus-debug · quickstart · SESSION

daeron@somnus:~$ pip install -e .
Successfully installed somnus-debug-0.1.0

daeron@somnus:~$ somnus-debug doctor init-config -o python_doctor.yaml
Wrote default configuration: python_doctor.yaml

daeron@somnus:~$ somnus-debug doctor scan . -o report.md
Scan complete: files=42, issues=118, critical=0, serious=9

daeron@somnus:~$ somnus-debug structure src/core.py -o CORE_INDEX.md
Class Index for `core.py` written to CORE_INDEX.md

daeron@somnus:~$ somnus-debug pycache-clean --config config.yaml --dry-run
Summary: deleted 6 directories, 0 files; freed 2.10 MiB # dry run — nothing actually removed

daeron@somnus:~$ █

Full flag reference and worked examples for every command: docs/MANUAL.md.

Build status

Honest, not aspirational — this reflects what's actually been verified, not what's planned.

somnus-debug · build status — 2026-09-01 · STATUS

Open items. pip install somnus-debug means an actual PyPI upload, which has not happened — the required TestPyPI-first release gate is in docs/PUBLISHING.md. The old root-level scripts (python_production_doctor.py, analyze_python_structure.py, pycache_cleaner.py, run_test.py, python_doctor.yaml) are still sitting next to src/somnus_debug/ pending cleanup — harmless, just redundant.

Using it as a library

from somnus_debug.structure.core import build_index
from somnus_debug.doctor.core import ProjectScanner, ConfigManager
from somnus_debug.pycache_cleaner.core import PycacheCleaner, CleanerConfig

Each core.py is the original single-file implementation, moved into the package rather than rewritten — anything importable from the standalone script is importable from somnus_debug.<tool>.core too.

Repository layout

pyproject.toml              package metadata, deps, entry points
LICENSE                      MIT
README.md                    this file
src/somnus_debug/
    cli.py                    `somnus-debug <command>` dispatcher
    doctor/core.py             = old python_production_doctor.py
    doctor/default_config.yaml = old python_doctor.yaml
    structure/core.py          = old analyze_python_structure.py
    pycache_cleaner/core.py    = old pycache_cleaner.py
    test_harness/scaffold.py + templates/{run_test.py, CONTRACT.md}
    tests/test_cli_smoke.py      10 real subprocess CLI smoke tests
docs/
    MANUAL.md                  full command reference (start here for usage)
    PUBLISHING.md               the real-PyPI-release checklist
    CONTRACT.md                 governs run_test.py's artifact contract
    OPSEC.md                    Somnus agent operational security protocol
    Python_Doctor_QUICKSTART.md  deep config-field reference for `doctor`

Documentation index

• STATE.md — what actually exists and works right now, verified not assumed.
• PLAN.md — what's next, in dependency order.
• docs/MANUAL.md — day-to-day command reference, every flag, worked examples, troubleshooting.
• docs/AGENTS_APPENDIX.md — pasteable global or repository-local agent guidance; installation and instruction hydration are intentionally separate.
• docs/PUBLISHING.md — the checklist for actually shipping this to PyPI.
• docs/Python_Doctor_QUICKSTART.md — full python_doctor.yaml field reference.
• docs/CONTRACT.md — what run_test.py does and does not own.
• docs/OPSEC.md — SUPREME-authority agent security posture for this codebase.