| name | app-it-static |
| description | Turn a finished or buildable web app into a macOS Dock-launchable .app that serves built output instead of a dev server. Use when the user asks for app-it-static, a finished site/app launcher, a lightweight Dock app, or a dist/build/out bundle clickable from the Dock. Builds once, serves a snapshot via static-server.py or file://, and routes live projects to app-it. macOS only. |
app-it-static - Make a finished build launchable from the Dock
app-it-static is the no-dev-server companion to app-it: it builds once,
serves the finished output, installs beside live apps in ~/Applications/App It/,
and keeps the native Swift WebKit window and Dock identity.
Non-Negotiables
- Run
templates/inspect-static.sh first and read the output before editing.
- Confirm before the first project build. It can write files and take time.
- Never run
npm run dev. If the app needs a live dev server, route to
app-it and say why.
- Serve a snapshot and say so. Source changes need
desktop:rebuild.
- Default to
serve_mode: "server". Use file only after proving the build is
file:// safe.
- Copy shipped templates and customize through
scripts/app-it.config.json.
Do not re-derive launcher patterns.
- Verify the built output, app bundle, install path, runtime port, server
response, quit cleanup, and human-only GUI limits.
Reference Map
Open only the files needed by the inspection result:
references/project-inspection.md - static-servable tests, build/output
detection, package managers, monorepos, names, bundle IDs, and tools.references/serve-modes.md - server vs file decisions and the file:// safety
checklist.references/generated-files.md - template roster, shared-template rules,
allowed target-project files, config JSON, and package scripts.references/verification.md - smoke tests, app-bundle checks, runtime checks,
cleanup, and human/deferred buckets.references/report-template.md - exact final report format plus decision
history.references/anti-patterns.md - traps that cause broken static launchers.
Templates
Templates live next to this file in templates/. Copy them into the target
project; do not rewrite them. See references/generated-files.md for the full
roster.
Shared templates are byte-identical to app-it and guarded by repo validation:
wrapper.swift, native-run-stub.c, desktop-icons.sh,
desktop-icons-preview.sh, desktop-install.sh, info-plist-template.xml, and
placeholder-icon-gen.sh. If launcher internals change, edit the app-it copy
and re-sync this plugin so marketplace installs stay self-contained.
Workflow
1. Inspect
Run:
/path/to/plugins/app-it-static/skills/app-it-static/templates/inspect-static.sh
Use disk truth: package.json, config files, built output, and actual scripts.
Read references/project-inspection.md before deciding whether the app is
static-servable, which build command/output dir to use, or whether a monorepo
contains multiple apps.
2. Decide
For each user-facing app:
Static build or hand-written index.html exists?
no -> route to app-it
yes -> needs http origin, routing fallback, fetch(), or service worker?
yes -> server mode (default)
no -> file mode candidate
When unsure, choose server mode. It costs a tiny Python process and is the safe
default for framework builds.
3. Build
Confirm with the user, run the project build once, then copy templates into the
target project and write scripts/app-it.config.json. desktop:build assembles
the .app; it must not run the project build. desktop:rebuild is the refresh
path that reruns the build command.
Read references/generated-files.md before editing package scripts, generated
docs, config JSON, icons, or install paths.
4. Verify
Verification is mandatory. Read references/verification.md and run the checks
that apply: built index.html, Mach-O Contents/MacOS/run, executable
run.sh, Mach-O wrapper, plist placeholders gone, .icns, installed-path
open, server response, and Cmd+Q cleanup for server mode.
Never claim GUI-only checks passed unless a display actually proves them. Put
window render and Dock icon identity in the human bucket when needed.
5. Report
Use references/report-template.md for both the chat reply and
docs/desktop-launcher.app-it-static-report.md. Include snapshot limitations,
refresh command, verification results, known limits, and decision history.
Stage files only when the local convention or user request asks for it. Do not
commit unless asked.
Quick Defaults
- Install destination:
~/Applications/App It/.
- Bundle ID prefix:
com.user.<slug>.
- Serve mode:
server, unless file:// safety is proven.
- Vite/CRA/Astro/SvelteKit static/Next export/Angular/Nuxt generate: usually
server mode.
- Hand-written
index.html with relative assets and no routing/fetch/service
worker: file mode candidate.
- Missing
swiftc or python3: stop and say xcode-select --install.
Stop Signs
Stop and explain clearly when the app only works through a live dev server, the
build fails before launcher work, the output dir lacks index.html, required
tooling is missing, or the environment cannot verify a claim the report would
need.
