fix(packaging): workaround yauzl/Node 26 hang + fix API bootstrap contract

Packaging was silently hanging forever because yauzl 2.10.0 read streams
emit no data events under Node 26, causing extract-zip to block indefinitely
inside @electron/packager 20. Fix: postinstall script patches
@electron/packager/dist/unzip.js to use bsdtar (libarchive) instead.
bsdtar was chosen over 7z because 7z refuses chained symlinks in macOS
.app framework bundles. Both package:linux and package:mac now produce
correct output.

Also corrects the V3 API bootstrap contract in api_client.ts:
- SearchQuery body was wrapped in an extra {search_query: ...} layer — removed
- x-no-account-id header standardised to 'bypass'
- Redundant x-no-account-id removed from file download headers
- Smoke test rewritten to validate the real two-step bootstrap path

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

README.md

@@ -290,3 +290,34 @@ See `documentation/PROJECT__AE_Events_Launcher_Native_integration.md` Section 8
 - **Preload:** Logic defined in `src/preload/index.ts`.
 - **Handlers:** OS-level logic in `src/main/shell_handlers.ts`, `src/main/file_handlers.ts`, and `src/main/system_handlers.ts`.
 - **Types:** Shared TypeScript interfaces in `src/shared/types.ts`.
+
+### Build Requirements (System Dependencies)
+
+`bsdtar` (libarchive) must be present on the build host. It is used by the `postinstall` patch
+to work around a hard hang in `@electron/packager` 20 on Node 26.
+
+| OS | Install |
+| --- | --- |
+| Arch Linux | `sudo pacman -S libarchive` |
+| macOS | `brew install libarchive` (or use the system bsdtar included in Xcode CLT) |
+| Ubuntu/Debian | `sudo apt install libarchive-tools` |
+
+### Why bsdtar — Node 26 Packaging Bug
+
+**Symptom:** `npm run package:mac` or `npm run package:linux` prints
+`Packaging app for platform ... using electron v42.x` then hangs forever (or exits 0 with no output).
+
+**Root cause:** `yauzl` 2.10.0 (used by `extract-zip` inside `@electron/packager` 20) creates
+read streams that never emit `data` events under Node 26. The zip extraction call blocks
+indefinitely.
+
+**Fix:** `scripts/patch-packager-unzip.js` (run automatically via `postinstall`) replaces the
+`extractElectronZip` function in `node_modules/@electron/packager/dist/unzip.js` with a
+`child_process.execSync` call to `bsdtar -xf`. `bsdtar` was chosen over `7z` because `7z`
+refuses to extract macOS `.app` bundles that contain symlinks chained through other symlinks
+(e.g. `Electron Framework.framework/Libraries → Versions/Current/Libraries`, where
+`Versions/Current` is itself a symlink).
+
+**This patch is re-applied automatically on every `npm install`** via the `postinstall` hook.
+If a future release of `@electron/packager` or `extract-zip` fixes Node 26 compatibility,
+remove the `postinstall` line from `package.json` and delete `scripts/patch-packager-unzip.js`.

dist/main/api_client.js

