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

3.3 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
  • can be packaged as a DMG

Layout Standard

Use this layout for new projects:

  • web/ for web backend source (app.py, modules, requirements)
  • mac/<AppName>Mac/ for Xcode project and SwiftUI shell
  • 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.
  • Include all required web files/modules in build inputs.
  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.
  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.
  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.
  1. Validate.
  • Python syntax: python -m py_compile on web entrypoint.
  • Xcode build: xcodebuild ... build.
  • Runtime check: no external browser opens, webview loads locally, settings persist across relaunch.

Required Deliverables

  • Embedded backend build script
  • macOS app host that launches backend + WKWebView
  • Shared settings sync path
  • README section for local build + DMG workflow
  • Verified build commands and final artifact locations

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.