Skip to content

Mola-maker/mstack / skills/m-cua

Drive a real desktop app, Android device or browser to prove L3/L4 acceptance. Use for 点一下/操作界面/真机验收/computer use.

FileKindSize
SKILL.mdskill md5.9 KB
references/drivers.mdmarkdown7.8 KB
scripts/cua-doctor.mjsscript11.2 KB
scripts/cua-doctor.test.mjsscript12.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);
}
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: 198kUpdated Claude CodeCodexVerifiedInstall
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: 196kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
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: 196kUpdated Claude CodeCodexVerifiedInstall