feat: support Maestro setPermissions

Author: Rohit3523

packages/maestro/src/internal/__tests__/program-ir-parser.test.ts

@@ -409,6 +409,63 @@ describe('parseMaestroProgram', () => {
     });
   });
 
+  test('parses setPermissions maps, variables, and optional/label', () => {
+    const program = parseMaestroProgram(`appId: example.app
+---
+- setPermissions:
+    permissions:
+      all: deny
+      notifications: unset
+- setPermissions:
+    appId: child.app
+    permissions:
+      camera: \${CAMERA_STATE}
+      location: always
+    optional: true
+    label: Prepare scan
+`);
+
+    assert.deepEqual(program.commands[0], {
+      kind: 'setPermissions',
+      source: { line: 3 },
+      permissions: { all: 'deny', notifications: 'unset' },
+    });
+    assert.deepEqual(program.commands[1], {
+      kind: 'setPermissions',
+      source: { line: 7 },
+      appId: 'child.app',
+      permissions: { camera: '${CAMERA_STATE}', location: 'always' },
+      optional: true,
+      label: 'Prepare scan',
+    });
+    assert.throws(
+      () =>
+        parseMaestroProgram(`---
+- setPermissions:
+    appId: example.app
+`),
+      /requires permissions.*line 2/i,
+    );
+    assert.throws(
+      () =>
+        parseMaestroProgram(`---
+- setPermissions:
+    permissions:
+      camera: sometimes
+`),
+      /allow\|deny\|unset.*line 4/i,
+    );
+    assert.throws(
+      () =>
+        parseMaestroProgram(`---
+- setPermissions:
+    permissions:
+      camera: \${ALLOW + 1}
+`),
+      /not supported.*line 4/i,
+    );
+  });
+
   test('reports source lines for unsupported and invalid command shapes', () => {
     assert.throws(
       () =>

packages/maestro/src/internal/__tests__/runtime-port-fixtures.ts

@@ -59,6 +59,7 @@ export function makeOperations(
     resolveGestureViewport: async () => ({ x: 0, y: 0, width: 402, height: 874 }),
     launchApp: noOp,
     stopApp: noOp,
+    setPermissions: noOp,
     openLink: noOp,
     tapOn: noOp,
     doubleTapOn: noOp,

packages/maestro/src/internal/__tests__/runtime-port.test.ts

@@ -10,6 +10,40 @@ import {
 } from './runtime-port-fixtures.ts';
 
 describe('MaestroRuntimePort', () => {
+  test('dispatches setPermissions with the flow appId and resolved values', async () => {
+    const calls: RecordedCall[] = [];
+    const operations = makeOperations({
+      setPermissions: vi.fn(async (input, context) =>
+        record(calls, 'setPermissions', input, context),
+      ),
+    });
+    const program = parseMaestroProgram(
+      [
+        'appId: com.example.checkout',
+        'env:',
+        '  CAMERA_STATE: allow',
+        '---',
+        '- setPermissions:',
+        '    permissions:',
+        '      all: deny',
+        '      camera: ${CAMERA_STATE}',
+      ].join('\n'),
+    );
+
+    const result = await executeMaestroProgram(program, createMaestroRuntimePort(operations));
+
+    expect(result).toMatchObject({ executed: 1, skipped: 0 });
+    expect(calls).toHaveLength(1);
+    expect(calls[0]).toMatchObject({
+      kind: 'setPermissions',
+      input: {
+        appId: 'com.example.checkout',
+        permissions: { all: 'deny', camera: 'allow' },
+      },
+      appId: 'com.example.checkout',
+    });
+  });
+
   test('delegates typed lifecycle, input, keyboard, screenshot, and script operations', async () => {
     const calls: RecordedCall[] = [];
     const operations = makeOperations({

packages/maestro/src/internal/conformance-normalize.ts

@@ -77,6 +77,7 @@ export type CanonicalCommand =
   | { kind: 'takeScreenshot' }
   | { kind: 'waitForAnimationToEnd'; timeout?: number | string }
   | { kind: 'stopApp' }
+  | { kind: 'setPermissions'; appId?: string; permissions?: Record<string, string> }
   | { kind: 'repeat'; times: string | number }
   | { kind: 'retry'; maxRetries?: string | number }
   | { kind: 'runFlow'; label?: string; source: 'file' | 'commands' }
@@ -98,7 +99,19 @@ export function canonicalizeUpstreamFlow(commands: UpstreamCommand[]): Canonical
     .map(canonicalizeUpstreamCommand);
 }
 
+/** Upstream commands that canonicalize to a bare kind with no fields. */
+const BARE_UPSTREAM_CANONICAL: Record<string, CanonicalCommand> = {
+  ScrollCommand: { kind: 'scroll' },
+  BackPressCommand: { kind: 'back' },
+  HideKeyboardCommand: { kind: 'hideKeyboard' },
+  TakeScreenshotCommand: { kind: 'takeScreenshot' },
+  StopAppCommand: { kind: 'stopApp' },
+  RunScriptCommand: { kind: 'runScript' },
+};
+
 function canonicalizeUpstreamCommand(command: UpstreamCommand): CanonicalCommand {
+  const bare = BARE_UPSTREAM_CANONICAL[command.type];
+  if (bare) return bare;
   const f = command.fields;
   switch (command.type) {
     case 'LaunchAppCommand':
@@ -164,8 +177,6 @@ function canonicalizeUpstreamCommand(command: UpstreamCommand): CanonicalCommand
     }
     case 'SwipeCommand':
       return dropUndefined({ kind: 'swipe', label: str(f.label), gesture: upstreamGesture(f) });
-    case 'ScrollCommand':
-      return { kind: 'scroll' };
     case 'ScrollUntilVisibleCommand':
       return dropUndefined({
         kind: 'scrollUntilVisible',
@@ -185,19 +196,17 @@ function canonicalizeUpstreamCommand(command: UpstreamCommand): CanonicalCommand
       return dropUndefined({ kind: 'openLink', link: str(f.link) });
     case 'PressKeyCommand':
       return { kind: 'pressKey', key: lower(str(f.code)) ?? '' };
-    case 'BackPressCommand':
-      return { kind: 'back' };
-    case 'HideKeyboardCommand':
-      return { kind: 'hideKeyboard' };
-    case 'TakeScreenshotCommand':
-      return { kind: 'takeScreenshot' };
     case 'WaitForAnimationToEndCommand':
       return dropUndefined({
         kind: 'waitForAnimationToEnd',
         timeout: numLike(f.timeout) ?? str(f.timeout),
       });
-    case 'StopAppCommand':
-      return { kind: 'stopApp' };
+    case 'SetPermissionsCommand':
+      return dropUndefined({
+        kind: 'setPermissions',
+        appId: str(f.appId),
+        permissions: permissionsRecord(f.permissions),
+      });
     case 'RepeatCommand':
       return { kind: 'repeat', times: numLike(f.times) ?? str(f.times) ?? '' };
     case 'RetryCommand':
@@ -211,8 +220,6 @@ function canonicalizeUpstreamCommand(command: UpstreamCommand): CanonicalCommand
         label: str(f.label),
         source: f.sourceDescription != null ? 'file' : 'commands',
       });
-    case 'RunScriptCommand':
-      return { kind: 'runScript' };
     default:
       return { kind: 'unsupported', command: unsupportedName(command.type) };
   }
@@ -286,6 +293,18 @@ function lower(value: string | undefined): string | undefined {
   return value?.toLowerCase();
 }
 
+function permissionsRecord(value: unknown): Record<string, string> | undefined {
+  const record = asRecord(value);
+  if (!record) return undefined;
+  const permissions: Record<string, string> = {};
+  for (const [key, entry] of Object.entries(record)) {
+    const coerced = str(entry)?.toLowerCase();
+    if (coerced === undefined) return undefined;
+    permissions[key] = coerced;
+  }
+  return permissions;
+}
+
 // ---------------------------------------------------------------------------
 // agent-device engine IR → canonical
 // ---------------------------------------------------------------------------
@@ -302,10 +321,27 @@ export function canonicalizeAgentCommands(
   return program.commands.map((command) => canonicalizeAgentCommand(command, program.config));
 }
 
+/** Agent commands that canonicalize to a bare kind with no fields. */
+const BARE_AGENT_CANONICAL = {
+  scroll: { kind: 'scroll' },
+  back: { kind: 'back' },
+  hideKeyboard: { kind: 'hideKeyboard' },
+  takeScreenshot: { kind: 'takeScreenshot' },
+  stopApp: { kind: 'stopApp' },
+  runScript: { kind: 'runScript' },
+} satisfies Record<string, CanonicalCommand>;
+
+type BareAgentCommand = Extract<MaestroCommand, { kind: keyof typeof BARE_AGENT_CANONICAL }>;
+
+function isBareAgentCommand(command: MaestroCommand): command is BareAgentCommand {
+  return command.kind in BARE_AGENT_CANONICAL;
+}
+
 function canonicalizeAgentCommand(
   command: MaestroCommand,
   config: MaestroProgram['config'],
 ): CanonicalCommand {
+  if (isBareAgentCommand(command)) return BARE_AGENT_CANONICAL[command.kind];
   switch (command.kind) {
     case 'launchApp':
       return dropUndefined({
@@ -384,8 +420,6 @@ function canonicalizeAgentCommand(
       return dropUndefined({ kind: 'eraseText', count: numLike(command.charactersToErase) });
     case 'openLink':
       return dropUndefined({ kind: 'openLink', link: command.link });
-    case 'scroll':
-      return { kind: 'scroll' };
     case 'scrollUntilVisible':
       // Upstream materializes the DOWN default onto the command at parse time;
       // our engine defers it to execution (runtime-port-commands.ts). Materialize
@@ -400,16 +434,14 @@ function canonicalizeAgentCommand(
       });
     case 'pressKey':
       return { kind: 'pressKey', key: command.key.toLowerCase() };
-    case 'back':
-      return { kind: 'back' };
-    case 'hideKeyboard':
-      return { kind: 'hideKeyboard' };
-    case 'takeScreenshot':
-      return { kind: 'takeScreenshot' };
     case 'waitForAnimationToEnd':
       return dropUndefined({ kind: 'waitForAnimationToEnd', timeout: numLike(command.timeout) });
-    case 'stopApp':
-      return { kind: 'stopApp' };
+    case 'setPermissions':
+      return dropUndefined({
+        kind: 'setPermissions',
+        appId: command.appId ?? config.appId,
+        permissions: command.permissions,
+      });
     case 'repeat':
       return { kind: 'repeat', times: numLike(command.times) ?? str(command.times) ?? '' };
     case 'retry':
@@ -423,8 +455,6 @@ function canonicalizeAgentCommand(
         label: command.label,
         source: command.include.kind === 'file' ? 'file' : 'commands',
       });
-    case 'runScript':
-      return { kind: 'runScript' };
     default: {
       const exhaustive: never = command;
       throw new Error(`Unhandled agent command: ${JSON.stringify(exhaustive)}`);

packages/maestro/src/internal/program-ir-command-parser.ts

@@ -14,6 +14,7 @@ import type {
   MaestroPressKeyCommand,
   MaestroScrollCommand,
   MaestroScrollUntilVisibleCommand,
+  MaestroSetPermissionsCommand,
   MaestroStopAppCommand,
   MaestroTakeScreenshotCommand,
   MaestroWaitForAnimationToEndCommand,
@@ -58,6 +59,7 @@ import {
   readSequenceItems,
   sourceAt,
   type MaestroProgramParseContext,
+  VARIABLE_PATTERN,
 } from './program-ir-values.ts';
 
 export function parseMaestroCommandList(
@@ -122,6 +124,7 @@ const COMMAND_VALUE_PARSERS: Readonly<Record<string, CommandValueParser>> = {
   back: parseBack,
   waitForAnimationToEnd: parseWaitForAnimationToEnd,
   stopApp: parseStopApp,
+  setPermissions: parseSetPermissions,
   runScript: parseMaestroRunScriptCommand,
   runFlow: (value, node, context) =>
     parseMaestroRunFlowCommand(value, node, context, parseMaestroCommandList),
@@ -447,6 +450,86 @@ function parseStopApp(
   return { kind: 'stopApp', source, appId: readRequiredString(value, 'stopApp', context) };
 }
 
+const MAESTRO_PERMISSION_VALUES = new Set([
+  'allow',
+  'deny',
+  'unset',
+  'always',
+  'inuse',
+  'never',
+  'limited',
+]);
+
+function parseSetPermissions(
+  value: Node | null,
+  commandNode: Node,
+  context: MaestroProgramParseContext,
+): MaestroSetPermissionsCommand {
+  const source = sourceAt(commandNode, context);
+  const entries = readMapEntries(value, 'setPermissions', context);
+  assertOnlyKeys(entries, 'setPermissions', ['appId', 'permissions', 'optional', 'label'], context);
+  if (!hasEntry(entries, 'permissions'))
+    invalidAt('Maestro setPermissions requires permissions.', commandNode, context);
+  const appId = readOptionalEntry(entries, 'appId', (entry) =>
+    readOptionalString(entry, 'setPermissions.appId', context),
+  );
+  const permissions = readSetPermissionsMap(entryValue(entries, 'permissions'), context);
+  if (Object.keys(permissions).length === 0)
+    invalidAt('Maestro setPermissions requires at least one permission.', commandNode, context);
+  const options = readOptionalCommandOption(entries, 'setPermissions', context);
+  const label = readMaestroCommandLabel(entries, 'setPermissions', context);
+  return stripUndefined({
+    kind: 'setPermissions' as const,
+    source,
+    appId,
+    permissions,
+    ...options,
+    label,
+  });
+}
+
+function readSetPermissionsMap(
+  node: Node | null | undefined,
+  context: MaestroProgramParseContext,
+): Record<string, string> {
+  const entries = readMapEntries(node, 'setPermissions.permissions', context);
+  const permissions: Record<string, string> = {};
+  for (const entry of entries) {
+    if (entry.key in permissions)
+      invalidAt(
+        `Maestro setPermissions.permissions contains duplicate permission "${entry.key}".`,
+        entry.keyNode,
+        context,
+      );
+    permissions[entry.key] = readPermissionValue(entry, context);
+  }
+  return permissions;
+}
+
+function readPermissionValue(
+  entry: { key: string; value: Node | null },
+  context: MaestroProgramParseContext,
+): string {
+  const name = `setPermissions.permissions.${entry.key}`;
+  const value = readScalarValue(entry.value, name, context);
+  if (typeof value !== 'string')
+    invalidAt(`Maestro ${name} expects a string.`, entry.value, context);
+  const normalized = value.toLowerCase();
+  if (MAESTRO_PERMISSION_VALUES.has(normalized)) return normalized;
+  if (VARIABLE_PATTERN.test(value)) return value;
+  if (value.includes('${'))
+    invalidAt(
+      `Maestro ${name} only supports allow|deny|unset (plus always|inuse|never|limited for location/photos) or a bare \${VAR} lookup; JavaScript expressions are not supported.`,
+      entry.value,
+      context,
+    );
+  invalidAt(
+    `Maestro ${name} expects allow|deny|unset (plus always|inuse|never|limited for location/photos) or a bare \${VAR} lookup.`,
+    entry.value,
+    context,
+  );
+}
+
 function parseLaunchArguments(
   node: Node | null | undefined,
   name: string,

packages/maestro/src/internal/program-ir-values.ts

@@ -199,7 +199,7 @@ export function readOptionalBoolean(
   return value;
 }
 
-const VARIABLE_PATTERN = /^\$\{[A-Za-z_][A-Za-z0-9_.]*\}$/;
+export const VARIABLE_PATTERN = /^\$\{[A-Za-z_][A-Za-z0-9_.]*\}$/;
 const NUMERIC_STRING_PATTERN = /^-?\d+(\.\d+)?$/;
 const INTEGER_STRING_PATTERN = /^-?\d+$/;