mbrucedogs/maneshtrader
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
cd042f105b
maneshtrader/skills/macos-selfcontained-webapp/SKILL.md

4.4 KiB
Raw Blame History

name description
macos-selfcontained-webapp Build or refactor a project so a web app runs as a self-contained macOS app: embedded local backend binary + SwiftUI/WKWebView shell + packaging scripts. Use when a user has web logic and wants no external browser, no separate web-code install, local execution from inside .app, and repeatable DMG packaging.

macOS Self-Contained Web App

Outcome

Deliver one installable macOS app that:

  • launches an embedded backend executable from app resources
  • opens the web UI only inside WKWebView
  • persists settings locally and supports native-to-web sync
  • provides native app-level help/onboarding (not only in the web UI)
  • can be packaged as a DMG

Layout Standard

Use this layout for new projects:

  • web/src/ for web backend source (app.py, modules, requirements)
  • mac/src/ for Xcode project and SwiftUI shell sources
  • scripts/ for build and packaging automation
  • docs/ for architecture and onboarding docs

For existing repos, avoid destructive renames unless explicitly requested. Add compatibility paths or migration commits in small steps.

Detailed naming guidance: references/layout-and-naming.md

Workflow

  1. Inventory existing architecture.
  • Identify backend entrypoint, runtime dependencies, and static/resource files.
  • Confirm current launch mode and where browser auto-open is happening.
  1. Create embedded backend launcher.
  • Add a thin launcher (backend_embedded_launcher.py or equivalent) that starts the web server on 127.0.0.1 and reads port from env (for example MANESH_TRADER_PORT).
  • Ensure browser auto-open is disabled.
  1. Build backend into a single executable.
  • Add scripts/build_embedded_backend.sh that compiles backend into a one-file executable and copies it into the mac target resource folder.
  • Use generic discovery:
    • discover *.xcodeproj under mac/src
    • discover scheme via xcodebuild -list -json (fallback to project name)
    • discover/create EmbeddedBackend folder under selected project sources
  • Include all required web files/modules in build inputs.
  • Default backend name should be stable (for example WebBackend) and configurable via env.
  1. Implement SwiftUI host shell.
  • Use @Observable host state (no ObservableObject/Combine).
  • Start/stop backend process, detect available local port, and handle retries.
  • Render URL in WKWebView only.
  • Keep app responsive when backend fails and surface actionable status.
  • Resolve backend executable by checking both current and legacy names during migration.
  • Add a native toolbar Help button that opens bundled help content in-app.
  1. Define settings sync contract.
  • Use shared settings file (for example ~/.<app>/settings.json) as source of truth.
  • Normalize settings both in web app and native app.
  • Pass effective settings via URL query params on launch/reload/restart.
  • Keep onboarding limited to starter fields; preserve advanced fields.
  • Add web-only fallback access to help/onboarding (for users not using the mac wrapper).
  1. Automate packaging.
  • Add scripts/build_selfcontained_mac_app.sh to build embedded backend then Xcode app.
  • Add scripts/create_installer_dmg.sh for distributable DMG.
  • Use generic app bundle discovery for DMG defaults where possible.
  • Standardize installer artifacts under build/dmg/ (not repo root).
  • Ensure .gitignore excludes generated artifacts (build/, *.dmg, temp rw.*.dmg).
  1. Validate.
  • Python syntax: python -m py_compile on web entrypoint.
  • Tests: PYTHONPATH=web/src pytest -q web/src/tests.
  • Xcode build: xcodebuild ... build.
  • Runtime check: no external browser opens, webview loads locally, settings persist across relaunch.
  • Verify help works in both modes:
    • native toolbar help popup in mac app
    • sidebar help fallback in web-only mode

Required Deliverables

  • Embedded backend build script
  • macOS app host that launches backend + WKWebView
  • Shared settings sync path
  • Native help/onboarding popup + web fallback help entry
  • README section for local build + DMG workflow
  • Verified build commands and final artifact locations
  • .gitignore updated for build/installer outputs

References

  • Layout and migration rules: references/layout-and-naming.md
  • Implementation blueprint and command templates: references/implementation-blueprint.md

Bundled Script

Use scripts/scaffold_web_mac_layout.sh to create a new standardized folder skeleton for fresh projects.