@mobileaidev/ai-app-bridge 0.2.15 → 0.3.0-rc.2

package/bin/ios-runtime-binding.js

@@ -0,0 +1,54 @@
+'use strict';
+
+const { CommandError } = require('./command-errors');
+const { currentExecution } = require('./shared-kernel/execution-scope');
+
+const schemaVersion = 'aab.ios-runtime/v1';
+const sdkCommands = new Set(['ios-status', 'ios-tree', 'ios-logs', 'ios-network', 'ios-state', 'ios-events',
+  'ios-h5-dom', 'ios-h5-eval', 'ios-h5-click', 'ios-h5-input', 'ios-h5-scroll', 'ios-flutter-tree', 'ios-flutter-nodes', 'ios-flutter-action',
+  'ios-tap-flutter', 'ios-input-flutter-text', 'ios-scroll-flutter', 'ios-flutter-back', 'ios-flutter-hide-keyboard']);
+const fields = ['schemaVersion', 'bundleId', 'runtimeEpoch', 'processId', 'port'];
+
+function bindingFailure(code, message) {
+  const dispatched = currentExecution()?.dispatched === true;
+  return new CommandError(code, message, { dispatched, ambiguous: dispatched });
+}
+
+function runtimeBinding(value, minimumPort = 1) {
+  if (!value || value.schemaVersion !== schemaVersion || typeof value.bundleId !== 'string'
+    || !/^[A-Za-z0-9_.-]{1,255}$/.test(value.bundleId)
+    || typeof value.runtimeEpoch !== 'string' || !/^[A-Za-z0-9_-]{1,128}$/.test(value.runtimeEpoch)
+    || !Number.isSafeInteger(value.processId) || value.processId < 1
+    || !Number.isInteger(value.port) || value.port < minimumPort || value.port > 65535) {
+    throw bindingFailure('invalid_ios_runtime_binding', `Expected a ${schemaVersion} identity with bundleId, runtimeEpoch, processId and port.`);
+  }
+  return Object.freeze(Object.fromEntries(fields.map(field => [field, value[field]])));
+}
+
+function descriptorBinding(value, bundleId) {
+  const binding = runtimeBinding(value, value?.ok === false ? 0 : 1);
+  if (value.ok !== true) throw bindingFailure('ios_runtime_not_ready',
+    `The selected App has not published a ready runtime descriptor${typeof value.error === 'string' ? `: ${value.error}` : '.'}`);
+  if (binding.bundleId !== bundleId) throw bindingFailure('ios_runtime_binding_mismatch', 'The App container descriptor does not match the requested bundleId.');
+  return binding;
+}
+
+function bindingHeaders(binding) {
+  return {
+    'X-AAB-Runtime-Schema': binding.schemaVersion,
+    'X-AAB-Bundle-Id': binding.bundleId,
+    'X-AAB-Runtime-Epoch': binding.runtimeEpoch,
+    'X-AAB-Process-Id': String(binding.processId),
+    'X-AAB-Runtime-Port': String(binding.port),
+  };
+}
+
+function assertRuntimeResponse(response, expected) {
+  const actual = runtimeBinding(response?.runtimeBinding);
+  if (fields.some(field => actual[field] !== expected[field])) {
+    throw bindingFailure('ios_runtime_binding_mismatch', 'The HTTP endpoint does not match the runtime copied from the selected device and App.');
+  }
+  if (typeof response.ok !== 'boolean') throw bindingFailure('invalid_ios_runtime_response', 'The bound runtime response must declare ok as a boolean.');
+}
+
+module.exports = { sdkCommands, descriptorBinding, bindingHeaders, assertRuntimeResponse, bindingFailure };

package/bin/ios-wda-execution.js

