[WIP] Add tethys run — zero-config single-file app runner (express mode POC)

[gagelarsen]

⚠️ Read this first

This is an AI-generated proof of concept. The design and implementation were produced with an AI assistant (Claude) working interactively with @gagelarsen, then verified end-to-end locally. It is a draft for discussion with the Tethys team — not a request to merge as-is. All suggestions, redesigns, and pushback are welcome.

Implements #1286.

What this does

tethys run app.py [-p PORT] [--host HOST] [--no-browser] [--no-reload] [--clean]

Runs a bare, single-file component app — never pip-installed, no pyproject.toml, no portal config, no database setup, no login — with the ergonomics of shiny run / streamlit run:

# app.py — complete and runnable
from tethys_sdk.components import ComponentBase

class App(ComponentBase):
    name = "My Dashboard"

@App.page
def home(lib):
    return lib.tethys.Display(lib.tethys.Map())

First run takes ~4s (silent SQLite migration); subsequent runs ~3s. Hot reload is on by default (Django's stock autoreloader — the app file is an imported module). tethys run with no argument looks for app.py in the cwd.

How it works (design)

"Portal-in-a-box": the existing portal runtime runs unmodified, configured down via an ephemeral generated environment — chosen over (a) a purpose-built minimal runtime (dual-runtime drift risk) and (b) materializing the file into a generated package (codegen indirection). Because everything downstream is stock machinery, an express app is guaranteed to behave identically when later installed in a real portal — the same file drops verbatim into a scaffolded component app's app.py (a future tethys scaffold --from app.py could automate graduation).

1. tethys_cli/run_commands.py (new): validates the file (AST check for a ComponentBase subclass), creates ~/.tethys/express/<pkg>_<hash-of-abs-path>/ as an isolated TETHYS_HOME, writes a portal_config.yml into it (MULTIPLE_APP_MODE: False, STANDALONE_APP: <pkg>, ENABLE_OPEN_PORTAL: True, persisted SECRET_KEY), runs manage.py migrate --no-input (idempotent, every start), then execs manage.py runserver. Configuration flows through env vars (TETHYS_HOME, TETHYS_EXPRESS_APP) so it survives autoreloader restarts. No changes to settings.py were needed.
2. tethys_apps/base/express.py (new): when TETHYS_EXPRESS_APP is set, loads the file as tethysapp.<pkg>.app and pre-registers it (plus a synthetic parent package) in sys.modules, so the untouched harvester/register_controllers machinery — including its importlib.reload() — resolves it like an installed app. Missing metadata is synthesized: package/root_url from the filename (parent dir for generic app.py), name title-cased, index = first @App.page function.
3. tethys_apps/harvester.py (~10 lines): include the express app in the harvest dict.
4. tethys_apps/base/component_base.py: __init_subclass__ hook calls the metadata synthesis at class-definition time — required because @App.page reads app.package at decoration time (ComponentLibrary keying).

Drive-by bug fixes (pre-existing, single-app mode)

Both were hit during testing and affect non-express portals too — happy to split them into a separate PR:

• tethys_apps/utilities.py: get_configured_standalone_app() caught Postgres's ProgrammingError but not SQLite's OperationalError, so a fresh single-app portal with reactpy_django installed crashed during migrate (reactpy's app-ready hook imports the URLconf, which queries TethysApp before tables exist).
• tethys_apps/base/component_base.py: auto nav links hard-coded /apps/<root_url>/, which 404s when MULTIPLE_APP_MODE=False (apps are served at root). Now settings-aware.

Verification performed

• 28 new unit tests (test_express.py, test_run_commands.py) — all passing; regression run of touched-module test files shows failure sets identical to main (3 pre-existing, unrelated).
• End-to-end in a real browser (Playwright): page renders, button click round-trips state over the ReactPy websocket, multi-page nav works, hot reload verified by editing the file mid-serve.
• Built a real dashboard app on it (Utah lakes map + click-for-fish-species from public APIs) as a dogfooding exercise.
• flake8 and black --check clean.

Known limitations / open questions

• Component apps only (no classic template apps) — intentional for v1.
• Hard-wired anonymous (ENABLE_OPEN_PORTAL); no auth flag yet.
• Multi-file express apps work incidentally (sibling controllers.py etc. are importable via the synthetic package path) but are untested/undocumented.
• The generated state dir accumulates under ~/.tethys/express/ (per-app, keyed by file path; --clean wipes one app's state). No global GC.
• requests/network access to esm.sh (React CDN) is required at page load, as with all component apps.
• Naming (tethys run vs tethys express), the state-dir lifecycle, and whether portal-in-a-box is the right long-term architecture are all up for debate in Feature proposal: tethys run app.py — zero-config single-file app runner ("Tethys Express") #1286.

🤖 Generated with Claude Code

[gagelarsen]

Added documentation in 35617c4:

• New CLI reference page (docs/tethys_cli/run.rst): quick start, how-it-works explanation, auto-generated argument docs (sphinx-argparse), and usage examples
• What's New entry for the release notes
• Cross-reference tip in the Component Apps SDK docs (app.py section) pointing to tethys run
• Added run to the CLI docs toctree

Sphinx build verified locally — no warnings from the changed files.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR adds an “express mode” workflow for running a single-file Tethys Component App via tethys run, by bootstrapping an isolated ephemeral portal config + DB and loading the app file under the tethysapp.<package> namespace so the existing portal/harvester machinery can run it unmodified.

Changes:

• Adds tethys run CLI command that generates an isolated TETHYS_HOME, migrates SQLite, and starts runserver.
• Implements express app loading/metadata synthesis (tethys_apps.base.express) and hooks it into harvesting and ComponentBase initialization.
• Documents the new command and adds unit tests for CLI + express loader behavior; includes a small standalone-app-mode DB error-handling fix.

Reviewed changes

Copilot reviewed 12 out of 12 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
tethys_cli/run_commands.py	New tethys run command: validates app file, generates express TETHYS_HOME, migrates DB, runs dev server.
tethys_cli/init.py	Wires the new run parser into the CLI entrypoint.
tethys_apps/utilities.py	Broadens standalone-app lookup exception handling to include SQLite OperationalError.
tethys_apps/harvester.py	Hooks express app harvesting into the existing app harvesting flow.
tethys_apps/base/express.py	New express-mode module loader and metadata synthesis utilities.
tethys_apps/base/component_base.py	Adds express metadata synthesis hook and fixes auto-nav links in single-app mode.
tests/unit_tests/test_tethys_cli/test_run_commands.py	Unit tests for tethys run CLI behavior and generated portal config.
tests/unit_tests/test_tethys_apps/test_base/test_express.py	Unit tests for express loader helpers and harvesting behavior.
docs/whats_new.rst	Release notes entry describing tethys run / express mode.
docs/tethys_sdk/components.rst	Adds a tip pointing component users to tethys run for quick prototyping.
docs/tethys_cli/run.rst	New CLI documentation page for tethys run.
docs/tethys_cli.rst	Adds the new tethys_cli/run page to the CLI docs toctree.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.