@xenon-device-management/xenon 2.13.2 → 2.15.0

package/lib/src/data-service/web-config-service.js

@@ -18,109 +18,67 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.WebConfigService = void 0;
 const prisma_1 = require("../prisma");
 const typedi_1 = require("typedi");
+/** How each saved setting is read back: they are all stored as text. */
+const SETTINGS = {
+    enableSelfHealing: 'boolean',
+    healthCheckIntervalMs: 'number',
+    healthCheckSchedule: 'text',
+    buildCleanupDays: 'number',
+    buildCleanupMaxCount: 'number',
+    buildCleanupSchedule: 'text',
+    deleteBuildAssets: 'boolean',
+    aiProvider: 'text',
+    aiModel: 'text',
+    aiBaseUrl: 'text',
+    geminiModel: 'text',
+    openaiModel: 'text',
+    anthropicModel: 'text',
+    ollamaModel: 'text',
+};
+/**
+ * The lab settings the dashboard saves, one `WebConfig` row each, keyed by the
+ * setting's name.
+ *
+ * A row's `id` is the table's primary key, and used to be written as 'global'
+ * for every setting, so the table held one: the first setting saved was kept,
+ * and saving a second failed with "Unique constraint failed on the fields
+ * (`id`)". A setting's row now has its own name as its id, as the metrics
+ * counters kept in the same table do. A row an earlier version saved under
+ * 'global' is still read, and still the one the next save of that setting
+ * updates.
+ */
 let WebConfigService = class WebConfigService {
-    constructor() {
-        this.CONFIG_ID = 'global';
-    }
     getConfig() {
         return __awaiter(this, void 0, void 0, function* () {
-            const configs = yield prisma_1.prisma.webConfig.findMany({
-                where: { id: this.CONFIG_ID },
+            const rows = yield prisma_1.prisma.webConfig.findMany({
+                where: { name: { in: Object.keys(SETTINGS) } },
             });
             const result = {};
-            for (const config of configs) {
-                if (config.name === 'healthCheckIntervalMs') {
-                    result.healthCheckIntervalMs = parseInt(config.value);
-                }
-                else if (config.name === 'healthCheckSchedule') {
-                    result.healthCheckSchedule = config.value;
-                }
-                else if (config.name === 'buildCleanupDays') {
-                    result.buildCleanupDays = parseInt(config.value);
-                }
-                else if (config.name === 'buildCleanupMaxCount') {
-                    result.buildCleanupMaxCount = parseInt(config.value);
-                }
-                else if (config.name === 'buildCleanupSchedule') {
-                    result.buildCleanupSchedule = config.value;
-                }
-                else if (config.name === 'deleteBuildAssets') {
-                    result.deleteBuildAssets = config.value === 'true';
-                }
+            for (const row of rows) {
+                const kind = SETTINGS[row.name];
+                if (kind === 'number')
+                    result[row.name] = parseInt(row.value);
+                else if (kind === 'boolean')
+                    result[row.name] = row.value === 'true';
+                else if (kind === 'text')
+                    result[row.name] = row.value;
             }
             return result;
         });
     }
     setConfig(config) {
         return __awaiter(this, void 0, void 0, function* () {
-            const promises = [];
-            if (config.healthCheckIntervalMs !== undefined) {
-                promises.push(prisma_1.prisma.webConfig.upsert({
-                    where: { name: 'healthCheckIntervalMs' },
-                    update: { value: config.healthCheckIntervalMs.toString() },
-                    create: {
-                        id: this.CONFIG_ID,
-                        name: 'healthCheckIntervalMs',
-                        value: config.healthCheckIntervalMs.toString(),
-                    },
-                }));
-            }
-            if (config.healthCheckSchedule !== undefined) {
-                promises.push(prisma_1.prisma.webConfig.upsert({
-                    where: { name: 'healthCheckSchedule' },
-                    update: { value: config.healthCheckSchedule },
-                    create: {
-                        id: this.CONFIG_ID,
-                        name: 'healthCheckSchedule',
-                        value: config.healthCheckSchedule,
-                    },
-                }));
-            }
-            if (config.buildCleanupDays !== undefined) {
-                promises.push(prisma_1.prisma.webConfig.upsert({
-                    where: { name: 'buildCleanupDays' },
-                    update: { value: config.buildCleanupDays.toString() },
-                    create: {
-                        id: this.CONFIG_ID,
-                        name: 'buildCleanupDays',
-                        value: config.buildCleanupDays.toString(),
-                    },
-                }));
-            }
-            if (config.buildCleanupMaxCount !== undefined) {
-                promises.push(prisma_1.prisma.webConfig.upsert({
-                    where: { name: 'buildCleanupMaxCount' },
-                    update: { value: config.buildCleanupMaxCount.toString() },
-                    create: {
-                        id: this.CONFIG_ID,
-                        name: 'buildCleanupMaxCount',
-                        value: config.buildCleanupMaxCount.toString(),
-                    },
-                }));
-            }
-            if (config.buildCleanupSchedule !== undefined) {
-                promises.push(prisma_1.prisma.webConfig.upsert({
-                    where: { name: 'buildCleanupSchedule' },
-                    update: { value: config.buildCleanupSchedule },
-                    create: {
-                        id: this.CONFIG_ID,
-                        name: 'buildCleanupSchedule',
-                        value: config.buildCleanupSchedule,
-                    },
-                }));
-            }
-            if (config.deleteBuildAssets !== undefined) {
-                promises.push(prisma_1.prisma.webConfig.upsert({
-                    where: { name: 'deleteBuildAssets' },
-                    update: { value: config.deleteBuildAssets.toString() },
-                    create: {
-                        id: this.CONFIG_ID,
-                        name: 'deleteBuildAssets',
-                        value: config.deleteBuildAssets.toString(),
-                    },
-                }));
-            }
-            yield Promise.all(promises);
+            const writes = Object.keys(SETTINGS)
+                .filter((name) => config[name] !== undefined && config[name] !== null)
+                .map((name) => {
+                const value = String(config[name]);
+                return prisma_1.prisma.webConfig.upsert({
+                    where: { name },
+                    update: { value },
+                    create: { id: name, name, value },
+                });
+            });
+            yield Promise.all(writes);
         });
     }
 };

package/lib/src/device-managers/AndroidDeviceManager.js

@@ -77,6 +77,7 @@ const device_service_1 = require("../data-service/device-service");
 const device_store_1 = require("../data-service/device-store");
 const Devices_1 = __importDefault(require("./cloud/Devices"));
 const DeviceLockManager_1 = require("./android/DeviceLockManager");
+const shellCommands_1 = require("./shellCommands");
 const androidIdentity_1 = require("./android/androidIdentity");
 const deviceIdentity_1 = require("./deviceIdentity");
 const localDeviceHosts_1 = require("./localDeviceHosts");
@@ -1151,43 +1152,20 @@ let AndroidDeviceManager = class AndroidDeviceManager {
     }
     executeShell(udid, command) {
         return __awaiter(this, void 0, void 0, function* () {
-            const ALLOWED_COMMANDS = [
-                'ls',
-                'ps',
-                'top',
-                'dumpsys battery',
-                'dumpsys wifi',
-                'dumpsys power',
-                'whoami',
-                'getprop',
-                'pm list packages',
-                'ip addr',
-                'cat /proc/meminfo',
-                'cat /proc/cpuinfo',
-                'date',
-                'uptime',
-                'netstat',
-            ];
-            // Basic sanitation
-            const safeCommand = command.trim();
-            // Check if the command starts with any allowed prefix
-            const isAllowed = ALLOWED_COMMANDS.some((prefix) => safeCommand.startsWith(prefix));
-            if (!isAllowed) {
-                logger_1.default.warn(`Blocked potentially unsafe shell command on ${udid}: ${safeCommand}`);
-                throw new Error(`Command '${safeCommand}' is not allowed for security reasons.`);
+            // An allowed command word for word, in words `sh` reads nothing into:
+            // `adb shell` hands the joined line to the phone's shell (shellCommands.ts).
+            const parsed = (0, shellCommands_1.parseShellCommand)(command, shellCommands_1.ANDROID_SHELL_COMMANDS);
+            if ('refused' in parsed) {
+                logger_1.default.warn(`Blocked shell command on ${udid}: ${command.trim()}`);
+                throw new Error(parsed.refused);
             }
-            // Split command into args for adbExec
-            // This is a naive split, but safe enough for the allowed commands which don't use complex quoting
-            const args = safeCommand.split(/\s+/);
-            logger_1.default.info(`Executing shell command on ${udid}: ${safeCommand}`);
+            logger_1.default.info(`Executing shell command on ${udid}: ${parsed.argv.join(' ')}`);
             const { adbInstance } = yield this.getAdb();
             if (!adbInstance)
                 throw new Error('ADB is not available');
             // Use device lock to ensure thread safety
             return yield DeviceLockManager_1.deviceLock.acquire(udid, () => __awaiter(this, void 0, void 0, function* () {
-                // Direct raw shell execution might be better for piping, but adbExec is safer as it escapes args
-                // except we passed them as array, so standard child_process rules apply.
-                return yield adbInstance.adbExec(['-s', udid, 'shell', ...args], { timeout: 10000 });
+                return yield adbInstance.adbExec(['-s', udid, 'shell', ...parsed.argv], { timeout: 10000 });
             }));
         });
     }

package/lib/src/device-managers/android/AndroidH264StreamService.js

@@ -93,27 +93,34 @@ let AndroidH264StreamService = class AndroidH264StreamService {
     startWatchdog() {
         // unref()ed below: the server's listener keeps the process alive; this only
         // needs to fire while it runs.
-        setInterval(() => {
-            const now = Date.now();
-            for (const [udid, s] of this.sessions.entries()) {
-                if (s.status !== 'running')
-                    continue;
-                if (s.mux.clientCount > 0) {
-                    s.emptyAt = undefined;
-                }
-                else if (s.emptyAt === undefined) {
-                    s.emptyAt = now;
-                }
-                else if (now - s.emptyAt > IDLE_TIMEOUT_MS) {
-                    logger_1.default.info(`[${udid}] Stopping idle H.264 stream (no viewers for ${IDLE_TIMEOUT_MS}ms)`);
-                    // The stream went, but the live-preview hold stayed: with H.264
-                    // preview, a tab closed without releasing kept the device busy for
-                    // good. stop() itself must not release (a recording starting calls
-                    // it); an idle stop does, if nothing else uses the device.
-                    void this.stop(udid).then(() => (0, previewHold_1.releaseIdlePreviewHold)(udid));
-                }
+        setInterval(() => this.sweep(Date.now()), 60000).unref();
+    }
+    /** One look at every capture: ends those nobody has watched for long enough. */
+    sweep(now) {
+        for (const [udid, s] of this.sessions.entries()) {
+            if (s.status !== 'running')
+                continue;
+            if (s.mux.clientCount > 0) {
+                s.emptyAt = undefined;
+            }
+            else if (s.endWhenUnwatched && !this.startPromises.has(udid)) {
+                // A page asked for MJPEG while this capture was starting for a viewer
+                // who then never came (endWhenUnwatched leaves a start alone).
+                logger_1.default.info(`[${udid}] Stopping the unwatched H.264 stream: the phone is shown as MJPEG`);
+                void this.stop(udid);
             }
-        }, 60000).unref();
+            else if (s.emptyAt === undefined) {
+                s.emptyAt = now;
+            }
+            else if (now - s.emptyAt > IDLE_TIMEOUT_MS) {
+                logger_1.default.info(`[${udid}] Stopping idle H.264 stream (no viewers for ${IDLE_TIMEOUT_MS}ms)`);
+                // The stream went, but the live-preview hold stayed: with H.264
+                // preview, a tab closed without releasing kept the device busy for
+                // good. stop() itself must not release (a recording starting calls
+                // it); an idle stop does, if nothing else uses the device.
+                void this.stop(udid).then(() => (0, previewHold_1.releaseIdlePreviewHold)(udid));
+            }
+        }
     }
     getMultiplexer(udid) {
         var _a;
@@ -131,6 +138,7 @@ let AndroidH264StreamService = class AndroidH264StreamService {
                 var _a, _b;
                 const mux = new H264Multiplexer_1.H264Multiplexer();
                 const session = { status: 'running', mux };
+                mux.onEmpty(() => this.endIfUnwatched(udid, session));
                 this.sessions.set(udid, session);
                 try {
                     let resolveConfig = () => undefined;
@@ -178,6 +186,44 @@ let AndroidH264StreamService = class AndroidH264StreamService {
             }
         });
     }
+    /**
+     * A page that showed this phone's H.264 preview now shows MJPEG (its player
+     * failed, or it cannot play H.264), and the MJPEG capture is starting for
+     * it. One capture per phone where possible, but never at the expense of a
+     * viewer still playing H.264: another tile, tab or admin may be. So the
+     * capture ends now if nobody watches it, else the moment its last viewer
+     * leaves, never after the idle wait. A viewer who joins meanwhile is served
+     * and ends it in turn. A capture still starting is left to the viewer it is
+     * starting for, and the watchdog ends it if that viewer never comes.
+     */
+    endWhenUnwatched(udid) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const session = this.sessions.get(udid);
+            if (!session || session.status !== 'running')
+                return;
+            session.endWhenUnwatched = true;
+            const viewers = session.mux.clientCount;
+            if (viewers > 0) {
+                logger_1.default.info(`[${udid}] H.264 stream kept beside MJPEG for its ${viewers} viewer(s); ` +
+                    'it ends when the last one leaves');
+                return;
+            }
+            if (this.startPromises.has(udid)) {
+                logger_1.default.info(`[${udid}] H.264 stream still starting: kept for the viewer it is starting for`);
+                return;
+            }
+            logger_1.default.info(`[${udid}] Stopping the unwatched H.264 stream: the phone is shown as MJPEG`);
+            yield this.stop(udid);
+        });
+    }
+    /** The last viewer left `session`: end it if a page asked (endWhenUnwatched). */
+    endIfUnwatched(udid, session) {
+        // A capture replaced since (a stop and a new start) is not this one.
+        if (this.sessions.get(udid) !== session || !session.endWhenUnwatched)
+            return;
+        logger_1.default.info(`[${udid}] Stopping the H.264 stream: its last viewer left, the phone is shown as MJPEG`);
+        void this.stop(udid);
+    }
     stop(udid) {
         return __awaiter(this, void 0, void 0, function* () {
             var _a;
@@ -192,6 +238,9 @@ let AndroidH264StreamService = class AndroidH264StreamService {
                 /* best-effort */
             }
             this.sessions.delete(udid);
+            // Viewers still on it (a recording starting, a stream/stop) are told, so
+            // their players fall back to MJPEG instead of freezing on the last frame.
+            session.mux.close();
             logger_1.default.info(`[${udid}] H.264 stream terminated.`);
         });
     }

package/lib/src/device-managers/android/H264Multiplexer.js

@@ -9,6 +9,7 @@ class H264Multiplexer {
     constructor() {
         this.clients = new Set();
         this.gop = []; // current GOP: [keyframe, ...deltas-since]
+        this.closed = false;
     }
     setConfig(p) {
         this.config = p;
@@ -16,9 +17,21 @@ class H264Multiplexer {
     get clientCount() {
         return this.clients.size;
     }
-    /** Register a client sink. Returns a remover. */
-    addClient(send) {
-        const c = { send, started: false };
+    /** Called each time the last client leaves. */
+    onEmpty(listener) {
+        this.emptyListener = listener;
+    }
+    /**
+     * Register a client sink, and how to end it when the stream does (see
+     * `close`). Returns a remover (safe to call twice).
+     */
+    addClient(send, end) {
+        const c = { send, started: false, end };
+        if (this.closed) {
+            // Joined a stream already stopped: end it now rather than starve it.
+            end === null || end === void 0 ? void 0 : end();
+            return () => undefined;
+        }
         this.clients.add(c);
         if (this.config)
             send(this.config);
@@ -29,9 +42,30 @@ class H264Multiplexer {
             c.started = true;
         }
         return () => {
-            this.clients.delete(c);
+            var _a;
+            if (this.clients.delete(c) && this.clients.size === 0)
+                (_a = this.emptyListener) === null || _a === void 0 ? void 0 : _a.call(this);
         };
     }
+    /**
+     * The capture stopped: end every client (its socket closes, so its player
+     * falls back to MJPEG instead of freezing on its last frame). Not an
+     * `onEmpty`: nobody left, the stream did.
+     */
+    close() {
+        var _a;
+        this.closed = true;
+        const ending = [...this.clients];
+        this.clients.clear();
+        for (const c of ending) {
+            try {
+                (_a = c.end) === null || _a === void 0 ? void 0 : _a.call(c);
+            }
+            catch (_b) {
+                /* one client's end must not keep the others open */
+            }
+        }
+    }
     /** Feed one upstream packet; fans out per the join semantics above. */
     push(p) {
         if (p.type === 'config') {

package/lib/src/device-managers/ios/WDAClient.js

@@ -27,6 +27,7 @@ const typedi_1 = require("typedi");
 const ProcessRegistry_1 = require("../../services/ProcessRegistry");
 const IOSStreamService_1 = __importDefault(require("./IOSStreamService"));
 const IOSTunnels_1 = require("./IOSTunnels");
+const shellCommands_1 = require("../shellCommands");
 const device_store_1 = require("../../data-service/device-store");
 const child_process_1 = require("child_process");
 const util_1 = require("util");
@@ -1005,57 +1006,57 @@ let WDAClient = WDAClient_1 = class WDAClient {
     }
     executeShell(udid, command) {
         return __awaiter(this, void 0, void 0, function* () {
-            // Separate allowlists for simulators vs real devices
-            const SIMCTL_COMMANDS = ['listapps', 'get_app_container', 'list', 'getenv'];
-            const GOIOS_COMMANDS = ['apps', 'info', 'syslog', 'list', 'deviceinfo', 'diagnostics'];
-            const GENERIC_COMMANDS = ['ls', 'ps', 'top', 'whoami', 'date', 'uptime', 'netstat', 'id'];
-            const safeCommand = command.trim();
-            const commandWord = safeCommand.split(/\s+/)[0]; // First word is the command
-            // Determine device type
+            // Simulators: a few simctl commands, and generic commands spawned in the
+            // simulator. Real iPhones: go-ios commands for this phone only. Every
+            // command is matched word for word, in plain words (shellCommands.ts).
             const device = yield device_store_1.DeviceStoreFactory.getStore().findDevice({ udid });
-            const isSimulator = device && !device.realDevice;
-            // Check allowlists based on device type
-            const isSimctlAllowed = SIMCTL_COMMANDS.includes(commandWord);
-            const isGoiosAllowed = GOIOS_COMMANDS.includes(commandWord);
-            const isGenericAllowed = GENERIC_COMMANDS.some((prefix) => safeCommand.startsWith(prefix));
-            if (!isSimctlAllowed && !isGoiosAllowed && !isGenericAllowed) {
-                this.log.warn(`Blocked shell command on ${udid}: ${safeCommand}`);
-                throw new Error(`Command '${safeCommand}' is not allowed for security reasons.`);
-            }
-            const args = safeCommand.split(/\s+/);
-            const s = typedi_1.Container.get(IOSStreamService_1.default);
-            // Route to the correct tool
-            if (isSimctlAllowed && isSimulator) {
-                // Simulator-specific: xcrun simctl <command> <udid> [args...]
-                const [cmd, ...rest] = args;
-                const { stdout } = yield execFilePromise('xcrun', ['simctl', cmd, udid, ...rest]);
-                return stdout;
-            }
-            if (isGoiosAllowed) {
-                // Real device: go-ios <command> --udid <udid> [args...]
-                if (yield s.isGoIOSAvailable()) {
-                    const { stdout } = yield execFilePromise(s.goIOSPath, [...args, '--udid', udid], {
-                        env: Object.assign(Object.assign({}, process.env), { ENABLE_GO_IOS_AGENT: 'yes' }),
+            const isSimulator = !!device && !device.realDevice;
+            const word = command.trim().split(/\s+/)[0];
+            const refuse = (reason) => {
+                this.log.warn(`Blocked shell command on ${udid}: ${command.trim()}`);
+                return new Error(reason);
+            };
+            if (isSimulator) {
+                const simctl = (0, shellCommands_1.parseShellCommand)(command, shellCommands_1.IOS_SIMCTL_COMMANDS);
+                if ('argv' in simctl) {
+                    const [cmd, ...rest] = simctl.argv;
+                    const { stdout } = yield execFilePromise('xcrun', ['simctl', cmd, udid, ...rest], {
+                        timeout: 10000,
                     });
                     return stdout;
                 }
-                throw new Error(`Command '${commandWord}' requires go-ios but it is not available.`);
+                const spawned = (0, shellCommands_1.parseShellCommand)(command, shellCommands_1.IOS_SPAWN_COMMANDS);
+                if ('refused' in spawned)
+                    throw refuse(spawned.refused);
+                const { stdout } = yield execFilePromise('xcrun', ['simctl', 'spawn', udid, ...spawned.argv], {
+                    timeout: 10000,
+                });
+                return stdout;
             }
-            if (isSimctlAllowed && !isSimulator) {
-                // User tried a simctl command on a real device - give helpful error
-                throw new Error(`Command '${commandWord}' is only available for Simulators. For real devices, try: ${GOIOS_COMMANDS.join(', ')}`);
+            const onDevice = (0, shellCommands_1.parseShellCommand)(command, shellCommands_1.IOS_DEVICE_COMMANDS);
+            if ('refused' in onDevice) {
+                const simulatorOnly = [...shellCommands_1.IOS_SIMCTL_COMMANDS, ...shellCommands_1.IOS_SPAWN_COMMANDS].some((c) => c.words[0] === word);
+                if (simulatorOnly) {
+                    throw refuse(`'${word}' runs on simulators only. On a real iPhone, try: ${shellCommands_1.IOS_DEVICE_COMMANDS.map((c) => c.words.join(' ')).join(', ')}.`);
+                }
+                throw refuse(onDevice.refused);
             }
-            // Generic system command - try simctl first, fallback to go-ios
-            if (isSimulator) {
-                const { stdout } = yield execFilePromise('xcrun', ['simctl', 'spawn', udid, ...args]);
-                return stdout;
+            // Xenon names the phone; a command may not name another one.
+            if (onDevice.argv.some((arg) => arg.startsWith('--udid'))) {
+                throw refuse(`Command '${command.trim()}' is not allowed: Xenon chooses the device.`);
             }
-            else if (yield s.isGoIOSAvailable()) {
-                // For real devices, generic commands aren't directly possible via go-ios
-                // Try go-ios launch/exec if available, otherwise inform user
-                throw new Error(`System command '${commandWord}' is not available on real devices. Use device-specific commands: ${GOIOS_COMMANDS.join(', ')}`);
+            const s = typedi_1.Container.get(IOSStreamService_1.default);
+            if (!(yield s.isGoIOSAvailable())) {
+                throw new Error(`'${word}' needs go-ios, which is not installed on this server.`);
             }
-            throw new Error(`Could not execute command: no suitable runtime found for ${isSimulator ? 'simulator' : 'real device'}`);
+            // On iOS 17+ go-ios reaches the phone only through its tunnel.
+            const tunnels = typedi_1.Container.get(IOSTunnels_1.IOSTunnels);
+            yield tunnels.borrow(udid);
+            const { stdout } = yield execFilePromise(s.goIOSPath, [...onDevice.argv, '--udid', udid], {
+                env: tunnels.envFor(udid),
+                timeout: 10000,
+            });
+            return stdout;
         });
     }
 };

package/lib/src/device-managers/shellCommands.js

@@ -0,0 +1,96 @@
+"use strict";
+/**
+ * What the device control Shell tab may run.
+ *
+ * Android runs a command through `adb shell`, which joins the words and hands
+ * them to the phone's `sh`. Through 2.13.2 the allow-list was a `startsWith`
+ * test on the whole line, so `ls; reboot`, `ls && pm uninstall …` and `lsof`
+ * all ran. Now a command must begin with an allowed command word for word, and
+ * every word of it may only use characters a shell gives no meaning to, so the
+ * phone's shell can't read anything into it. A command that changes or reads
+ * more than the entry is for (`dumpsys battery set …`, `cat` of another file)
+ * takes no arguments.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IOS_DEVICE_COMMANDS = exports.IOS_SIMULATOR_COMMANDS = exports.IOS_SPAWN_COMMANDS = exports.IOS_SIMCTL_COMMANDS = exports.ANDROID_SHELL_COMMANDS = void 0;
+exports.parseShellCommand = parseShellCommand;
+/** Letters, digits and `._/:=@%+,-`: nothing `sh` expands, splits or redirects on. */
+const PLAIN_WORD = /^[A-Za-z0-9._/:=@%+,-]+$/;
+exports.ANDROID_SHELL_COMMANDS = [
+    { words: ['ls'], args: 'plain' },
+    { words: ['ps'], args: 'plain' },
+    { words: ['top'], args: 'plain' },
+    { words: ['dumpsys', 'battery'], args: 'none' },
+    { words: ['dumpsys', 'wifi'], args: 'none' },
+    { words: ['dumpsys', 'power'], args: 'none' },
+    { words: ['whoami'], args: 'none' },
+    { words: ['getprop'], args: 'plain' },
+    { words: ['pm', 'list', 'packages'], args: 'plain' },
+    { words: ['ip', 'addr'], args: 'plain' },
+    { words: ['cat', '/proc/meminfo'], args: 'none' },
+    { words: ['cat', '/proc/cpuinfo'], args: 'none' },
+    { words: ['date'], args: 'plain' },
+    { words: ['uptime'], args: 'none' },
+    { words: ['netstat'], args: 'plain' },
+];
+/** `xcrun simctl <command> <udid> [args]` on a simulator. */
+exports.IOS_SIMCTL_COMMANDS = [
+    { words: ['listapps'], args: 'none' },
+    { words: ['get_app_container'], args: 'plain' },
+    { words: ['getenv'], args: 'plain' },
+];
+/**
+ * `xcrun simctl spawn <udid> <command>` on a simulator. A simulator's processes
+ * see this Mac's file system, so these take no arguments.
+ */
+exports.IOS_SPAWN_COMMANDS = [
+    { words: ['ls'], args: 'none' },
+    { words: ['ps'], args: 'none' },
+    { words: ['whoami'], args: 'none' },
+    { words: ['date'], args: 'none' },
+    { words: ['uptime'], args: 'none' },
+    { words: ['id'], args: 'none' },
+];
+exports.IOS_SIMULATOR_COMMANDS = [
+    ...exports.IOS_SIMCTL_COMMANDS,
+    ...exports.IOS_SPAWN_COMMANDS,
+];
+/**
+ * go-ios commands on a real iPhone (`ios <command> [args] --udid <udid>`). None
+ * may name a device itself: Xenon adds this phone's `--udid`.
+ */
+exports.IOS_DEVICE_COMMANDS = [
+    { words: ['apps'], args: 'plain' },
+    { words: ['info'], args: 'none' },
+];
+/**
+ * The command's argv when it is allowed, or why it isn't. Words are split on
+ * spaces; quoting is not supported, since a quote is refused anyway.
+ */
+function parseShellCommand(input, commands) {
+    const shown = input.trim();
+    // Words are separated by spaces only: a newline or tab means another line.
+    if (/[^\S ]/.test(shown)) {
+        return {
+            refused: `Command '${shown.split(/\s/)[0]}…' is not allowed: one line, words separated by spaces.`,
+        };
+    }
+    const argv = shown.split(/ +/).filter(Boolean);
+    if (argv.length === 0)
+        return { refused: 'Type a command.' };
+    const bad = argv.find((word) => !PLAIN_WORD.test(word));
+    if (bad !== undefined) {
+        return {
+            refused: `Command '${shown}' is not allowed: '${bad}' contains characters the shell would interpret.`,
+        };
+    }
+    const match = commands.find((command) => command.words.length <= argv.length && command.words.every((word, i) => argv[i] === word));
+    if (!match)
+        return { refused: `Command '${shown}' is not allowed for security reasons.` };
+    if (match.args === 'none' && argv.length > match.words.length) {
+        return {
+            refused: `Command '${shown}' is not allowed: '${match.words.join(' ')}' takes no arguments here.`,
+        };
+    }
+    return { argv };
+}