@@ -0,0 +1,70 @@
+'use strict';
+
+const { randomUUID } = require('node:crypto');
+const { isDeepStrictEqual } = require('node:util');
+const managed = require('./shared-kernel/managed-sdk-execution');
+const { runDeviceEffect } = require('./shared-kernel/device-mutation-lease');
+const { runExecution } = require('./shared-kernel/execution-scope');
+const { iosDeviceKey, lookupCompletion } = require('./ios-execution');
+
+const schema = 'aab.wda-execution/v1';
+function proof(result, identity, target) {
+  const terminal = managed.terminalReceipt(schema, result, identity) ? result : result?.cancellation?.executionResult;
+  if (terminal && !isDeepStrictEqual(terminal.execution?.target, target)) return null;
+  return managed.settlementProof('ios-wda', schema, result, identity);
+}
+function completionPort(port) { return { get: route => port.request('GET', route, null) }; }
+
+async function executeWDAAction({ port, args, operation, selected, payload = {} }) {
+  const identity = { actionId: args.runtimeActionId ?? args.requestId ?? randomUUID(), runtimeEpoch: port.runtimeBinding.runtimeEpoch };
+  const target = { ...selected, runnerBundleId: port.runtimeBinding.bundleId, operation };
+  const connection = { deviceId: port.device.udid, wdaRunnerBundleId: args.wdaRunnerBundleId,
+    ...Object.fromEntries(['wdaUrl', 'devicectl'].filter(key => args[key] !== undefined).map(key => [key, args[key]])) };
+  return runDeviceEffect({ kind: 'ios-wda', ...identity, target: connection, executionTarget: target }, async () => {
+    const result = await managed.executeManagedAction({ kind: 'wda', schema,
+      runtime: { runtimeEpoch: identity.runtimeEpoch, executionSchema: port.status.executionSchema },
+      payload: { operation, target: selected, payload }, actionId: identity.actionId, timeoutMs: args.timeoutMs ?? 30000,
+      send: async request => {
+        const reply = await port.request('POST', '/aab/action', request, selected);
+        if (managed.terminalReceipt(schema, reply, identity) && !isDeepStrictEqual(reply.execution.target, target)) {
+          return { ok: false, error: 'ios_wda_completion_target_mismatch', settled: false, dispatched: null, ambiguous: true };
+        }
+        return reply;
+      },
+      cancel: original => runExecution({ timeoutMs: 4000 }, async () => {
+        const cancelled = await port.request('POST', '/aab/execution/cancel', original);
+        if (cancelled.ok !== true) return cancelled;
+        const found = await lookupCompletion(completionPort(port), 'wda', original, cancelled);
+        if (found.executionResult && !isDeepStrictEqual(found.executionResult.execution?.target, target))
+          return { ok: false, error: 'ios_wda_completion_target_mismatch', settled: false };
+        return found;
+      }),
+    });
+    return { ...result, executionReceipt: proof(result, identity, target) };
+  }, result => result.executionReceipt);
+}
+
+async function reconcileWDA({ lease, device, args, createPort }) {
+  return lease.reconcile(iosDeviceKey(device), async pending => {
+    if (pending.kind !== 'ios-wda' || pending.target?.deviceId !== device.udid
+      || pending.target?.wdaRunnerBundleId !== args.wdaRunnerBundleId
+      || pending.executionTarget?.runnerBundleId !== args.wdaRunnerBundleId
+      || typeof pending.actionId !== 'string' || typeof pending.runtimeEpoch !== 'string')
+      return { settled: false, error: 'ios_wda_original_identity_required' };
+    const identity = { actionId: pending.actionId, runtimeEpoch: pending.runtimeEpoch };
+    try {
+      const target = { ...pending.target, timeoutMs: args.timeoutMs ?? 30000 };
+      for (const key of ['wdaUrl', 'devicectl']) if (args[key] !== undefined) target[key] = args[key];
+      const port = await createPort(target);
+      const found = await lookupCompletion(completionPort(port), 'wda', identity);
+      if (found.ok !== true || found.receipt?.committed !== true
+          || !Number.isSafeInteger(found.receipt.sequence) || found.receipt.sequence < 1
+          || !/^[a-f0-9]{64}$/.test(found.receipt.sha256))
+        return { settled: false, error: found.error || 'ios_wda_durable_completion_required' };
+      return proof(found.executionResult, identity, pending.executionTarget)
+        || { settled: false, error: 'ios_wda_completion_target_mismatch' };
+    } catch (error) { return { settled: false, error: error.code || 'ios_wda_completion_query_failed', message: error.message }; }
+  });
+}
+
+module.exports = { executeWDAAction, reconcileWDA, completionPort };

package/bin/ios-wda-port.js

