Positron Shell

Status: implemented as an experimental local shell in this slice.

The current Positron port lives under shells/positron/.

Current responsibilities:

  • import the shared Django code from src/ instead of forking app code into the shell

  • validate that the shared Django source tree is present before configuring Django, so startup failures stay readable

  • start Django inside the Positron process with an in-process WSGI server bound to a random localhost port

  • generate a fresh per-session shell-to-Django auth token, pass it into Django as DESKTOP_DJANGO_AUTH_TOKEN, and load the web view through Django’s /desktop-auth/bootstrap/ URL so Django can set an HttpOnly same-origin auth cookie before redirecting to the app

  • enforce a single running instance per app-data directory with a lock file before the in-process server starts

  • run the optional tasks_demo worker in-process on a background thread

  • always boot Django with desktop_django_starter.settings.packaged so local Positron runs validate the packaged-style app-data and staticfiles contract

  • refresh collected static files on startup without clearing the cache-backed staticfiles tree on every launch

  • reuse the shared brand source under assets/brand/ and generate shell-local icon outputs into shells/positron/resources/

  • keep Positron-specific runtime behavior under shells/positron/src/desktop_django_starter_positron/

Local commands:

  • just positron-install

  • just positron-check

  • just positron-start

  • just positron-smoke

  • just positron-icons

  • just positron-create

  • just positron-build

  • just positron-package-dmg

Update strategy in this repo:

  • manual-only for now

  • current install/update artifact: a local macOS DMG produced by just positron-package-dmg

  • current operator path: build the newer DMG locally on a macOS machine with the Briefcase prerequisites, quit the installed app, then replace the app manually from that newer DMG

  • current artifact boundary: just positron-package-dmg uses Briefcase ad-hoc signing, so the resulting app is only suitable for local validation on the machine that built it rather than a hosted end-user release lane

  • local Positron updates should leave per-user app data in place because the app bundle is replaced separately from the writable app-data directory

  • Briefcase development refresh flows such as briefcase update or briefcase build --update-resources are not presented here as end-user auto-update

  • there is no connected updater, hosted artifact lane, checksum lane, or GitHub release-publication flow for Positron in this repo

  • a broader Positron updater path would first need a real hosted artifact lane, checksum generation, release publication, platform signing/notarization, and Windows packaged install/run proof

Scope boundaries:

  • Positron is still experimental and local-only in this slice

  • GitHub Actions artifact generation remains out of scope

  • Electron remains the most complete shell path

  • packaged startup uses the same fallback DJANGO_SECRET_KEY value as Electron and Tauri when the environment does not provide one; this is only a local bootstrap convenience, not a release secret

  • Positron uses a bootstrap HttpOnly cookie instead of Electron’s hidden per-request header injection because this Toga web view path does not currently have an Electron-equivalent external-localhost outgoing request header hook

  • Positron now enforces single-instance startup, but unlike Electron and Tauri it currently exits the second launch instead of focusing the existing window

  • Positron intentionally always uses the packaged Django settings module, even during local shell runs, so the experimental shell exercises the desktop-style SQLite location and collected-staticfiles path instead of Django’s debug-oriented local settings

  • startup still refreshes collected static files locally without clearing the cache-backed staticfiles tree on every launch

  • splashscreen parity is intentionally not required on macOS for Positron

  • Positron is not a release-parity path in this slice

  • Windows packaged-build parity is not claimed for Positron yet

  • local macOS packaging uses Briefcase and currently depends on ad-hoc signing

tasks_demo posture in this slice:

  • supported

  • Positron intentionally differs from Electron and Tauri here: the shell starts the django_tasks_db worker in-process on a thread instead of spawning a db_worker subprocess