@alumnium/maestro 0.0.0-stage → 0.24.0-alpha.2

package/LICENSE.md

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2024 Alexey Rodionov, Tatiana Shepeleva
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -1,3 +1,3 @@
-# Temporary Holding Version
+# @alumnium/maestro
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Alumnium Maestro driver. See [the main `alumnium` package page](https://www.npmjs.com/package/alumnium) for more details.

package/package.json

@@ -1,6 +1,42 @@
 {
   "name": "@alumnium/maestro",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.24.0-alpha.2",
+  "description": "Alumnium Maestro driver",
+  "license": "MIT",
+  "author": "Alex Rodionov <p0deje@gmail.com>",
+  "contributors": [
+    "Alex Rodionov <p0deje@gmail.com>",
+    "Sasha Koss <koss@nocorp.me>",
+    "Tatiana Shepeleva <tati.shep@gmail.com>"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/alumnium-hq/alumnium.git"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE.md"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./src/index.d.ts",
+        "default": "./src/index.js"
+      },
+      "require": {
+        "types": "./src/index.d.ts",
+        "default": "./src/index.cjs"
+      }
+    }
+  },
+  "dependencies": {
+    "@alumnium/core": "0.24.0-alpha.2",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "alwaysly": "^0.4.0",
+    "domhandler": "^6.0.0",
+    "smollit": "^0.2.0",
+    "zod": "^4.4.1"
+  }
+}

package/src/Alumni.d.ts

@@ -0,0 +1,16 @@
+import { Alumni as BaseAlumni } from "@alumnium/core";
+import { MaestroDriver } from "./drivers/MaestroDriver.ts";
+import { MaestroSession } from "./drivers/MaestroSession.ts";
+/** Alumni driving a `MaestroSession`. */
+export declare class Alumni extends BaseAlumni<MaestroDriver> {
+  constructor(driver: MaestroSession, options?: Alumni.Options);
+  /** Whether the given object is a native driver this Alumni accepts. */
+  static accepts(driver: unknown): driver is Alumni.Driver;
+}
+export declare namespace Alumni {
+  type Driver = MaestroSession;
+  type Options = BaseAlumni.Options;
+  type VisionOptions = BaseAlumni.VisionOptions;
+  type CheckOptions = BaseAlumni.CheckOptions;
+  type CheckAssert = BaseAlumni.CheckAssert;
+}

package/src/accessibility/MaestroAccessibilityTree.d.ts

@@ -0,0 +1,34 @@
+import {
+  type AccessibilityElement,
+  BaseAccessibilityTree,
+} from "@alumnium/core/internal";
+import type { MaestroSession } from "../drivers/MaestroSession.ts";
+export declare namespace MaestroAccessibilityTree {
+  /** Role names inferred from the attributes Maestro provides. */
+  type Role = "TextField" | "CheckBox" | "Button" | "Text" | "View";
+}
+/**
+ * Maestro's view hierarchy, rendered as XML with `raw_id` markers.
+ *
+ * Maestro normalizes iOS and Android into one flat shape of `{attributes, children}`, which means
+ * it drops the platform element type — there is no `XCUIElementTypeButton` or
+ * `android.widget.TextView` to key off. Roles are therefore inferred from the attributes that do
+ * survive, and most nodes end up as the generic `View` that the server tree collapses away.
+ */
+export declare class MaestroAccessibilityTree extends BaseAccessibilityTree<MaestroSession.Hierarchy> {
+  #private;
+  protected get kind(): string;
+  constructor(hierarchy: MaestroSession.Hierarchy);
+  /** Renders the hierarchy as XML, stamping `raw_id` on every node. */
+  toStr(): string;
+  /** True when any node in the hierarchy carries the given `resource-id`. */
+  hasResourceId(resourceId: string): boolean;
+  elementById(rawId: number): AccessibilityElement;
+  /** Scopes the tree to the subtree rooted at `rawId`. */
+  scopeToArea(rawId: number): MaestroAccessibilityTree;
+  /** Parses the centre point of a Maestro `[x1,y1][x2,y2]` bounds string. */
+  static centreOf(bounds: string): {
+    x: number;
+    y: number;
+  };
+}

package/src/drivers/MaestroDriver.d.ts

@@ -0,0 +1,50 @@
+import {
+  AppId,
+  type BaseAccessibilityTree,
+  BaseDriver,
+  type Driver,
+  type Keys,
+  type ToolClass,
+} from "@alumnium/core/internal";
+import { MaestroSession } from "./MaestroSession.ts";
+export declare class MaestroDriver extends BaseDriver<never> {
+  #private;
+  kind: "maestro";
+  get platform(): Driver.MobileOs;
+  supportedTools: Set<ToolClass>;
+  delay: number;
+  hideKeyboardAfterTyping: boolean;
+  readonly session: MaestroSession;
+  constructor(session: MaestroSession);
+  protected fetchAccessibilityTree(): Promise<BaseAccessibilityTree>;
+  click(id: number): Promise<void>;
+  type(id: number, text: string): Promise<void>;
+  pressKey(key: Keys.Key): Promise<void>;
+  back(): Promise<void>;
+  visit(url: string): Promise<void>;
+  screenshot(): Promise<string>;
+  app(): AppId;
+  title(): string;
+  url(): string;
+  wait(seconds: number): Promise<void>;
+  quit(): Promise<void>;
+  /** Maestro has no programmatic access to elements. */
+  findElement(): Promise<never>;
+  dragSlider(): void;
+  dragAndDrop(): Promise<void>;
+  scrollTo(): Promise<void>;
+  executeScript(): Promise<void>;
+  switchToNextTab(): Promise<void>;
+  switchToPreviousTab(): Promise<void>;
+  waitForSelector(): Promise<void>;
+  printToPdf(): Promise<void>;
+  checkNavigationPolicy(_url?: string): void;
+  /**
+   * Resolves a raw id to the tap target it would produce, so the tree drill can report which ids
+   * are actionable. Maestro has no locators, so the bounds string stands in for one.
+   */
+  protected devDrillProbeTree(
+    tree: BaseAccessibilityTree,
+    rawId: number,
+  ): Promise<string>;
+}

package/src/drivers/MaestroSession.d.ts

@@ -0,0 +1,91 @@
+import z from "zod";
+export declare namespace MaestroSession {
+  type Os = z.infer<typeof MaestroSession.Os>;
+  interface Node {
+    [key: string]: unknown;
+  }
+  interface Hierarchy {
+    ui_schema: {
+      platform?: string;
+      abbreviations: Record<string, string>;
+      defaults: Record<string, unknown>;
+    };
+    elements: Node[];
+  }
+  interface Device {
+    device_id: string;
+    name: string;
+    platform: string;
+    type: string;
+    connected: boolean;
+  }
+  interface Props {
+    /** Application identifier, e.g. an iOS bundle id: `com.ayodeji.TodoList`. */
+    appId: string;
+    /** Maestro device id, i.e. a simulator UDID. Defaults to the first connected device. */
+    deviceId?: string | undefined;
+    /** Hide the macOS Simulator window. Defaults to false. iOS simulators only. */
+    headless?: boolean | undefined;
+    /** Path to the `maestro` executable. Defaults to `~/.maestro/bin/maestro`. */
+    executablePath?: string | undefined;
+    /** Arguments the app is launched with. */
+    launchArgs?: string[] | undefined;
+    /**
+     * Environment the app is launched with. Maestro's own `launchApp` cannot set one, so a session
+     * that needs it is launched through `simctl` instead — see `launchApp`. iOS simulators only.
+     */
+    launchEnv?: Record<string, string> | undefined;
+  }
+  interface LaunchAppOptions {
+    clearState?: boolean;
+  }
+  /** A single content item of an MCP tool result. */
+  interface Content {
+    type: string;
+    text?: string;
+    data?: string;
+    mimeType?: string;
+  }
+}
+/**
+ * A live Maestro session, driven through Maestro's own MCP server (`maestro mcp`) over stdio.
+ */
+export declare class MaestroSession {
+  #private;
+  static Os: z.ZodEnum<{
+    android: "android";
+    ios: "ios";
+  }>;
+  /** Marks the object for `Alumni`'s duck-typed driver detection. */
+  readonly isMaestroSession: true;
+  readonly appId: string;
+  /** Upper bound for one Maestro MCP tool call. */
+  static readonly TOOL_TIMEOUT_MS: number;
+  constructor(props: MaestroSession.Props);
+  get deviceId(): string;
+  get os(): MaestroSession.Os;
+  static start(props: MaestroSession.Props): Promise<MaestroSession>;
+  inspectScreen(): Promise<MaestroSession.Hierarchy>;
+  /**
+   * Runs Maestro flow commands against the running app.
+   *
+   * The commands are wrapped in a flow with an `appId` header. Maestro does not relaunch or reset
+   * the app for a flow that has no explicit `launchApp`, so consecutive calls act on the state the
+   * previous one left behind.
+   *
+   * @param commands Flow body in Maestro YAML, e.g. `- tapOn:\n    point: "10,20"`.
+   */
+  run(commands: string): Promise<void>;
+  /**
+   * Launches the app, optionally wiping its state first.
+   *
+   * With a launch environment or arguments, the launch goes through `simctl` rather than Maestro:
+   * Maestro's `launchApp` can pass neither, and an app that reads its configuration from the
+   * environment only sees it on a launch that actually sets one. Maestro then drives whatever is on
+   * screen, which is the app this just started — its flows never relaunch on their own.
+   */
+  launchApp(options?: MaestroSession.LaunchAppOptions): Promise<void>;
+  /** Takes a screenshot and returns it base64-encoded. */
+  screenshot(): Promise<string>;
+  close(): Promise<void>;
+}