@@ -0,0 +1,98 @@
+'use strict';
+
+const { CommandError } = require('./command-errors');
+const { currentExecution, checkExecution } = require('./shared-kernel/execution-scope');
+
+const fields = ['schemaVersion', 'bundleId', 'runtimeEpoch', 'processId', 'port'];
+const schemaVersion = 'aab.ios-wda/v1';
+const commands = new Set(['ios-wda-status', 'ios-wda-session', 'ios-uia-tree', 'ios-tap', 'ios-input', 'ios-swipe', 'ios-set-orientation', 'ios-tap-native', 'ios-input-native-text']);
+
+function fail(code, message, details) {
+  const dispatched = currentExecution()?.dispatched === true;
+  return new CommandError(code, message, { dispatched, ambiguous: dispatched, ...(details ? { details } : {}) });
+}
+
+function binding(value) {
+  if (value?.schemaVersion !== schemaVersion || typeof value?.bundleId !== 'string' || !/^[A-Za-z0-9_.-]{1,255}$/.test(value.bundleId)
+    || typeof value?.runtimeEpoch !== 'string' || !/^[A-Za-z0-9_-]{1,128}$/.test(value.runtimeEpoch) || !Number.isSafeInteger(value?.processId)
+    || value.processId < 1 || !Number.isInteger(value?.port) || value.port < 1 || value.port > 65535) {
+    throw fail('invalid_ios_wda_binding', `Expected ${schemaVersion} Runner identity.`);
+  }
+  return Object.freeze(Object.fromEntries(fields.map(key => [key, value[key]])));
+}
+
+function target(value, session = false) {
+  if (typeof value?.bundleId !== 'string' || !value.bundleId || !Number.isSafeInteger(value?.processId) || value.processId < 1
+    || (session && (typeof value.sessionId !== 'string' || !value.sessionId))) throw fail('invalid_ios_wda_target', 'WDA must identify the exact foreground App process and session.');
+  return Object.freeze({ bundleId: value.bundleId, processId: value.processId, ...(session ? { sessionId: value.sessionId } : {}) });
+}
+
+async function openWdaPort(provider, args, device) {
+  if (!args.deviceId || !args.wdaRunnerBundleId) throw fail('ios_wda_target_required', 'WDA requires deviceId and the actual wdaRunnerBundleId from ios-setup.');
+  device ??= await provider.requireDevice(args);
+  if (![device.identifier, device.udid].includes(args.deviceId) || device.developerModeStatus !== 'enabled'
+    || device.ddiServicesAvailable !== true || device.tunnelState !== 'connected') throw fail('ios_tunnel_unavailable', 'The selected WDA device must have a connected developer tunnel.');
+  const descriptor = await provider.readContainerDescriptor(args, device, args.wdaRunnerBundleId, 'ai_app_bridge_wda.json');
+  const runtime = binding(descriptor);
+  if (descriptor.ok !== true || runtime.bundleId !== args.wdaRunnerBundleId) throw fail('ios_wda_binding_mismatch', 'The selected Runner container has no matching ready WDA descriptor.');
+  let url;
+  try {
+    const host = device.tunnelIPAddress;
+    if (!args.wdaUrl && !host) throw new Error('No developer tunnel IP');
+    url = new URL(args.wdaUrl ?? `http://${host.includes(':') ? `[${host}]` : host}:${runtime.port}`);
+    if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password || url.search || url.hash) throw new Error('Invalid WDA URL');
+  } catch (error) { throw fail('invalid_ios_wda_url', error.message); }
+  const baseUrl = url.href.replace(/\/$/, '');
+  const headers = { 'X-AAB-WDA-Schema': runtime.schemaVersion, 'X-AAB-WDA-Bundle-Id': runtime.bundleId,
+    'X-AAB-WDA-Runtime-Epoch': runtime.runtimeEpoch, 'X-AAB-WDA-Process-Id': String(runtime.processId), 'X-AAB-WDA-Port': String(runtime.port) };
+  let completedMutation = false;
+  async function request(method, route, body, selected, mutation = method !== 'GET') {
+    const boundHeaders = { ...headers, ...(selected ? { 'X-AAB-WDA-Target-Bundle-Id': selected.bundleId,
+      'X-AAB-WDA-Target-Process-Id': String(selected.processId), ...(selected.sessionId ? { 'X-AAB-WDA-Session-Id': selected.sessionId } : {}) } : {}) };
+    let response;
+    // A managed event's response arrives from its original XCTest completion.
+    // Its wait must use the admitted action budget, not the shorter read budget.
+    const timeoutMs = route === '/aab/action' ? body.execution.timeoutMs : args.timeoutMs ?? 5000;
+    try { response = await provider.httpRequest(method, `${baseUrl}${route}`, body, { headers: boundHeaders, timeoutMs, mutation }); }
+    catch (error) {
+      if (!error.response) throw error;
+      response = error.response;
+    }
+    const actual = binding(response?.wdaBinding);
+    if (fields.some(key => actual[key] !== runtime[key])) throw fail('ios_wda_binding_mismatch', 'WDA response does not belong to the Runner instance read from the selected device.');
+    if (!Object.hasOwn(response, 'value')) throw fail('invalid_ios_wda_response', 'WDA response is missing its value.');
+    if (route === '/aab/status' || route === '/aab/action' || route.startsWith('/aab/execution/')) {
+      if (typeof response.value?.ok === 'boolean') {
+        checkExecution();
+        return response.value;
+      }
+    }
+    const error = response.value?.error;
+    if (error !== undefined) {
+      if (typeof error !== 'string' || !error) throw fail('invalid_ios_wda_response', 'WDA error must be a nonempty string.');
+      const rejected = /^ios_wda_|^invalid_ios_wda_/.test(error) && response.value.dispatched === false && response.value.ambiguous === false;
+      throw new CommandError(rejected ? error : 'ios_wda_command_failed', response.value.message || error,
+        { dispatched: rejected ? completedMutation : currentExecution()?.dispatched === true,
+          ambiguous: rejected ? false : currentExecution()?.dispatched === true, details: { wdaError: error, response } });
+    }
+    checkExecution();
+    if (mutation) completedMutation = true;
+    return response.value;
+  }
+  async function session(required = true) {
+    const status = await request('GET', '/aab/session', null);
+    if (!status || !Object.hasOwn(status, 'session')) throw fail('invalid_ios_wda_session', 'WDA did not return session state.');
+    if (!required) return status;
+    if (status.session === null) throw fail('ios_wda_session_required', 'Create a session with ios-wda-session before reading or acting.');
+    const selected = target(status.session, true);
+    if (selected.bundleId !== args.bundleId || selected.sessionId !== args.wdaSessionId) throw fail('ios_wda_session_changed', 'The requested App/session does not match the bound WDA session.');
+    return selected;
+  }
+  // An old unmodified WDA cannot ignore the binding headers and receive a write.
+  const status = await request('GET', '/aab/status', null);
+  if (status?.ok !== true || status.ready !== true || status.executionSchema !== 'aab.wda-execution/v1')
+    throw fail('ios_wda_not_ready', 'The selected WDA Runner must expose a ready managed execution store.');
+  return { device, baseUrl, runtimeBinding: runtime, request, session, status };
+}
+
+module.exports = { commands, openWdaPort, binding, target };

