@qubiqlabs/mobiflow 0.9.1 → 1.0.0

package/README.md

@@ -21,15 +21,9 @@ 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+):
+**npm** (ships the engine; no git). You still need **Python 3.11+** on PATH.
+The launcher creates `~/.mobiflow/venv` and pip-installs the bundled package
+there (it does not clone GitHub or write into Homebrew/system Python):
 
 ```bash
 npm install -g @qubiqlabs/mobiflow
@@ -37,7 +31,7 @@ npm install -g @qubiqlabs/mobiflow
 npx @qubiqlabs/mobiflow --help
 ```
 
-On Windows, the wrapper prefers `py -3.12` / `py -3` (not the Microsoft Store
+On Windows, the launcher prefers `py -3.12` / `py -3` (not the Microsoft Store
 `python` stub). If detection still fails:
 
 ```bat
@@ -45,7 +39,11 @@ set MOBIFLOW_PYTHON=C:\Path\To\Python312\python.exe
 mobiflow init
 ```
 
-Or skip npm and run: `py -3.12 -m pip install mobiflow` then `py -3.12 -m mobiflow init`.
+**From this repo** (contributors):
+
+```bash
+pip install -e ".[dev]"
+```
 
 See [docs/PUBLISH.md](docs/PUBLISH.md) for maintainers.
 

package/bin/mobiflow.js

@@ -1,8 +1,7 @@
 #!/usr/bin/env node
 /**
- * npm bin wrapper for the Python MobiFlow CLI.
- * Ensures the Python package matches this package.json version, then runs
- * ``python -m mobiflow``.
+ * npm launcher for the MobiFlow engine (Python), which is shipped inside
+ * this package (pyproject.toml + src/mobiflow). No git clone.
  *
  * Windows note: never run ``python -c "…"`` through ``cmd.exe`` (shell:true) —
  * quoting breaks and a real 3.12 install looks like “no Python 3.11+”.
@@ -10,10 +9,13 @@
 "use strict";
 
 const { spawnSync } = require("child_process");
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
 
 const PKG = require("../package.json");
 const VERSION = PKG.version || "0.1.0";
-const REPO = "https://github.com/javed0211/MobiFlow.git";
+const ROOT = path.resolve(__dirname, "..");
 const IS_WIN = process.platform === "win32";
 
 /** @typedef {{ cmd: string, prefixArgs?: string[], label?: string }} PyCandidate */
@@ -157,8 +159,40 @@ function installedVersion(py) {
   return ver || null;
 }
 
+function bundledRoot() {
+  const pyproject = path.join(ROOT, "pyproject.toml");
+  const pkgDir = path.join(ROOT, "src", "mobiflow");
+  if (fs.existsSync(pyproject) && fs.existsSync(pkgDir)) return ROOT;
+  return null;
+}
+
+function venvDir() {
+  return process.env.MOBIFLOW_VENV || path.join(os.homedir(), ".mobiflow", "venv");
+}
+
+function venvPythonPath() {
+  const dir = venvDir();
+  return IS_WIN
+    ? path.join(dir, "Scripts", "python.exe")
+    : path.join(dir, "bin", "python");
+}
+
+/** Create ~/.mobiflow/venv with the discovered system Python (PEP 668 safe). */
+function ensureVenv(systemPy) {
+  const exe = venvPythonPath();
+  if (fs.existsSync(exe)) {
+    const ver = pythonVersion({ cmd: exe });
+    if (ver && ver.major >= 3 && ver.minor >= 11) return exe;
+  }
+  console.error(`[mobiflow] Creating engine venv at ${venvDir()}`);
+  fs.mkdirSync(path.dirname(venvDir()), { recursive: true });
+  const r = run(systemPy, ["-m", "venv", venvDir()], { stdio: "inherit" });
+  if (r.status !== 0 || !fs.existsSync(exe)) return null;
+  return exe;
+}
+
 function pipInstall(py, spec) {
-  console.error(`[mobiflow] Installing Python package: ${spec}`);
+  console.error(`[mobiflow] Installing engine from ${spec}`);
   const r = run(py, ["-m", "pip", "install", "--upgrade", spec], {
     stdio: "inherit",
   });
@@ -170,42 +204,48 @@ function ensureMobiflow(py) {
   if (current === VERSION) return true;
   if (current) {
     console.error(
-      `[mobiflow] Python package is ${current}; need ${VERSION} — upgrading…`
+      `[mobiflow] Engine is ${current}; need ${VERSION} — installing from this package…`
     );
+  } else {
+    console.error("[mobiflow] Installing engine from this npm package…");
   }
 
-  // Prefer git tags: the npm wrapper version tracks the GitHub release.
-  // PyPI may lag or be empty for early releases.
-  const specs = [
-    process.env.MOBIFLOW_PIP_SPEC,
-    `git+${REPO}@v${VERSION}`,
-    `mobiflow==${VERSION}`,
-    "mobiflow",
-    `git+${REPO}@main`,
-  ].filter(Boolean);
+  const specs = [];
+  if (process.env.MOBIFLOW_PIP_SPEC) {
+    specs.push(process.env.MOBIFLOW_PIP_SPEC);
+  }
+  const bundled = bundledRoot();
+  if (bundled) specs.push(bundled);
+
+  if (!specs.length) {
+    console.error(
+      "[mobiflow] This npm package is missing pyproject.toml / src/mobiflow.\n" +
+        "  Reinstall: npm install -g @qubiqlabs/mobiflow"
+    );
+    return false;
+  }
 
   for (const spec of specs) {
     if (!pipInstall(py, spec)) continue;
     const got = installedVersion(py);
     if (got === VERSION) return true;
-    if (moduleAvailable(py) && (spec.includes("@main") || process.env.MOBIFLOW_PIP_SPEC)) {
+    if (moduleAvailable(py) && process.env.MOBIFLOW_PIP_SPEC && spec === process.env.MOBIFLOW_PIP_SPEC) {
       return true;
     }
   }
-  // Last resort: whatever is importable (may be older — caller still runs).
   return moduleAvailable(py);
 }
 
 function main(argv) {
-  const py = whichPython();
-  if (!py) {
+  const systemPy = whichPython();
+  if (!systemPy) {
     const tried = whichPython._tried || [];
     console.error(
-      "[mobiflow] Python 3.11+ is required on PATH.\n" +
+      "[mobiflow] Python 3.11+ is required on PATH (the npm package ships the engine;\n" +
+        "  it does not replace Python).\n" +
         "  https://www.python.org/downloads/\n" +
         "  Or set MOBIFLOW_PYTHON to your python.exe, e.g.\n" +
-        '    set MOBIFLOW_PYTHON=C:\\Users\\You\\AppData\\Local\\Programs\\Python\\Python312\\python.exe\n' +
-        "  Or: py -3.12 -m pip install mobiflow && py -3.12 -m mobiflow --help"
+        "    set MOBIFLOW_PYTHON=C:\\Users\\You\\AppData\\Local\\Programs\\Python\\Python312\\python.exe"
     );
     if (tried.length) {
       console.error("  Tried: " + tried.join("; "));
@@ -213,14 +253,19 @@ function main(argv) {
     process.exit(1);
   }
 
-  // Always ensure the Python package matches this npm wrapper version first.
-  // Do not hand off to a stale console script on PATH (that hid new commands
-  // like ``apps`` after npm upgrades).
+  const py = ensureVenv(systemPy);
+  if (!py) {
+    console.error(
+      `[mobiflow] Could not create a venv with "${systemPy}".\n` +
+        `  Try: "${systemPy}" -m venv "${venvDir()}"`
+    );
+    process.exit(1);
+  }
+
   if (!ensureMobiflow(py)) {
     console.error(
-      "[mobiflow] Could not install the Python package.\n" +
-        `  Try: "${py}" -m pip install "git+${REPO}@v${VERSION}"\n` +
-        `  Or:  "${py}" -m pip install "git+${REPO}@main"`
+      "[mobiflow] Could not install the engine from this npm package.\n" +
+        `  Try: "${py}" -m pip install --upgrade "${ROOT}"`
     );
     process.exit(1);
   }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@qubiqlabs/mobiflow",
-  "version": "0.9.1",
-  "description": "CLI: NL \u2192 Maestro mobile flows via LLM, run on device/emulator, self-heal. (npm wrapper for the Python package)",
+  "version": "1.0.0",
+  "description": "CLI: NL \u2192 Maestro mobile flows via LLM, run on device/emulator, self-heal.",
   "license": "Apache-2.0",
   "author": "QubiQ Labs <labs@qubiq.ai>",
   "homepage": "https://github.com/javed0211/MobiFlow",
@@ -28,6 +28,11 @@
   },
   "files": [
     "bin/",
+    "src/mobiflow/**/*.py",
+    "src/mobiflow/**/*.html",
+    "src/mobiflow/**/*.svg",
+    "src/mobiflow/**/*.jpg",
+    "pyproject.toml",
     "README.md",
     "LICENSE"
   ],
@@ -36,7 +41,7 @@
   },
   "scripts": {
     "mobiflow": "node bin/mobiflow.js",
-    "prepack": "node -e \"require('fs').accessSync('bin/mobiflow.js')\""
+    "prepack": "node -e \"const fs=require('fs'); ['bin/mobiflow.js','pyproject.toml','src/mobiflow/cli.py'].forEach(p=>fs.accessSync(p))\""
   },
   "publishConfig": {
     "access": "public"

package/pyproject.toml

@@ -0,0 +1,59 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "mobiflow"
+version = "1.0.0"
+description = "CLI: NL → Maestro mobile flows via LLM, run on device/emulator, self-heal before you commit."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "Apache-2.0" }
+authors = [{ name = "QubiQ Labs", email = "labs@qubiq.ai" }]
+keywords = ["maestro", "mobile", "android", "ios", "testing", "llm", "cli"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Testing",
+]
+dependencies = [
+    "click>=8.1",
+    "questionary>=2.0",
+    "rich>=13.0",
+    "pyyaml>=6.0",
+    "pydantic>=2.5",
+    "openai>=1.40",
+    "httpx>=0.27",
+]
+
+[project.urls]
+Homepage = "https://github.com/javed0211/MobiFlow"
+Documentation = "https://github.com/javed0211/MobiFlow/blob/main/docs/CASES.md"
+Repository = "https://github.com/javed0211/MobiFlow"
+Issues = "https://github.com/javed0211/MobiFlow/issues"
+Changelog = "https://github.com/javed0211/MobiFlow/releases"
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0", "ruff>=0.5"]
+anthropic = ["anthropic>=0.40"]
+
+[project.scripts]
+mobiflow = "mobiflow.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/mobiflow"]
+
+[tool.hatch.build.targets.wheel.sources]
+"src/mobiflow" = "mobiflow"
+
+[tool.hatch.build.targets.sdist]
+include = ["src/mobiflow", "docs", "README.md", "pyproject.toml", "cases", "flows"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]

package/src/mobiflow/__init__.py

@@ -0,0 +1,9 @@
+"""mobiflow — NL → Maestro mobile automation in the terminal."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("mobiflow")
+except PackageNotFoundError:  # pragma: no cover - editable / source tree
+    __version__ = "1.0.0"
+

package/src/mobiflow/__main__.py

@@ -0,0 +1,6 @@
+"""Allow `python -m mobiflow`."""
+
+from mobiflow.cli import main
+
+if __name__ == "__main__":
+    main()

package/src/mobiflow/baseline.py

@@ -0,0 +1,228 @@
+"""Screenshot baseline compare for visual smoke checks."""
+
+from __future__ import annotations
+
+import json
+import struct
+import zlib
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+
+@dataclass
+class BaselineResult:
+    ok: bool
+    case: str
+    baseline: str = ""
+    candidate: str = ""
+    diff_path: str = ""
+    mismatch_ratio: float = 0.0
+    threshold: float = 0.02
+    message: str = ""
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "ok": self.ok,
+            "case": self.case,
+            "baseline": self.baseline,
+            "candidate": self.candidate,
+            "diff_path": self.diff_path,
+            "mismatch_ratio": self.mismatch_ratio,
+            "threshold": self.threshold,
+            "message": self.message,
+        }
+
+
+def baseline_dir(artifacts_dir: Path, case_name: str) -> Path:
+    return Path(artifacts_dir) / "baselines" / case_name
+
+
+def _read_png_rgba(path: Path) -> tuple[int, int, bytes]:
+    """Minimal PNG reader (8-bit RGBA/RGB/Gray). Returns width, height, RGBA bytes."""
+    data = path.read_bytes()
+    if data[:8] != b"\x89PNG\r\n\x1a\n":
+        raise ValueError(f"Not a PNG: {path}")
+    pos = 8
+    width = height = 0
+    bit_depth = 8
+    color_type = 2
+    raw = b""
+    while pos < len(data):
+        length = struct.unpack(">I", data[pos : pos + 4])[0]
+        pos += 4
+        ctype = data[pos : pos + 4]
+        pos += 4
+        chunk = data[pos : pos + length]
+        pos += length
+        pos += 4  # crc
+        if ctype == b"IHDR":
+            width, height, bit_depth, color_type = struct.unpack(">IIBB", chunk[:10])
+        elif ctype == b"IDAT":
+            raw += chunk
+        elif ctype == b"IEND":
+            break
+    if not width or not height:
+        raise ValueError(f"Invalid PNG header: {path}")
+    if bit_depth != 8 or color_type not in (0, 2, 4, 6):
+        raise ValueError(f"Unsupported PNG format in {path}")
+    decompressed = zlib.decompress(raw)
+    # Remove filter bytes (assume filter 0 for simplicity; handle None/sub roughly)
+    stride = {0: 1, 2: 3, 4: 2, 6: 4}[color_type]
+    row_bytes = width * stride
+    pixels = bytearray()
+    offset = 0
+    prev = bytearray(row_bytes)
+    for _y in range(height):
+        filter_type = decompressed[offset]
+        offset += 1
+        row = bytearray(decompressed[offset : offset + row_bytes])
+        offset += row_bytes
+        if filter_type == 1:  # Sub
+            for i in range(row_bytes):
+                left = row[i - stride] if i >= stride else 0
+                row[i] = (row[i] + left) & 0xFF
+        elif filter_type == 2:  # Up
+            for i in range(row_bytes):
+                row[i] = (row[i] + prev[i]) & 0xFF
+        elif filter_type == 3:  # Average
+            for i in range(row_bytes):
+                left = row[i - stride] if i >= stride else 0
+                row[i] = (row[i] + ((left + prev[i]) // 2)) & 0xFF
+        elif filter_type == 4:  # Paeth
+            for i in range(row_bytes):
+                a = row[i - stride] if i >= stride else 0
+                b = prev[i]
+                c = prev[i - stride] if i >= stride else 0
+                p = a + b - c
+                pa, pb, pc = abs(p - a), abs(p - b), abs(p - c)
+                pr = a if pa <= pb and pa <= pc else (b if pb <= pc else c)
+                row[i] = (row[i] + pr) & 0xFF
+        elif filter_type != 0:
+            raise ValueError(f"Unsupported PNG filter {filter_type} in {path}")
+        prev = row
+        if color_type == 6:
+            pixels.extend(row)
+        elif color_type == 2:
+            for i in range(0, len(row), 3):
+                pixels.extend([row[i], row[i + 1], row[i + 2], 255])
+        elif color_type == 0:
+            for v in row:
+                pixels.extend([v, v, v, 255])
+        elif color_type == 4:
+            for i in range(0, len(row), 2):
+                pixels.extend([row[i], row[i], row[i], row[i + 1]])
+    return width, height, bytes(pixels)
+
+
+def _write_png_rgba(path: Path, width: int, height: int, rgba: bytes) -> None:
+    def chunk(tag: bytes, data: bytes) -> bytes:
+        return (
+            struct.pack(">I", len(data))
+            + tag
+            + data
+            + struct.pack(">I", zlib.crc32(tag + data) & 0xFFFFFFFF)
+        )
+
+    raw = bytearray()
+    stride = width * 4
+    for y in range(height):
+        raw.append(0)
+        raw.extend(rgba[y * stride : (y + 1) * stride])
+    ihdr = struct.pack(">IIBBBBB", width, height, 8, 6, 0, 0, 0)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_bytes(
+        b"\x89PNG\r\n\x1a\n"
+        + chunk(b"IHDR", ihdr)
+        + chunk(b"IDAT", zlib.compress(bytes(raw), 9))
+        + chunk(b"IEND", b"")
+    )
+
+
+def compare_images(
+    baseline: Path,
+    candidate: Path,
+    *,
+    diff_path: Path | None = None,
+    threshold: float = 0.02,
+    max_channel_delta: int = 12,
+) -> tuple[bool, float, Path | None]:
+    """Return (ok, mismatch_ratio, diff_path)."""
+    bw, bh, bp = _read_png_rgba(baseline)
+    cw, ch, cp = _read_png_rgba(candidate)
+    if (bw, bh) != (cw, ch):
+        # Treat size mismatch as total fail
+        return False, 1.0, None
+    total = bw * bh
+    mismatches = 0
+    diff = bytearray(len(bp))
+    for i in range(0, len(bp), 4):
+        dr = abs(bp[i] - cp[i])
+        dg = abs(bp[i + 1] - cp[i + 1])
+        db = abs(bp[i + 2] - cp[i + 2])
+        if max(dr, dg, db) > max_channel_delta:
+            mismatches += 1
+            diff[i] = 255
+            diff[i + 1] = 0
+            diff[i + 2] = 0
+            diff[i + 3] = 255
+        else:
+            # dim baseline
+            diff[i] = bp[i] // 3
+            diff[i + 1] = bp[i + 1] // 3
+            diff[i + 2] = bp[i + 2] // 3
+            diff[i + 3] = 255
+    ratio = mismatches / max(1, total)
+    out_diff = None
+    if diff_path is not None:
+        _write_png_rgba(diff_path, bw, bh, bytes(diff))
+        out_diff = diff_path
+    return ratio <= threshold, ratio, out_diff
+
+
+def update_baseline(case_name: str, image: Path, artifacts_dir: Path) -> Path:
+    dest = baseline_dir(artifacts_dir, case_name) / "baseline.png"
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    dest.write_bytes(image.read_bytes())
+    meta = {
+        "case": case_name,
+        "source": str(image),
+        "updated_at": datetime.now(UTC).strftime("%Y-%m-%dT%H:%M:%SZ"),
+    }
+    (dest.parent / "baseline.json").write_text(
+        json.dumps(meta, indent=2) + "\n", encoding="utf-8"
+    )
+    return dest
+
+
+def compare_case_screenshot(
+    case_name: str,
+    candidate: Path,
+    artifacts_dir: Path,
+    *,
+    threshold: float = 0.02,
+) -> BaselineResult:
+    base = baseline_dir(artifacts_dir, case_name) / "baseline.png"
+    if not base.is_file():
+        return BaselineResult(
+            ok=False,
+            case=case_name,
+            candidate=str(candidate),
+            threshold=threshold,
+            message="No baseline — run `mobiflow baseline update <case> <png>`",
+        )
+    diff = baseline_dir(artifacts_dir, case_name) / "diff.png"
+    ok, ratio, diff_out = compare_images(
+        base, candidate, diff_path=diff, threshold=threshold
+    )
+    return BaselineResult(
+        ok=ok,
+        case=case_name,
+        baseline=str(base),
+        candidate=str(candidate),
+        diff_path=str(diff_out or ""),
+        mismatch_ratio=ratio,
+        threshold=threshold,
+        message="pass" if ok else f"mismatch {ratio:.3%} > {threshold:.3%}",
+    )