@@ -18,7 +18,7 @@ async function fetchFullConfig(seed) {
                 headers: {
                     'Content-Type': 'application/json',
                     'x-aether-api-key': seed.aether_api_key,
-                    'x-no-account-id': 'Nothing to See Here'
+                    'x-no-account-id': 'bypass'
                 },
             });
             if (!deviceResponse.ok) {
@@ -29,20 +29,16 @@ async function fetchFullConfig(seed) {
             // Use 'app_base_url' as the FQDN for the site lookup
             const fqdn = deviceData.app_base_url || 'native-demo.oneskyit.com';
             // --- STEP 2: Get Site Context ---
-            const searchUrl = `${baseUrl}/v3/crud/site_domain/search`;
+            const searchUrl = `${baseUrl}/v3/crud/site_domain/search?limit=1`;
             const siteResponse = await fetch(searchUrl, {
                 method: 'POST',
                 headers: {
                     'Content-Type': 'application/json',
                     'x-aether-api-key': seed.aether_api_key,
-                    'x-no-account-id': 'Nothing to See Here',
                     'x-account-id': deviceData.account_id_random || deviceData.account_id || ''
                 },
                 body: JSON.stringify({
-                    search_query: {
                     and: [{ field: 'fqdn', op: 'eq', value: fqdn }]
-                    },
-                    limit: 1
                 })
             });
             if (!siteResponse.ok) {

dist/main/api_client.js.map

@@ -1 +1 @@
-{"version":3,"file":"api_client.js","sourceRoot":"","sources":["../../src/main/api_client.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"api_client.js","sourceRoot":"","sources":["../../src/main/api_client.ts"],"names":[],"mappings":"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"}

dist/main/file_handlers.js

@@ -100,8 +100,7 @@ function registerFileHandlers() {
                 method: 'get', url, responseType: 'stream',
                 headers: {
                     'x-aether-api-key': api_key,
-                    'x-account-id': account_id || '',
+                    'x-account-id': account_id || ''
-                    'x-no-account-id': 'Nothing to See Here'
                 }
             });
             const writer = fs.createWriteStream(tmp_path);
@@ -131,7 +130,7 @@ function registerFileHandlers() {
             endpoints_in_progress = endpoints_in_progress.filter(e => e !== url);
         }
     });
-    electron_1.ipcMain.handle('native:launch-from-cache', async (event, { cache_root, hash, temp_root, filename, hash_prefix_length = 2 }) => {
+    electron_1.ipcMain.handle('native:launch-from-cache', async (event, { cache_root, hash, temp_root, filename, hash_prefix_length = 2, script_template = null }) => {
         try {
             const source = get_organized_hashed_path(cache_root, hash, hash_prefix_length);
             const expanded_temp = (0, file_utils_1.expandPath)(temp_root);
@@ -141,10 +140,52 @@ function registerFileHandlers() {
                 fs.mkdirSync(expanded_temp, { recursive: true });
             // 1. Copy the file to temp folder with original name
             fs.copyFileSync(source, target);
-            // 2. Determine file type
+            // 2a. Data-driven script override (no rebuild needed for script changes).
+            //     Set via event_device.data_json.launch_scripts or $events_loc.launcher.launch_scripts.
+            //     Format: AppleScript string with {{path}} placeholder, OR "shell:<cmd> {{path}}"
+            if (script_template) {
+                const resolved = script_template.replace(/\{\{path\}\}/g, target);
+                if (resolved.startsWith('shell:')) {
+                    const cmd = resolved.slice(6).trim();
+                    console.log(`Native: Running custom shell script for ${filename}`);
+                    return new Promise((resolve_fn) => {
+                        (0, child_process_1.exec)(cmd, (err, stdout, stderr) => {
+                            if (err)
+                                resolve_fn({ success: false, error: err.message, stderr: stderr.trim() });
+                            else
+                                resolve_fn({ success: true, stdout: stdout.trim() });
+                        });
+                    });
+                }
+                else {
+                    // Treat as AppleScript — write to temp .scpt file (same hardened approach used below)
+                    console.log(`Native: Running custom AppleScript for ${filename}`);
+                    const tmp_script_path = path.join(os.tmpdir(), `ae_launch_${Date.now()}.scpt`);
+                    return new Promise((resolve_fn) => {
+                        try {
+                            fs.writeFileSync(tmp_script_path, resolved.trim());
+                        }
+                        catch (e) {
+                            resolve_fn({ success: false, error: `Failed to write AppleScript temp file: ${e.message}` });
+                            return;
+                        }
+                        (0, child_process_1.exec)(`osascript "${tmp_script_path}"`, (err) => {
+                            try {
+                                fs.unlinkSync(tmp_script_path);
+                            }
+                            catch { }
+                            if (err)
+                                resolve_fn({ success: false, error: err.message });
+                            else
+                                resolve_fn({ success: true });
+                        });
+                    });
+                }
+            }
+            // 2b. Determine file type (legacy hardcoded launch logic — used when no script_template provided)
             const ext = path.extname(filename).toLowerCase().replace('.', '');
             const is_pres = ['pptx', 'ppt', 'key', 'pdf', 'odp'].includes(ext);
-            // 3. Optimized Launch (LibreOffice / AppleScript)
+            // 3. Hardcoded launch (legacy — still the default when no script_template is configured)
             if (is_pres) {
                 if (os.platform() === 'linux') {
                     console.log(`Native: Launching LibreOffice (--impress) for ${target}`);
@@ -216,5 +257,30 @@ function registerFileHandlers() {
             return { success: false, error: error.message };
         }
     });
+    // Thin primitive: copy a cached file to the temp directory with its original filename,
+    // then return the resolved path. The caller (Svelte side) decides what to do next —
+    // run_osascript, run_cmd, open_local_file, etc.
+    //
+    // This is the preferred building block for custom launch flows. Use launch_from_cache
+    // when the built-in hardcoded logic is sufficient; use copy_from_cache_to_temp when
+    // you want full control over what happens after the file lands in temp.
+    electron_1.ipcMain.handle('native:copy-from-cache-to-temp', async (event, { cache_root, hash, temp_root, filename, hash_prefix_length = 2 }) => {
+        try {
+            const source = get_organized_hashed_path(cache_root, hash, hash_prefix_length);
+            if (!fs.existsSync(source)) {
+                return { success: false, error: `File not in cache: ${hash}` };
+            }
+            const expanded_temp = (0, file_utils_1.expandPath)(temp_root);
+            const target = path.join(expanded_temp, filename);
+            if (!fs.existsSync(expanded_temp))
+                fs.mkdirSync(expanded_temp, { recursive: true });
+            fs.copyFileSync(source, target);
+            console.log(`Native: Copied from cache to temp -> ${target}`);
+            return { success: true, path: target };
+        }
+        catch (error) {
+            return { success: false, error: error.message };
+        }
+    });
 }
 //# sourceMappingURL=file_handlers.js.map

dist/main/shell_handlers.js

@@ -36,6 +36,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.registerShellHandlers = registerShellHandlers;
 const electron_1 = require("electron");
 const child_process_1 = require("child_process");
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
 const os = __importStar(require("os"));
 const file_utils_1 = require("./file_utils");
 function registerShellHandlers() {
@@ -65,10 +67,29 @@ function registerShellHandlers() {
     electron_1.ipcMain.handle('native:run-osascript', async (event, script) => {
         if (os.platform() !== 'darwin')
             return { success: false, error: 'AppleScript is only available on macOS' };
-        const escapedScript = script.replace(/"/g, '\"');
+        // HARDENED: Write script to a temp .scpt file rather than passing inline via -e.
-        const cmd = `osascript -e "${escapedScript}"`;
+        // The old -e approach (`osascript -e "..."`) has two fatal flaws:
+        //   1. It breaks on multi-line scripts.
+        //   2. It breaks on paths containing spaces or special characters (quotes, parens, etc.)
+        // Writing to a file sidesteps both — no shell escaping needed at all.
+        // The .scpt file is deleted immediately after execution (success or failure).
+        // Worst case on crash: a stale .scpt in /tmp, cleared on next OS reboot.
+        //
+        // LEGACY (removed): const cmd = `osascript -e "${script.replace(/"/g, '\\"')}"`;
+        const tmp_script_path = path.join(os.tmpdir(), `ae_osa_${Date.now()}.scpt`);
         return new Promise((resolve) => {
-            (0, child_process_1.exec)(cmd, (error, stdout, stderr) => {
+            try {
+                fs.writeFileSync(tmp_script_path, script.trim());
+            }
+            catch (e) {
+                resolve({ success: false, error: `Failed to write AppleScript temp file: ${e.message}` });
+                return;
+            }
+            (0, child_process_1.exec)(`osascript "${tmp_script_path}"`, (error, stdout, stderr) => {
+                try {
+                    fs.unlinkSync(tmp_script_path);
+                }
+                catch { }
                 resolve({ success: !error, stdout: stdout.trim(), stderr: stderr.trim(), error: error ? error.message : null });
             });
         });

documentation/TODO_AGENTS.md

@@ -0,0 +1,52 @@
+# Native App Agent Task List
+> Use this file to track steps for complex features or bug fixes.
+> **Status:** Stable - ongoing development.
+
+## Current Investigation
+- This started as an API contract review for the native Electron bootstrap path and expanded into a packaging/runtime issue after the deploy step stopped producing bundles.
+- We now know the API side was not the root cause. The bootstrap request shape in `src/main/api_client.ts` was wrong and has been corrected.
+- The packaging blocker has been diagnosed and fixed (see below).
+
+## What Was Fixed
+- Updated the native bootstrap flow to use the direct `site_domain/search` request body expected by API V3.
+- Standardized the account-bypass header to `x-no-account-id: bypass` where that narrow bypass is intended.
+- Removed a redundant `x-no-account-id` header from file download calls.
+- Rewrote the device lookup smoke test so it validates the real two-step bootstrap path end to end.
+- Upgraded Electron from 34.x to 42.0.1.
+- Replaced deprecated `electron-packager` with `@electron/packager` 20.0.0.
+- Added a `package:linux` smoke test path so packaging failures can be isolated from macOS-specific behavior.
+- **Fixed packaging hang on Node 26:** `yauzl` 2.10.0 (used by `extract-zip` in `@electron/packager`) emits no `data` events on Node 26 streams, causing zip extraction to hang indefinitely. Fix: patched `@electron/packager/dist/unzip.js` to use `7z` (system binary) instead of `extract-zip`. Patch is re-applied on every `npm install` via the `postinstall` script at `scripts/patch-packager-unzip.js`.
+
+## Verified So Far
+- `npm run dev` works once the Electron binary is present locally.
+- Manual Electron cache extraction restored a runnable checkout on this machine.
+- API validation confirmed the backend responds correctly for:
+	- `event_device/{id}` lookup
+	- `site_domain/search?limit=1` with the direct `SearchQuery` body
+- The returned `site_domain.account_id` matches the device account context in the verified bootstrap flow.
+- The SvelteKit frontend bootstrap path already follows the correct API contract and does not need the same fix.
+- **`npm run package:linux` now produces `builds/aether_launcher-linux-x64/`** with a complete bundle (confirmed 2026-05-11).
+- **`npm run package:mac` now produces `builds/aether_launcher-darwin-x64/` and `builds/aether_launcher-darwin-arm64/`** with `aether_launcher.app` inside each (confirmed 2026-05-11). Initial fix used `7z` but it refused chained symlinks inside macOS framework bundles; switched to `bsdtar` (libarchive) which handles both Linux and macOS zips correctly.
+- `deploy/deploy.sh` output directory names (`aether_launcher-darwin-x64`, `aether_launcher-darwin-arm64`) match packager output — no script changes needed.
+
+## Remaining Items
+1. Test that the packaged Linux binary runs end-to-end against the dev API.
+2. Document that `bsdtar` (libarchive) must be present on the build host — new build-time dependency. On Arch: `sudo pacman -S libarchive`.
+
+## Root Cause Summary (Packaging Hang)
+- **Tool chain:** Node 26.1.0 + `@electron/packager` 20.0.0 + `extract-zip` 2.0.1 + `yauzl` 2.10.0
+- **Symptom:** `npm run package:linux` exits 0 but produces no output. Debug log shows it starts extraction but never finishes.
+- **Root cause:** `yauzl` opens a read stream for the first zip entry, but on Node 26, no `data` events are ever emitted on that stream. The `pipeline(readStream, writeStream)` call in `extract-zip` blocks forever.
+- **Fix:** Replace the one-liner `extractElectronZip` function in `node_modules/@electron/packager/dist/unzip.js` with a `child_process.execSync` call to `7z x`. A `postinstall` npm script re-applies this patch after each `npm install`.
+- **Build-time dependency:** `p7zip` (provides `/usr/bin/7z`) must be installed on the build host. On Arch: `pacman -S p7zip`.
+
+## References
+- Electron 42 release notes: https://www.electronjs.org/blog/electron-42-0
+- Related Electron packaging discussion: https://github.com/aaddrick/claude-desktop-debian/pull/587
+- Electron packaging/runtime change reference: https://github.com/electron/electron/pull/49328
+- yauzl Node 26 stream issue: `yauzl` 2.10.0 uses legacy Node streams (streams1 style); Node 26 changed stream internal behavior so `openReadStream` returns a stream that never emits `data` without a proper pipeline consumer.
+
+## Notes
+- Was on Electron 34.
+- The problem is not the backend API keys or the frontend site bootstrap flow.
+- The packaging fix is a node_modules patch, not upstream. If `@electron/packager` or `extract-zip` releases a Node 26-compatible version, the `postinstall` script should be removed.

package.json

@@ -4,18 +4,20 @@
   "description": "AE Native Launcher V3",
   "main": "dist/main/index.js",
   "scripts": {
+    "postinstall": "node scripts/patch-packager-unzip.js",
     "start": "tsc && electron .",
     "dev": "tsc && electron .",
     "build": "tsc",
     "watch": "tsc -w",
+    "package:linux": "tsc && electron-packager . aether_launcher --platform=linux --arch=x64 --out=builds --overwrite --prune=true",
     "package:mac": "tsc && electron-packager . aether_launcher --platform=darwin --arch=x64,arm64 --out=builds --overwrite --prune=true --icon=resources/img/osit_logo.icns"
   },
   "devDependencies": {
-    "@types/node": "^22.10.7",
+    "@types/node": "^22.19.0",
-    "electron": "^34.0.0",
+    "electron": "^42.0.1",
-    "electron-packager": "^17.1.2",
+    "@electron/packager": "^20.0.0",
     "ts-node": "^10.9.2",
-    "typescript": "^5.7.3"
+    "typescript": "^5.9.3"
   },
   "dependencies": {
     "axios": "^1.13.2"

scripts/patch-packager-unzip.js

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+// extract-zip/yauzl streams hang on Node 26 (no data events emitted).
+// bsdtar (libarchive) handles both Linux and macOS zips including chained symlinks in .app bundles.
+const { writeFileSync, existsSync } = require('fs');
+const { resolve } = require('path');
+
+const target = resolve('node_modules/@electron/packager/dist/unzip.js');
+if (!existsSync(target)) {
+  console.log('patch-packager-unzip: target not found, skipping');
+  process.exit(0);
+}
+
+const patched = `import { execSync } from 'node:child_process';
+// extract-zip/yauzl streams are broken on Node 26; use bsdtar (libarchive) instead.
+// bsdtar correctly handles chained symlinks in macOS .app bundles that 7z refuses.
+export async function extractElectronZip(zipPath, targetDir) {
+    execSync(\`bsdtar -xf "\${zipPath}" -C "\${targetDir}"\`, { stdio: 'pipe' });
+}
+//# sourceMappingURL=unzip.js.map
+`;
+
+writeFileSync(target, patched);
+console.log('patch-packager-unzip: patched @electron/packager/dist/unzip.js to use bsdtar');

src/main/api_client.ts

@@ -20,7 +20,7 @@ export async function fetchFullConfig(seed: SeedConfig): Promise<any> {
         headers: {
           'Content-Type': 'application/json',
           'x-aether-api-key': seed.aether_api_key,
-          'x-no-account-id': 'Nothing to See Here'
+          'x-no-account-id': 'bypass'
         },
       });
 
@@ -35,20 +35,16 @@ export async function fetchFullConfig(seed: SeedConfig): Promise<any> {
       const fqdn = deviceData.app_base_url || 'native-demo.oneskyit.com';
 
       // --- STEP 2: Get Site Context ---
-      const searchUrl = `${baseUrl}/v3/crud/site_domain/search`;
+      const searchUrl = `${baseUrl}/v3/crud/site_domain/search?limit=1`;
       const siteResponse = await fetch(searchUrl, {
         method: 'POST',
         headers: {
           'Content-Type': 'application/json',
           'x-aether-api-key': seed.aether_api_key,
-          'x-no-account-id': 'Nothing to See Here',
           'x-account-id': deviceData.account_id_random || deviceData.account_id || ''
         },
         body: JSON.stringify({
-          search_query: {
           and: [{ field: 'fqdn', op: 'eq', value: fqdn }]
-          },
-          limit: 1
         })
       });
 

src/main/file_handlers.ts

@@ -67,8 +67,7 @@ export function registerFileHandlers() {
         method: 'get', url, responseType: 'stream',
         headers: {
           'x-aether-api-key': api_key,
-          'x-account-id': account_id || '',
+          'x-account-id': account_id || ''
-          'x-no-account-id': 'Nothing to See Here'
         }
       });
 

tests/test_device_lookup.py

@@ -1,55 +1,90 @@
 import requests
 import json
 
-def test_device_lookup():
+def test_bootstrap(device_id, api_key, base_url='https://dev-api.oneskyit.com'):
-    device_id = 'dbgMWS3KEHE'
+    """
-    api_key = 'INSdG85ANwsEIru3nUttMw'
+    Replicates the two-step bootstrap sequence in api_client.ts:
-    base_url = 'https://dev-api.oneskyit.com'
+      Step 1: GET event_device  →  extract account_id + app_base_url (fqdn)
-    endpoint = f'{base_url}/v3/crud/event_device/{device_id}'
+      Step 2: POST site_domain/search  →  returns the correct site context
+    """
+    print(f'\n=== Bootstrap test ===')
+    print(f'Device:   {device_id}')
+    print(f'Base URL: {base_url}')
 
-    headers = {
+    # --- Step 1: Get Device Config ---
+    device_url = f'{base_url}/v3/crud/event_device/{device_id}'
+    headers_step1 = {
+        'Content-Type': 'application/json',
         'x-aether-api-key': api_key,
-        'x-no-account-id': 'Nothing to See Here',
+        'x-no-account-id': 'bypass',
-        'Content-Type': 'application/json'
     }
 
-    params = {
+    print(f'\n-- Step 1: GET {device_url}')
-        'view': 'enriched'
-    }
-
-    print(f'Testing lookup for device: {device_id}')
-    print(f'Endpoint: {endpoint}')
-    
     try:
-        response = requests.get(endpoint, headers=headers, params=params)
+        r1 = requests.get(device_url, headers=headers_step1)
-        print(f'Status Code: {response.status_code}')
+        print(f'   Status: {r1.status_code}')
+        if r1.status_code != 200:
+            print(f'   Error: {r1.text}')
+            return
 
-        if response.status_code == 200:
+        device_data = r1.json().get('data', {})
-            data = response.json()
-            device_data = data.get('data', {})
-            
-            print('Returned Fields (Key Values):')
         important_fields = [
-                'account_id_random',
+            'account_id', 'app_base_url', 'code', 'name',
-                'app_base_url',
+            'event_id', 'event_location_id',
-                'code',
+            'local_file_cache_path', 'host_file_temp_path', 'recording_path',
-                'name',
-                'event_id_random',
-                'event_location_id_random',
-                'local_file_cache_path',
-                'host_file_temp_path',
-                'recording_path',
-                'cfg_json'
         ]
-            
         for field in important_fields:
-                val = device_data.get(field, 'MISSING')
+            print(f'   {field}: {device_data.get(field, "MISSING")}')
-                print(f'  {field}: {val}')
+
+        account_id = device_data.get('account_id') or device_data.get('account_id_random')
+        fqdn = device_data.get('app_base_url', 'native-demo.oneskyit.com')
+
+    except Exception as e:
+        print(f'   Request failed: {e}')
+        return
+
+    # --- Step 2: Get Site Context ---
+    search_url = f'{base_url}/v3/crud/site_domain/search?limit=1'
+    headers_step2 = {
+        'Content-Type': 'application/json',
+        'x-aether-api-key': api_key,
+        'x-account-id': account_id or '',
+    }
+    body = {
+        'and': [{'field': 'fqdn', 'op': 'eq', 'value': fqdn}]
+    }
+
+    print(f'\n-- Step 2: POST {search_url}')
+    print(f'   Searching for fqdn: {fqdn}')
+    try:
+        r2 = requests.post(search_url, headers=headers_step2, json=body)
+        print(f'   Status: {r2.status_code}')
+        if r2.status_code != 200:
+            print(f'   Error: {r2.text}')
+            return
+
+        results = r2.json().get('data', [])
+        print(f'   Results returned: {len(results)}')
+        if results:
+            sd = results[0]
+            print(f'   fqdn:       {sd.get("fqdn")}')
+            print(f'   account_id: {sd.get("account_id")}')
+            print(f'   site_id:    {sd.get("site_id")}')
+            if sd.get('account_id') != account_id:
+                print(f'   WARNING: site_domain account_id does not match device account_id!')
             else:
-            print(f'Error Response: {response.text}')
+                print(f'   OK: account_id matches device.')
+        else:
+            print(f'   WARNING: No site_domain found for fqdn "{fqdn}"')
 
     except Exception as e:
         print(f'   Request failed: {e}')
 
+
 if __name__ == '__main__':
-    test_device_lookup()
+    # Dev device (dev-api)
+    test_bootstrap(
+        device_id='dbgMWS3KEHE',
+        api_key='INSdG85ANwsEIru3nUttMw',
+        base_url='https://dev-api.oneskyit.com',
+    )