Skip to content

development-lifecycle.md

Latest commit

 

History

History
74 lines (59 loc) · 3.83 KB

development-lifecycle.md

File metadata and controls

74 lines (59 loc) · 3.83 KB
Raw

Agent-safe local development and spin

dev (source checkout) and spin (installed / uvx) share the lifecycle manager. It identifies instances by canonical checkout path (dev) or data directory (spin). Calling the entry point twice does not restart a healthy stack.

uv run manage.py dev                 # start/reuse Django, Hatchet, worker, Caddy, Open WebUI
uv run manage.py dev status          # owner, health and allocated public port
uv run manage.py dev agent-info      # exhaustive instructions for agents
uv run manage.py dev down            # graceful shutdown; preserve data
uv run manage.py dev restart         # intentional full restart
uv run manage.py dev reset           # destructive; reseed and start
uv run manage.py dev uninstall       # remove owned data + scoped uv caches

uvx --from simpleaudit-studio spin status
uvx --from simpleaudit-studio spin agent-info
uvx --from simpleaudit-studio spin down
uvx --from simpleaudit-studio spin reset
uvx --from simpleaudit-studio spin uninstall

reset and uninstall confirm interactively; use --yes for explicitly authorized noninteractive runs. uninstall removes managed Open WebUI state, embedded Hatchet data, local databases, and package-scoped uv wheel caches. It does not remove source, external result folders, shared Postgres, unrelated uv artifacts, system Python, or a source checkout's .venv. uvx may retain shared cached environments that cannot be safely identified by package.

Parallel worktrees

A linked Git worktree gets isolated ports, chat storage, embedded Hatchet PostgreSQL and Django SQLite by default. The instance manager allocates ports before Django settings or migration start. To find the actual URL, use status; never assume port 8000. The public --port flag also configures Caddy's public listener, Django internal port, and the Open WebUI upstream.

Data layout:

  • dev: checkout's dev.sqlite3; other services under ~/.local/state/simpleaudit-studio/data/dev-<hash>/
  • spin: ~/.simpleaudit-studio/ (compatible with existing installations)
  • Registry: ${XDG_STATE_HOME:-~/.local/state}/simpleaudit-studio/instances/

The manager refuses to destructively delete custom SIMPLEAUDIT_DATA_DIR or SIMPLEAUDIT_SQLITE_PATH locations and never kills a PID merely because it happens to use a preferred port. A second process sharing the same data dir is rejected while another registered owner is alive.

Reload behavior and agent policy

Django's existing runserver child autoreloads Python code. Edited Django templates are read again on refresh; the browser is not automatically refreshed without a separate browser-reload integration. The embedded Hatchet worker currently remains inside the owning parent process and is not automatically reloaded. Changes to worker code require a planned restart, preferably while no audits are running. Do not pretend a Django reload updates the worker.

Always check dev agent-info/spin agent-info and status before attempting to start, restart, reset, or uninstall. Never manually kill a port holder, change a running instance's persistent data, or restart an unrelated worktree. reset and uninstall require the user to authorize potential data loss.

Scope and caveats

This manager supervises the existing single-process embedded stack; it does not magically turn Hatchet's worker into an independently hot-reloadable process or enable shared PostgreSQL for dev. Shared-database/multi-instance scenarios need a separate Postgres-backed development mode and migration coordination.

devctl.sh is kept as a compatibility wrapper and must not use its former kill -9/pgrep port-based cleanup. Running uvx itself may download the CLI package again before an uninstall subcommand is processed; uninstalling a uv-managed permanent tool is a distinct operation handled only if it exists.