Mola-maker/mstack / skills/m-cua
m-cua
VerifiedDrive a real desktop app, Android device or browser to prove L3/L4 acceptance. Use for 点一下/操作界面/真机验收/computer use.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 5.9 KB |
| references/drivers.md | markdown | 7.8 KB |
| scripts/cua-doctor.mjs | script | 11.2 KB |
| scripts/cua-doctor.test.mjs | script | 12.9 KB |
scripts/cua-doctor.mjs
View on GitHub#!/usr/bin/env node
// Probes the GUI drivers m-cua can use and says what is missing and how to connect it.
// Usage: node cua-doctor.mjs [--need desktop|android|web] [--json]
// Exit 0: every needed driver is usable (no --need: at least one is). Exit 1: a needed driver is not usable. Exit 2: bad arguments.
// A driver is one of: ready | not-on-path (installed and working, but only by the full path printed) | no-device | missing | broken.
// ready and not-on-path are both usable.
import { existsSync, statSync } from "node:fs";
const isFile = (p) => { try { return statSync(p).isFile(); } catch { return false; } };
import { spawnSync } from "node:child_process";
import { join, delimiter, dirname, basename } from "node:path";
import { pathToFileURL } from "node:url";
const WIN = process.platform === "win32";
/** First existing file named `name` (with a PATHEXT suffix on Windows) in `dirs`. */
export function findIn(dirs, name, env = process.env) {
// On Windows an extensionless file beside the .cmd is npm's POSIX shim, so real launchers are tried first.
const exts = WIN ? [...(env.PATHEXT || ".EXE;.CMD;.BAT").split(";").map((e) => e.toLowerCase()), ""] : [""];
for (const d of dirs.filter(Boolean))
for (const e of exts) {
const p = join(d, name + e);
try { if (existsSync(p) && statSync(p).isFile()) return p; } catch { /* unreadable dir: keep looking */ }
}
return null;
}
const run = (bin, args, env) => {
const opts = { encoding: "utf8", env, timeout: 15000, windowsHide: true };
// Windows .cmd/.bat launchers need a shell. cmd expands %VAR% even inside quotes, so the directory never goes
// into the command string: the file is run as .\<name> from its directory (the .\ stops cmd from taking a same-named file on PATH). Arguments are fixed strings, never user input.
const viaShell = WIN && !/\.(exe|com)$/i.test(bin);
const r = viaShell ? spawnSync(`".\\${basename(bin)}" ${args.join(" ")}`, { ...opts, cwd: dirname(bin), shell: true }) : spawnSync(bin, args, opts);
return { status: r.status, out: (r.stdout || "") + (r.stderr || ""), error: r.error?.message };
};
function locate(name, extraDirs, env) {
const onPath = findIn((env.PATH || env.Path || "").split(delimiter), name, env);
if (onPath) return { bin: onPath, onPath: true };
const off = findIn(extraDirs, name, env);
return off ? { bin: off, onPath: false } : null;
}
export function probeDesktop(env = process.env) {
const extra = [env.APPDATA && join(env.APPDATA, "npm"), env.npm_config_prefix && join(env.npm_config_prefix, WIN ? "" : "bin"), env.HOME && join(env.HOME, ".npm-global", "bin")];
const hit = locate("agent-desktop", extra, env);
if (!hit) return { driver: "desktop", tool: "agent-desktop", state: "missing", fix: "npm install -g agent-desktop" };
const r = run(hit.bin, ["status"], env);
let st = null;
for (const line of r.out.split("\n")) { try { const j = JSON.parse(line); if (j.command === "status") st = j; } catch { /* launcher notices are not JSON */ } }
if (!st?.ok || !st.data) return { driver: "desktop", tool: "agent-desktop", state: "broken", bin: hit.bin, fix: "run `agent-desktop status` and read the error", detail: (r.error || r.out).slice(0, 200) };
// Reading the accessibility tree needs only this permission; screen recording matters for screenshots alone.
const acc = st.data.permissions?.accessibility?.state;
if (acc && !["granted", "not_required"].includes(acc))
return { driver: "desktop", tool: "agent-desktop", state: "broken", bin: hit.bin, fix: process.platform === "darwin" ? "agent-desktop permissions --guide" : "agent-desktop permissions --request, then read `agent-desktop skills get platform`", detail: "accessibility permission is " + acc };
return hit.onPath
? { driver: "desktop", tool: "agent-desktop", state: "ready", bin: hit.bin, version: st.data.version }
: { driver: "desktop", tool: "agent-desktop", state: "not-on-path", bin: hit.bin, fix: `call it by full path, or add its directory to PATH: ${hit.bin}` };
}
const MOLA_CUA_BUILD = "git clone https://github.com/Mola-maker/agent-desktop && cd agent-desktop/mola-cua && cargo build --release, then put target/release/mola-cua on PATH";
/**
* Android. `mola-cua` is preferred: it gives refs that are re-found before every action, says whether input
* reached the device, and reads fields back. It finds adb itself. Without it, plain `adb` still works (the
* driver reference has the commands) and the result says what is being missed.
*/
export function probeAndroid(env = process.env) {
// MOLA_CUA_BIN names the binary outright (a build output that is not installed). It must exist: a stale
// path is reported as that, with the variable named, not as "Android unusable".
if (env.MOLA_CUA_BIN && !isFile(env.MOLA_CUA_BIN)) {
return { driver: "android", tool: "mola-cua", state: "broken", bin: env.MOLA_CUA_BIN, fix: `MOLA_CUA_BIN is not a file (a missing path, or a directory): ${env.MOLA_CUA_BIN}; fix it, or unset it to use mola-cua from PATH or plain adb` };
}
const cargoBins = [env.CARGO_HOME && join(env.CARGO_HOME, "bin"), env.HOME && join(env.HOME, ".cargo", "bin"), env.USERPROFILE && join(env.USERPROFILE, ".cargo", "bin")];
const hit = env.MOLA_CUA_BIN ? { bin: env.MOLA_CUA_BIN, onPath: false } : locate("mola-cua", cargoBins, env);
if (!hit) {
const adb = probeAdb(env);
return { ...adb, note: `plain adb only; for refs and verified input build mola-cua: ${MOLA_CUA_BUILD}` };
}
const r = run(hit.bin, ["status"], env);
let st = null;
for (const line of r.out.split("\n")) { try { const j = JSON.parse(line); if (j.command === "status") st = j; } catch { /* not JSON */ } }
if (!st) return { driver: "android", tool: "mola-cua", state: "broken", bin: hit.bin, fix: "run `mola-cua status` and read the error", detail: (r.error || r.out).slice(0, 200) };
if (!st.ok) return { driver: "android", tool: "mola-cua", state: "broken", bin: hit.bin, fix: String(st.error?.suggestion ?? "run `mola-cua status` and read the error").slice(0, 300), detail: String(st.error?.message ?? "").slice(0, 200) };
const devices = Array.isArray(st.data?.devices) ? st.data.devices : [];
const online = devices.filter((d) => d?.state === "device").map((d) => String(d.serial));
if (!online.length) {
const why = devices.length ? `devices present but not usable: ${devices.map((d) => `${d.serial} ${d.state}`).join(", ")}` : "no device or emulator attached";
const emu = st.data?.adb?.path ? findIn([join(dirname(dirname(String(st.data.adb.path))), "emulator")], "emulator", env) : null;
const emulator = emu ?? "<Android SDK>/emulator/emulator";
return { driver: "android", tool: "mola-cua", state: "no-device", bin: hit.bin, fix: `start an emulator ("${emulator}" -list-avds, then "${emulator}" -avd <name>; in PowerShell put & before the quoted path) or plug in a device with USB debugging authorised`, detail: why };
}
return hit.onPath
? { driver: "android", tool: "mola-cua", state: "ready", bin: hit.bin, devices: online, version: st.data?.version }
: { driver: "android", tool: "mola-cua", state: "not-on-path", bin: hit.bin, devices: online, fix: `call it by full path, or add its directory to PATH: ${hit.bin}` };
}
/** Android through plain adb: the fallback when mola-cua is not installed. */
export function probeAdb(env = process.env) {
const sdks = [env.ANDROID_HOME, env.ANDROID_SDK_ROOT, env.LOCALAPPDATA && join(env.LOCALAPPDATA, "Android", "Sdk"), env.HOME && join(env.HOME, "Android", "Sdk"), env.HOME && join(env.HOME, "Library", "Android", "sdk")];
const hit = locate("adb", sdks.filter(Boolean).map((s) => join(s, "platform-tools")), env);
if (!hit) return { driver: "android", tool: "adb", state: "missing", fix: "install Android SDK Platform-Tools (https://developer.android.com/tools/releases/platform-tools) and put platform-tools on PATH" };
const r = run(hit.bin, ["devices"], env);
if (r.status !== 0) return { driver: "android", tool: "adb", state: "broken", bin: hit.bin, fix: "run `adb devices` and read the error", detail: (r.error || r.out).slice(0, 200) };
// A device row is `<serial><TAB><state>`; the state can hold spaces ("no permissions (...)"). Notices such as
// "* daemon started" or "adb server version (41) doesn't match this client" have no tab and are not devices.
const rows = r.out.split("\n").map((l) => l.trim().match(/^(\S+)\t+(.+)$/)).filter(Boolean).map((m) => [m[1], m[2]]);
const online = rows.filter((c) => c[1] === "device").map((c) => c[0]);
if (!online.length) {
// `emulator` is rarely on PATH; it sits beside platform-tools in the SDK.
const emu = findIn([join(dirname(dirname(hit.bin)), "emulator")], "emulator", env) ?? "<Android SDK>/emulator/emulator";
const why =(rows.length ? `devices present but not usable: ${rows.map((c) => c.join(" ")).join(", ")}` : "no device or emulator attached") + (hit.onPath ? "" : "; adb is also not on PATH");
return { driver: "android", tool: "adb", state: "no-device", bin: hit.bin, onPath: hit.onPath, fix: `start an emulator ("${emu}" -list-avds, then "${emu}" -avd <name>; in PowerShell put & before the quoted path) or plug in a device with USB debugging authorised`, detail: why };
}
return hit.onPath
? { driver: "android", tool: "adb", state: "ready", bin: hit.bin, devices: online }
: { driver: "android", tool: "adb", state: "not-on-path", bin: hit.bin, devices: online, fix: `call it by full path, or add its directory to PATH: ${hit.bin}` };
}
export function probeWeb(env = process.env, cwd = process.cwd()) {
const hit = findIn([join(cwd, "node_modules", ".bin")], "playwright", env) || locate("playwright", [], env)?.bin;
if (!hit) return { driver: "web", tool: "playwright", state: "missing", fix: "npm install -D @playwright/test && npx playwright install chromium" };
const r = run(hit, ["--version"], env);
if (r.status !== 0) return { driver: "web", tool: "playwright", state: "broken", bin: hit, fix: "run `npx playwright --version` and read the error", detail: (r.error || r.out).slice(0, 200) };
return { driver: "web", tool: "playwright", state: "ready", bin: hit, version: r.out.trim().split("\n").pop() };
}
const PROBES = { desktop: probeDesktop, android: probeAndroid, web: probeWeb };
export function main(argv, env = process.env, cwd = process.cwd()) {
const need = [];
let json = false;
for (let i = 0; i < argv.length; i++) {
if (argv[i] === "--json") json = true;
else if (argv[i] === "--need" && Object.hasOwn(PROBES, argv[i + 1] ?? "")) need.push(argv[++i]);
else return { code: 2, text: `usage: cua-doctor.mjs [--need desktop|android|web] [--json] (bad argument: ${argv[i]})` };
}
const results = (need.length ? need : Object.keys(PROBES)).map((d) => PROBES[d](env, cwd));
const usable = results.filter((r) => r.state === "ready" || r.state === "not-on-path");
const ok = need.length ? usable.length === results.length : usable.length > 0;
const text = json
? JSON.stringify({ ok, drivers: results })
: results.map((r) => `${r.driver}: ${r.state} (${r.tool}${r.bin ? " at " + r.bin : ""})${r.detail ? " - " + r.detail : ""}${r.fix ? "\n fix: " + r.fix : ""}${r.note ? "\n note: " + r.note : ""}`).join("\n");
return { code: ok ? 0 : 1, text };
}
if (import.meta.url === pathToFileURL(process.argv[1] ?? "").href) {
const { code, text } = main(process.argv.slice(2));
console.log(text);
process.exit(code);
}
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |