Development workflow and next steps
Source declarations now express which checkouts belong in .venv:
sources:
my.package:
repo: https://github.com/example/my.package.git
install: true
extras: [test]
Use sources list to inspect selection and checkout health, sources clone
to obtain missing code, and dependencies install to install it. Editable installation
avoids reinstalling after ordinary Python edits; dependency or extra changes still
require dependencies install. Restart the application when its imports or configuration
need refreshing. Use the existing shell’s Ctrl-Z detachment, db upgrade, and fg
attachment when the application needs to keep running during an upgrade.
Current reporting and scheduling
project describe now compares declarations with installed metadata and explains
configuration provenance, Jinja references, profile locations, file freshness,
service/template wiring, runtime health, and job history. Its HTML report is
searchable and responsive; focused sections also export JSON and Markdown.
cron adds manual and scheduled jobs through a Supervisor-managed Huey consumer.
See the job guide and development FAQ.
Supervisor startup now uses an incremental preparation graph. supervisor start --plan and project describe preparation explain required work; see the
preparation guide. Extending the graph to other command families
should preserve their explicit mutation and restart policies.
project doctor checks the target virtualenv, selected source installation
locations and modes, direct requirements, generated constraints, preparation,
and local services. It suggests next steps without changing the project. See the
doctor reference for the checks and their limits.
Selected sources can provide test_command; use test sources to run those
commands, including forwarded runner arguments. dependencies preview produces
temporary proposed inputs and invokes uv in dry-run mode. instance debug --debugpy
starts a loopback-only debugger, and supervisor restart PROGRAM targets a named
service. See the CLI reference.
Further work
Deeper dependency diagnosis. Extend doctor checks to nested requirement files and resolver output. Requested extras are not recorded in Python distribution metadata, so report their direct dependencies and explain what remains unknown.
Source-aware runtime impact. Associate running instances with selected sources and propose precise restart targets after code or dependency changes.
These remaining proposals build on the shared source plan, configuration trace, report sections, and job runner. Automatic reloads and database upgrades remain explicit future choices, rather than side effects of inspection or scheduling.