Skip to content

Refactor: serve.py is a 3000-line god-module β€” split into cli/*.pyΒ #156

@tcconnally

Description

@tcconnally

Severity: 🟒 Low (architecture; long-term maintenance)

src/perseus/serve.py is ~3000 lines covering: render, watch, graph, prefetch, synthesize, pack, validate, launchd install, MCP dispatch, cron, systemd, health, doctor, trust, update, oracle, serve HTTP, init.

This is the single biggest correctness/maintainability risk in the codebase. A change to any one command requires reading a massive blast radius.

Suggested decomposition

src/perseus/cli/
    render.py
    watch.py
    synth.py
    pack.py
    install.py
    doctor.py
    trust.py
    update.py
    oracle.py
    serve_http.py
    scheduler.py  (launchd/cron/systemd)

Keep serve.py as a thin re-export shim for backward compatibility. No behavior change β€” pure refactor. Ship as v1.1.0.

Acceptance criteria

  • All existing tests pass without modification.
  • git diff shows pure code movement (no logic deltas) per command file.
  • Public symbols (cmd_render, cmd_serve, etc.) remain importable from perseus.serve.

Metadata

Metadata

Assignees

No one assigned

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions