@qubiqlabs/mobiflow 0.2.0

package/LICENSE

@@ -0,0 +1,190 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2026 QubiQ Labs
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,225 @@
+# MobiFlow
+
+CLI-only mobile automation: describe a scenario in natural language,
+generate **Maestro** flow YAML with an LLM, run it on a device/emulator,
+and self-heal via a verify/repair loop — all in the terminal.
+
+Configure LLMs with `llm.json` + `mobiflow.config.yaml`, scaffold with
+`mobiflow init`, then author cases and run them locally or in the cloud.
+
+## Requirements
+
+- Python 3.11+
+- An LLM API key (OpenAI / Azure / Anthropic / Google)
+- [Maestro CLI](https://maestro.mobile.dev) + a JDK (`JAVA_HOME`)
+- Android emulator (`adb`) and/or booted iOS Simulator
+
+```bash
+# Maestro (macOS/Linux)
+curl -Ls "https://get.maestro.mobile.dev" | bash
+```
+
+## Install
+
+**Python (recommended):**
+
+```bash
+pip install mobiflow
+# or from source
+pip install -e ".[dev]"
+```
+
+**npm wrapper** (launches the Python CLI; requires Python 3.11+):
+
+```bash
+npm install -g @qubiqlabs/mobiflow
+# or
+npx @qubiqlabs/mobiflow --help
+```
+
+See [docs/PUBLISH.md](docs/PUBLISH.md) for maintainers.
+
+## Quick start
+
+```bash
+mobiflow init
+# Guided wizard:
+#   Step 1/5 — Project path
+#   Step 2/5 — LLM provider & models (writes llm.json)
+#   Step 3/5 — Device defaults + language (yaml | yaml+js)
+#   Step 4/5 — Detect missing packages → optional auto-install
+#   Step 5/5 — Write mobiflow.config.yaml + example case
+
+export OPENAI_API_KEY=sk-...   # or AZURE_OPENAI_API_KEY / ANTHROPIC_API_KEY / …
+
+mobiflow status
+mobiflow run cases/example.txt
+```
+
+Non-interactive (auto-installs missing Maestro / JDK / pip packages by default):
+
+```bash
+mobiflow init --mode local --path . --yes
+mobiflow init --mode local --path . --yes --no-install-deps   # skip installs
+mobiflow setup                # re-check / install anytime
+mobiflow setup --check-only   # report only
+mobiflow setup --install-adb  # also Homebrew android-platform-tools
+```
+
+### Auto-install during setup
+
+Step 4 (and `mobiflow setup`) probes and can install:
+
+| Dependency | How |
+|------------|-----|
+| Python packages (`openai`, `anthropic`, …) | `pip install` |
+| Maestro CLI | official `get.maestro.mobile.dev` installer |
+| JDK | Homebrew `openjdk` (when `brew` is available) |
+| Android `adb` | optional Homebrew `android-platform-tools` |
+
+Xcode / full Android SDK are reported but not auto-installed.
+
+## LLM configuration
+
+**Two files:**
+
+1. `llm.json` — named provider profiles (no secrets)
+2. `mobiflow.config.yaml` `llm:` — picks `discovery` + `codegen` by profile id
+
+```yaml
+llm:
+  catalog: llm.json
+  discovery: azure-gpt4o      # adaptive explore / plan
+  codegen: anthropic-sonnet   # Maestro YAML authoring
+```
+
+```json
+{
+  "version": 1,
+  "models": {
+    "azure-gpt4o": {
+      "provider": "azure",
+      "model": "gpt-4o",
+      "deployment": "gpt-4o",
+      "api_key_env": "AZURE_OPENAI_API_KEY",
+      "endpoint": "https://YOUR.openai.azure.com",
+      "endpoint_env": "AZURE_OPENAI_ENDPOINT",
+      "api_version": "2025-03-01-preview"
+    }
+  }
+}
+```
+
+Keys live only in env vars named by `api_key_env`. Never paste secrets into YAML/JSON.
+
+```bash
+mobiflow llm list
+mobiflow config show
+```
+
+## Test case format (`.txt`)
+
+Cases are free-form text with optional run knobs and external data. Full reference:
+**[docs/CASES.md](docs/CASES.md)**.
+
+```text
+@smoke
+appId: org.wikipedia
+platform: android
+codegen: true          # false → reuse flows/<case>.yaml
+retries: 0
+heal: 2
+data: data/example.json
+task: |
+  Open Wikipedia, dismiss onboarding, confirm Search is visible
+  1. Launch the app
+  2. Tap Search and type ${SEARCH_QUERY}
+  3. Confirm Search results are visible
+```
+
+**Precedence for run knobs:** CLI → case file → `mobiflow.config.yaml`.  
+**Data:** `data:` accepts a relative or absolute path to `.json` / `.yaml` / `.env`;
+values flatten into Maestro `--env` / `${KEY}`.
+
+```bash
+mobiflow run cases/example.txt
+mobiflow run cases/wikipedia_complex_search.txt   # iOS Wikipedia + data file
+```
+
+## Commands
+
+| Command | Behavior |
+|---------|----------|
+| `mobiflow init` | Wizard / non-interactive scaffold (+ optional deps install) |
+| `mobiflow setup` | Detect / auto-install missing Maestro, JDK, pip packages |
+| `mobiflow run <case.txt>` | Explore → LLM YAML → device (+ heal) |
+| `mobiflow run cases/ [--tag smoke]` | Suite: all (or tagged) cases + aggregate JUnit/HTML |
+| `mobiflow suite [cases/]` | Same as `run` on a directory (defaults to `cases/`) |
+| `mobiflow run <case.txt> --gen-only` | Author YAML only |
+| `mobiflow run … --reuse-flow` | Skip LLM; use frozen `flows/<case>.yaml` |
+| `mobiflow run … --incremental` | Gap-explore only newly appended numbered steps |
+| `mobiflow run … --extend-explore` | Full explore + extend codegen from prior YAML |
+| `mobiflow gen "Open Settings…"` | One-shot NL → YAML |
+| `mobiflow explore "…" [--interactive]` | Discovery session (confirm each action with `--interactive`) |
+| `mobiflow import-flow flow.yaml` | Studio/YAML → MobiFlow case (+ copy into `flows/`) |
+| `mobiflow baseline update/compare` | Visual PNG baseline |
+| `mobiflow studio` | Open Maestro Studio (local device UI) |
+| `mobiflow test-flow flows/foo.yaml` | Run existing YAML |
+| `mobiflow status` / `devices` | Maestro + local devices + cloud lab readiness |
+| `mobiflow devices --start` | Auto-start Android AVD (Win/Mac) or Xcode sim (Mac) |
+| `mobiflow config show` / `llm list` | Inspect config / catalog |
+
+## Languages
+
+| `stack.language` | Behavior |
+|------------------|----------|
+| `yaml+js` (default) | Maestro YAML + optional JS (`evalScript` / `runScript` / `${…}`) |
+| `yaml` | YAML commands only |
+
+Companion scripts land under `flows/scripts/`.
+
+## Reporting
+
+Each live run can write **JUnit** + **HTML** under `.mobiflow/reports/` (and under the run folder),
+plus Maestro debug output / screenshots when running locally.
+
+```yaml
+run:
+  reports: [junit, html]
+  report_dir: .mobiflow/reports
+```
+
+Suites write aggregate reports under `.mobiflow/reports/suite-<name>-<ts>/`.
+GitHub Actions (`.github/workflows/ci.yml`) runs lint + unit tests; set
+`MOBIFLOW_CLOUD_CI=true` plus cloud/LLM secrets for an optional smoke suite job.
+
+## Cloud device labs
+
+Set `device.provider` to `browserstack` or `testmu` to run on real devices in the cloud
+(same Maestro YAML; no local emulator required). See [docs/FEATURES.md](docs/FEATURES.md).
+
+```bash
+export BROWSERSTACK_USERNAME=... BROWSERSTACK_ACCESS_KEY=...
+# or TESTMU_USERNAME / TESTMU_ACCESS_KEY (LT_* aliases work)
+```
+
+## Pipeline
+
+```
+1. Load case + config + optional data: file → Maestro env
+2. Resolve run mode (codegen / reuse / incremental / extend) — CLI > case > config
+3. Explore app with discovery LLM (or replay prefix + gap for --incremental)
+4. Author / extend Maestro YAML (+ JS when enabled)
+5. Local: maestro test --device <id>
+   Cloud: upload app + suite → BrowserStack / TestMu HyperExecute
+6. On fail → repair with failure log (≤ heal) → re-run
+7. Write flows/<case>.yaml (+ scripts), guidance stamp, reports under .mobiflow/
+```
+
+## Docs
+
+| Doc | Contents |
+|-----|----------|
+| [docs/CASES.md](docs/CASES.md) | Case template, run knobs, `data:`, incremental |
+| [docs/FEATURES.md](docs/FEATURES.md) | Devices, cloud, suite, JS, reporting, CI |
+| [docs/PUBLISH.md](docs/PUBLISH.md) | PyPI + npm publish steps |

package/bin/mobiflow.js

@@ -0,0 +1,152 @@
+#!/usr/bin/env node
+/**
+ * npm bin wrapper for the Python MobiFlow CLI.
+ * Resolves: PATH mobiflow → python -m mobiflow → pip install → retry.
+ */
+"use strict";
+
+const { spawnSync } = require("child_process");
+const fs = require("fs");
+const path = require("path");
+
+const PKG = require("../package.json");
+const VERSION = PKG.version || "0.1.0";
+const REPO = "https://github.com/javed0211/MobiFlow.git";
+
+function pyCandidates() {
+  const fromEnv = process.env.MOBIFLOW_PYTHON;
+  const list = [];
+  if (fromEnv) list.push(fromEnv);
+  if (process.platform === "win32") {
+    list.push("py", "python3.12", "python3.11", "python", "python3");
+  } else {
+    list.push("python3.12", "python3.11", "python3", "python");
+  }
+  return [...new Set(list)];
+}
+
+function run(cmd, args, opts = {}) {
+  return spawnSync(cmd, args, {
+    stdio: opts.stdio ?? "inherit",
+    encoding: "utf8",
+    shell: process.platform === "win32",
+    env: process.env,
+  });
+}
+
+function pythonVersion(py) {
+  const r = run(
+    py,
+    ["-c", "import sys; print(f'{sys.version_info.major}.{sys.version_info.minor}')"],
+    { stdio: ["ignore", "pipe", "ignore"] }
+  );
+  if (r.status !== 0 || !r.stdout) return null;
+  const parts = r.stdout.toString().trim().split(".").map(Number);
+  return { major: parts[0], minor: parts[1], exe: null };
+}
+
+function whichPython() {
+  for (const py of pyCandidates()) {
+    const ver = pythonVersion(py);
+    if (!ver || ver.major < 3 || ver.minor < 11) continue;
+    const r = run(py, ["-c", "import sys; print(sys.executable)"], {
+      stdio: ["ignore", "pipe", "ignore"],
+    });
+    if (r.status === 0 && r.stdout) {
+      return r.stdout.toString().trim();
+    }
+  }
+  return null;
+}
+
+function moduleAvailable(py) {
+  const r = run(py, ["-c", "import mobiflow"], {
+    stdio: ["ignore", "ignore", "ignore"],
+  });
+  return r.status === 0;
+}
+
+function pipInstall(py, spec) {
+  console.error(`[mobiflow] Installing Python package: ${spec}`);
+  const r = run(py, ["-m", "pip", "install", "--upgrade", spec], {
+    stdio: "inherit",
+  });
+  return r.status === 0;
+}
+
+function ensureMobiflow(py) {
+  if (moduleAvailable(py)) return true;
+
+  const specs = [
+    process.env.MOBIFLOW_PIP_SPEC,
+    `mobiflow==${VERSION}`,
+    "mobiflow",
+    `git+${REPO}@v${VERSION}`,
+    `git+${REPO}@main`,
+  ].filter(Boolean);
+
+  for (const spec of specs) {
+    if (pipInstall(py, spec) && moduleAvailable(py)) return true;
+  }
+  return false;
+}
+
+function main(argv) {
+  const py = whichPython();
+  if (!py) {
+    console.error(
+      "[mobiflow] Python 3.11+ is required on PATH.\n" +
+        "  https://www.python.org/downloads/\n" +
+        "  Or set MOBIFLOW_PYTHON=/path/to/python3.12\n" +
+        "  Or: pip install mobiflow && mobiflow --help"
+    );
+    process.exit(1);
+  }
+
+  // Prefer an already-installed console script on PATH (avoid recursion).
+  const self = path.resolve(__filename);
+  const onPath = run(
+    process.platform === "win32" ? "where" : "which",
+    ["mobiflow"],
+    { stdio: ["ignore", "pipe", "ignore"] }
+  );
+  if (onPath.status === 0 && onPath.stdout) {
+    const candidates = onPath.stdout
+      .toString()
+      .split(/\r?\n/)
+      .map((s) => s.trim())
+      .filter(Boolean);
+    for (const bin of candidates) {
+      let resolved = bin;
+      try {
+        resolved = fs.realpathSync(bin);
+      } catch {
+        /* ignore */
+      }
+      if (resolved === self) continue;
+      if (resolved.includes(`${path.sep}node_modules${path.sep}`)) continue;
+      if (resolved.includes(`${path.sep}@qubiqlabs${path.sep}mobiflow${path.sep}`)) {
+        continue;
+      }
+      if (resolved.includes(`${path.sep}mobiflow${path.sep}bin${path.sep}`)) {
+        continue;
+      }
+      const r = run(bin, argv, { stdio: "inherit" });
+      process.exit(r.status ?? 1);
+    }
+  }
+
+  if (!ensureMobiflow(py)) {
+    console.error(
+      "[mobiflow] Could not install the Python package.\n" +
+        `  Try: ${py} -m pip install "git+${REPO}@main"\n` +
+        `  Or:  ${py} -m pip install mobiflow`
+    );
+    process.exit(1);
+  }
+
+  const r = run(py, ["-m", "mobiflow", ...argv], { stdio: "inherit" });
+  process.exit(r.status ?? 1);
+}
+
+main(process.argv.slice(2));

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@qubiqlabs/mobiflow",
+  "version": "0.2.0",
+  "description": "CLI: NL → Maestro mobile flows via LLM, run on device/emulator, self-heal. (npm wrapper for the Python package)",
+  "license": "Apache-2.0",
+  "author": "QubiQ Labs <labs@qubiq.ai>",
+  "homepage": "https://github.com/javed0211/MobiFlow",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/javed0211/MobiFlow.git"
+  },
+  "bugs": {
+    "url": "https://github.com/javed0211/MobiFlow/issues"
+  },
+  "keywords": [
+    "maestro",
+    "mobile",
+    "android",
+    "ios",
+    "testing",
+    "llm",
+    "cli",
+    "automation",
+    "mobiflow"
+  ],
+  "bin": {
+    "mobiflow": "bin/mobiflow.js"
+  },
+  "files": [
+    "bin/",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "mobiflow": "node bin/mobiflow.js",
+    "prepack": "node -e \"require('fs').accessSync('bin/mobiflow.js')\""
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "preferGlobal": true
+}