package/bin/ios-wda-project.js

@@ -0,0 +1,79 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { createHash } = require('node:crypto');
+const { CommandError } = require('./command-errors');
+
+const supportedVersion = '14.1.1';
+const directories = ['Configurations', 'PrivateHeaders', 'Scripts', 'WebDriverAgentLib', 'WebDriverAgentRunner', 'WebDriverAgentTests', 'WebDriverAgent.xcodeproj'];
+
+function wdaBuildEnvironment(environment = process.env) {
+  const result = { ...environment };
+  // A device build must use Xcode's selected SDK, never injected macOS
+  // header/library search paths from the Host shell.
+  for (const name of ['CPATH', 'C_INCLUDE_PATH', 'CPLUS_INCLUDE_PATH', 'OBJC_INCLUDE_PATH', 'LIBRARY_PATH', 'SDKROOT']) delete result[name];
+  return result;
+}
+
+function replaceOnce(source, before, after, file) {
+  if (source.split(before).length !== 2) throw new CommandError('ios_wda_source_mismatch', `The pinned WDA integration point changed: ${file}.`);
+  return source.replace(before, after);
+}
+
+function prepareWdaProject({ destination, packageDirectory = path.dirname(require.resolve('appium-webdriveragent/package.json')) }) {
+  const manifest = JSON.parse(fs.readFileSync(path.join(packageDirectory, 'package.json'), 'utf8'));
+  if (manifest.version !== supportedVersion) throw new CommandError('ios_wda_version_unsupported', `The prepared WDA runtime requires appium-webdriveragent ${supportedVersion}.`);
+  fs.mkdirSync(destination, { recursive: true });
+  if (fs.readdirSync(destination).length) throw new CommandError('ios_wda_destination_not_empty', 'WDA preparation requires an empty destination.');
+  for (const name of directories) fs.cpSync(path.join(packageDirectory, name), path.join(destination, name), { recursive: true });
+  fs.copyFileSync(path.join(packageDirectory, 'LICENSE'), path.join(destination, 'LICENSE.upstream'));
+  const sourceRoot = path.join(__dirname, '..', 'runtime', 'ios-wda');
+  for (const name of ['AABWDABinding.h', 'AABWDABinding.m', 'AABWDAIntegration.h', 'AABWDAManagedRoutes.h',
+    'AABWDAReceiptStore.h', 'AABWDAReceiptStore.m', 'AABWDAExecution.h', 'AABWDAExecution.m']) {
+    fs.copyFileSync(path.join(sourceRoot, name), path.join(destination, 'WebDriverAgentLib', 'Routing', name));
+  }
+  const nativeRoot = path.dirname(require.resolve('@mobileaidev/segmented-fact-store-native/package.json'));
+  const nativeCore = { version: JSON.parse(fs.readFileSync(path.join(nativeRoot, 'package.json'))).version, files: [] };
+  for (const relative of ['include/sfs.h', 'src/sfs.c']) {
+    const bytes = fs.readFileSync(path.join(nativeRoot, relative));
+    fs.writeFileSync(path.join(destination, 'WebDriverAgentLib', 'Routing', path.basename(relative)), bytes);
+    nativeCore.files.push({ path: relative, sha256: createHash('sha256').update(bytes).digest('hex') });
+  }
+  const transformations = [];
+  function patch(relative, edits) {
+    const filename = path.join(destination, relative);
+    const original = fs.readFileSync(filename, 'utf8');
+    let content = original;
+    for (const [before, after] of edits) content = replaceOnce(content, before, after, relative);
+    fs.writeFileSync(filename, content);
+    const digest = value => createHash('sha256').update(value).digest('hex');
+    transformations.push({ path: relative, beforeSha256: digest(original), afterSha256: digest(content) });
+  }
+  patch('WebDriverAgentLib/Routing/FBWebServer.m', [
+    ['#import "XCUIDevice+FBHelpers.h"', '#import "XCUIDevice+FBHelpers.h"\n#import "AABWDAIntegration.h"'],
+    ['[self.server setRouteQueue:dispatch_get_main_queue()];', '[self.server setRouteQueue:nil];'],
+    ['  [self registerRouteHandlers:[self.class collectCommandHandlerClasses]];', '  AABWDARegisterControl(self.server);\n  [self registerRouteHandlers:[self.class collectCommandHandlerClasses]];'],
+    ['  NSString *serverHost = bindingIP', '  NSError *bindingError;\n  if (![AABWDABinding.shared publishPort:self.server.port error:&bindingError]) {\n    [FBLogger logFmt:@"AAB WDA descriptor publication failed: %@", bindingError];\n  }\n\n  NSString *serverHost = bindingIP'],
+    ['        NSDictionary *arguments = [NSJSONSerialization JSONObjectWithData:request.body',
+      '        dispatch_sync(dispatch_get_main_queue(), ^{\n        NSString *admissionError = AABWDAAdmission(route, request.headers, request.params, request.body);\n        if (admissionError) { [AABWDAReject(admissionError) dispatchWithResponse:response]; return; }\n        NSDictionary *arguments = [NSJSONSerialization JSONObjectWithData:request.body'],
+    ['          [strongSelf handleException:exception forResponse:response];\n        }\n      }];',
+      '          [strongSelf handleException:exception forResponse:response];\n        }\n        });\n      }];'],
+    ['    [response respondWithString:@"Shutting down"];\n    [strongSelf.delegate webServerDidRequestShutdown:strongSelf];',
+      '    [AABWDAReject(@"ios_wda_route_unsupported") dispatchWithResponse:response];'],
+  ]);
+  patch('WebDriverAgentLib/Routing/FBResponsePayload.m', [
+    ['#import "FBResponsePayload.h"', '#import "FBResponsePayload.h"\n#import "AABWDABinding.h"'],
+    ['  response[@"sessionId"] = [FBSession activeSession].identifier ?: NSNull.null;', '  response[@"wdaBinding"] = AABWDABinding.shared.identity;\n  response[@"sessionId"] = [FBSession activeSession].identifier ?: NSNull.null;'],
+  ]);
+  patch('WebDriverAgentLib/Categories/XCUIApplication+FBHelpers.m', [
+    ['\n  info[@"rawIdentifier"] = FBValueOrNull([snapshot.identifier isEqual:@""] ? nil : snapshot.identifier);',
+      '\n  info[@"rawIdentifier"] = FBValueOrNull([snapshot.identifier isEqual:@""] ? nil : snapshot.identifier);\n  info[@"elementId"] = FBValueOrNull([FBXCElementSnapshotWrapper ensureWrapped:snapshot].wdUID);'],
+  ]);
+  const result = { schemaVersion: 'aab.ios-wda-project/v1', upstreamVersion: supportedVersion,
+    projectPath: path.join(destination, 'WebDriverAgent.xcodeproj'), transformations, nativeCore };
+  fs.writeFileSync(path.join(destination, 'aab-wda-project.json'), JSON.stringify(result, null, 2) + '\n');
+  return result;
+}
+
+module.exports = { supportedVersion, prepareWdaProject, wdaBuildEnvironment };