feat(launcher): configurable launch scripts + composable native primitives
- electron_relay: type launch_from_cache with script_template param; add copy_from_cache_to_temp export; add JSDoc for run_osascript hardening - launcher_file_cont: add get_launch_script_template() helper reading from device-level (event_device.data_json.launch_scripts) and event-level (events_loc.launcher.launch_scripts) config; wire into handle_open_file() - PROJECT__AE_Events_Launcher_Native_integration.md: add Section 8 (Configurable Launch Scripts); update IPC reference for new/changed handlers - MODULE__AE_Events_PressMgmt_Launcher.md: add configurable launch behavior note to Native Mode Safe Handover section
This commit is contained in:
Scott Idem
@@ -311,6 +311,13 @@ The Electron app zero-configs itself:
|
||||
3. Rename to original filename (e.g., `Abstract_101.pptx`)
|
||||
4. OS opens the file (Keynote, PowerPoint, Preview, etc.)
|
||||
|
||||
**Configurable launch behavior:** The open/launch command in step 4 can be overridden
|
||||
per file extension via `event_device.data_json.launch_scripts` (device-level config) or
|
||||
`event.launcher.launch_scripts` (event-level fallback). Templates use `{{path}}` as the
|
||||
file path placeholder; AppleScript or `shell:` prefixed commands are both supported. No
|
||||
Electron rebuild required to change how files open — edit config in Aether and it applies
|
||||
immediately. See `PROJECT__AE_Events_Launcher_Native_integration.md` Section 8.
|
||||
|
||||
Versioning is handled automatically: when a presenter uploads an updated file, the new
|
||||
hash is cached separately and the old one remains intact.
|
||||
|
||||
|
||||
@@ -144,7 +144,8 @@ no-op when `window.aetherNative` is not present (i.e., in browser/non-native mod
|
||||
### File Cache
|
||||
- `check_hash_file_cache({cache_root, hash, hash_prefix_length?})` — Verifies a file exists in the local hashed cache.
|
||||
- `download_to_cache({url, cache_root, hash, api_key, account_id, hash_prefix_length?})` — Streams a file download to the hashed cache with SHA-256 integrity check.
|
||||
- `launch_from_cache({cache_root, hash, temp_root, filename, hash_prefix_length?})` — Atomic "Safe Handover": copy from cache → tmp → rename → execute.
|
||||
- `copy_from_cache_to_temp({cache_root, hash, temp_root, filename, hash_prefix_length?})` — **Preferred primitive.** Copies a cached file to temp and returns `{ success, path }`. The Svelte caller decides what to do next (run a script, open it, etc.).
|
||||
- `launch_from_cache({cache_root, hash, temp_root, filename, hash_prefix_length?, script_template?})` — Combines copy + launch in one call. Uses `script_template` if provided, otherwise falls back to hardcoded extension logic. See **Configurable Launch Scripts** below.
|
||||
- `cleanup_tmp_files({cache_root, max_age_minutes?})` — Removes stale `*.tmp` download artifacts. Default: 1440 min (24h). Called at launcher startup.
|
||||
|
||||
> `hash_prefix_length` defaults to `2` throughout. Do not change without coordinating all devices — mismatched values create orphaned cache subdirectories.
|
||||
@@ -153,8 +154,8 @@ no-op when `window.aetherNative` is not present (i.e., in browser/non-native mod
|
||||
- `open_folder(path)` — Opens a path in the OS file manager.
|
||||
- `run_cmd({cmd, timeout?, return_stdout?})` — Async shell command execution.
|
||||
- `run_cmd_sync({cmd, return_stdout?})` — Synchronous shell command execution.
|
||||
- `run_osascript(script)` — Executes an AppleScript string. macOS only.
|
||||
- `kill_processes({process_name_li})` — Gracefully terminates processes by name.
|
||||
- `run_osascript(script)` — Executes an AppleScript string. macOS only. **Hardened (2026-05-11):** writes script to a temp `.scpt` file; multi-line scripts and paths with special characters now work correctly. No shell escaping needed in the passed string.
|
||||
- `kill_processes({process_name_li})` — Terminates processes by name. macOS/Linux: `pkill -f`. Windows: `taskkill /F`.
|
||||
- `open_local_file_v2(path)` — Opens a file with its default OS application.
|
||||
|
||||
### Presentations (Phase 5)
|
||||
@@ -176,5 +177,64 @@ All paths passed to native handlers should use tokens rather than hardcoded OS p
|
||||
- `[home]` — Resolved to the user's home directory by the native bridge.
|
||||
- `[tmp]` — Resolved to the system temporary directory.
|
||||
|
||||
---
|
||||
|
||||
## 8. Configurable Launch Scripts (No-Rebuild File Handling)
|
||||
|
||||
To avoid requiring a full Electron rebuild for changes to how files are opened, `launch_from_cache`
|
||||
supports an optional `script_template` parameter. When provided, Electron runs the template
|
||||
instead of its built-in hardcoded logic. The hardcoded logic remains intact as the fallback
|
||||
when no template is configured.
|
||||
|
||||
### Template Formats
|
||||
|
||||
| Format | Example |
|
||||
| :--- | :--- |
|
||||
| **AppleScript** (macOS) | Multi-line AppleScript string with `{{path}}` placeholder |
|
||||
| **Shell command** | String prefixed with `shell:` — e.g. `shell:open "{{path}}"` |
|
||||
|
||||
The placeholder `{{path}}` is replaced with the full resolved path to the file in the
|
||||
temp directory (after the atomic copy from cache).
|
||||
|
||||
### Where to Configure
|
||||
|
||||
Templates are resolved in priority order by `get_launch_script_template()` in
|
||||
`launcher_file_cont.svelte`:
|
||||
|
||||
1. **`event_device.data_json.launch_scripts`** — API-driven, per-device. Highest priority.
|
||||
Set via the `event_device` record (Pres Mgmt → Device Management or direct DB edit).
|
||||
2. **`$events_loc.launcher.launch_scripts`** — Local persistent config. Editable via the
|
||||
Launcher config UI (planned) or direct `localStorage` manipulation.
|
||||
|
||||
If neither is set, `script_template` is `null` and Electron uses its built-in hardcoded defaults.
|
||||
|
||||
### Key Format
|
||||
|
||||
Keys are lowercase file extensions without the dot. A `"default"` key catches all
|
||||
unrecognised extensions.
|
||||
|
||||
```json
|
||||
// event_device.data_json.launch_scripts example
|
||||
{
|
||||
"launch_scripts": {
|
||||
"pptx": "tell application \"Microsoft PowerPoint\"\n activate\n open (POSIX file \"{{path}}\")\n delay 3\nend tell\ntell application \"System Events\"\n keystroke return using command down\nend tell",
|
||||
"key": "tell application \"Keynote\"\n activate\n open (POSIX file \"{{path}}\")\n delay 1\n start (front document)\nend tell",
|
||||
"pdf": "shell:open \"{{path}}\"",
|
||||
"default": "shell:open \"{{path}}\""
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Known Issue: `launch_presentation` vs `launch_from_cache` Inconsistency
|
||||
|
||||
`shell_handlers.ts` `native:launch-presentation` still uses the old `osascript -e "<inline>"` approach
|
||||
for its AppleScript execution. `file_handlers.ts` `native:launch-from-cache` uses the hardened
|
||||
temp-`.scpt`-file approach. These two handlers behave differently for identical file types.
|
||||
|
||||
- **`launch_from_cache`** (used by the "Open" button in the Launcher file list) — hardened, correct.
|
||||
- **`launch_presentation`** (used by `electron_relay.launch_presentation`) — legacy `-e` flag, fragile on paths with spaces or special characters.
|
||||
|
||||
**Recommendation:** `launch_presentation` should be updated to use the temp-`.scpt` approach in a future Electron build. It is not used in the primary file-open flow today, so this is not blocking.
|
||||
|
||||
### Not Exposed via Relay (intentional)
|
||||
- `get_seed_config` / `get_jwt` — Exposed in the preload but not relayed to the UI. The JWT and seed are injected into the environment at startup; components should not call these directly.
|
||||
|
||||
Reference in New Issue
Block a user