maactl 0.1.0 → 0.1.2

package/README.md

@@ -1,62 +1,64 @@
-# maactl (npm)
-
-通过 `npx` 运行 MaaCtl 的命令行客户端。这个包只是一个很薄的转发器：它负责找到
-`maactl.exe`（自带、缓存或按需下载），把命令行参数原样传给它，并把退出码回传给 shell。
-
-```powershell
-# 直接运行，无需全局安装
-npx maactl --version
-npx maactl adb devices
-npx maactl interface --tasks -f D:\01_Projects\github\MaaMio
-
-# 若某些 npx 版本吞掉了参数，用 -- 显式分隔
-npx maactl -- run task "自动挂机卖蛋" -f D:\01_Projects\github\MaaMio --stop-after 10s
-```
-
-`npx maactl ...` 之后的所有参数都会原样传给 `maactl.exe`，包括 `-f/--interface`、
-`--adb-address`、`--json` 等；工作目录也不会被改变，因此默认的 `./interface.json`
-仍然相对于你执行命令的目录解析。
-
-## 平台
-
-只提供 Windows amd64 的 `maactl.exe`（自带 MaaFramework 运行库）。包内声明了
-`"os": ["win32"]`，在其他系统上 npm 会以 `EBADPLATFORM` 拒绝安装。
-
-## maactl.exe 的来源
-
-按以下顺序查找，第一个命中的会被使用：
-
-1. 环境变量 `MAACTL_BINARY` 指向的文件；
-2. 包内的 `vendor/maactl.exe`（正式发布的 tarball 会携带）；
-3. 缓存 `%LOCALAPPDATA%\maactl\npm\<version>\maactl.exe`；
-4. 都找不到时，从对应版本的 GitHub Release 下载并校验后缓存（下次直接复用）。
-
-## 环境变量
-
-| 变量 | 作用 |
-| --- | --- |
-| `MAACTL_BINARY` | 指定要执行的 `maactl.exe`，跳过查找与下载。 |
-| `MAACTL_HOME` | 覆盖缓存根目录，默认 `%LOCALAPPDATA%\maactl`。 |
-| `MAACTL_VERSION` | 覆盖下载时使用的版本，默认取包的 `version`。 |
-| `MAACTL_BINARY_URL` | 直接指定下载地址，完全跳过 GitHub 拼接。 |
-| `MAACTL_MIRROR` | 镜像前缀，最终地址为 `<mirror>/https://github.com/<repo>/releases/download/<tag>/maactl.exe`。 |
-| `MAACTL_REPO` / `MAACTL_ASSET` | 覆盖仓库（默认 `TanyaShue/MaaCtl`）与资产名（默认 `maactl.exe`）。 |
-| `MAACTL_SKIP_DOWNLOAD=1` | 安装阶段不预下载，改为首次运行时下载。 |
-| `MAACTL_STRICT_INSTALL=1` | 预下载失败时让 `npm install` 直接失败。 |
-| `MAACTL_QUIET=1` | 静默模式，不输出下载进度。 |
-| `MAACTL_VERBOSE=1` | 输出实际使用的 `maactl.exe` 路径。 |
-| `MAACTL_LANG` | 包装器的提示语言（`zh_CN`/`en`），与 CLI 自身一致。 |
-
-## 从源码使用
-
-```powershell
-# 直接用 shim，无需安装
-node npm/bin/maactl.js --help
-
-# 或在本地安装为全局命令
-cd npm
-npm install -g .
-maactl --version
-```
-
-完整的命令说明见 [MaaCtl 主仓库](https://github.com/TanyaShue/MaaCtl#readme)。
+# maactl (npm)
+
+通过 `npx` 运行 MaaCtl 的命令行客户端。这个包只是一个很薄的转发器：它负责找到
+`maactl.exe`（自带、缓存或按需下载），把命令行参数原样传给它，并把退出码回传给 shell。
+
+```powershell
+# 直接运行，无需全局安装
+npx maactl --version
+npx maactl adb devices
+npx maactl interface --tasks -f D:\01_Projects\github\MaaMio
+
+# 若某些 npx 版本吞掉了参数，用 -- 显式分隔
+npx maactl -- run task "自动挂机卖蛋" -f D:\01_Projects\github\MaaMio --stop-after 10s
+```
+
+`npx maactl ...` 之后的所有参数都会原样传给 `maactl.exe`，包括 `-f/--interface`、
+`--adb-address`、`--json` 等；工作目录也不会被改变，因此默认的 `./interface.json`
+仍然相对于你执行命令的目录解析。
+
+## 平台
+
+只提供 Windows amd64 的 `maactl.exe`（自带 MaaFramework 运行库）。包内声明了
+`"os": ["win32"]`，在其他系统上 npm 会以 `EBADPLATFORM` 拒绝安装；同时声明了
+`"engines": { "node": ">=22" }`，因为包装器只用 Node 22 及以上提供的内置能力。
+
+## maactl.exe 的来源
+
+按以下顺序查找，第一个命中的会被使用：
+
+1. 环境变量 `MAACTL_BINARY` 指向的文件；
+2. 包内的 `vendor/maactl.exe`（正式发布的 tarball 会携带）；
+3. 缓存 `%LOCALAPPDATA%\maactl\npm\<version>\maactl.exe`；
+4. 都找不到时，从对应版本的 GitHub Release 下载并校验后缓存（下次直接复用）。
+
+## 环境变量
+
+| 变量 | 作用 |
+| --- | --- |
+| `MAACTL_BINARY` | 指定要执行的 `maactl.exe`，跳过查找与下载。 |
+| `MAACTL_HOME` | 覆盖缓存根目录，默认 `%LOCALAPPDATA%\maactl`。 |
+| `MAACTL_VERSION` | 覆盖下载时使用的版本，默认取包的 `version`。 |
+| `MAACTL_BINARY_URL` | 直接指定下载地址，完全跳过 GitHub 拼接。 |
+| `MAACTL_MIRROR` | 镜像前缀，最终地址为 `<mirror>/https://github.com/<repo>/releases/download/<tag>/maactl.exe`。 |
+| `MAACTL_REPO` / `MAACTL_ASSET` | 覆盖仓库（默认 `TanyaShue/MaaCtl`）与资产名（默认 `maactl.exe`）。 |
+| `MAACTL_SKIP_DOWNLOAD=1` | 安装阶段不预下载，改为首次运行时下载。 |
+| `MAACTL_STRICT_INSTALL=1` | 预下载失败时让 `npm install` 直接失败。 |
+| `MAACTL_QUIET=1` | 静默模式，不输出下载进度。 |
+| `MAACTL_VERBOSE=1` | 输出实际使用的 `maactl.exe` 路径。 |
+| `MAACTL_LANG` | 包装器的提示语言（`zh_CN`/`en`），与 CLI 自身一致。 |
+
+## 从源码使用
+
+```powershell
+# 直接用 shim，无需安装
+node npm/bin/maactl.js --help
+
+# 或在本地安装为全局命令
+cd npm
+npm install -g .
+maactl --version
+```
+
+完整的命令说明见 [MaaCtl 命令行参考](https://github.com/TanyaShue/MaaCtl/blob/main/docs/cli.md)，
+安装方式见 [主仓库 README](https://github.com/TanyaShue/MaaCtl#readme)。

package/bin/maactl.js

@@ -1,19 +1,19 @@
-#!/usr/bin/env node
-'use strict';
-
-// npm installs this file as the `maactl` command on Windows
-// (maactl.cmd / maactl.ps1 wrappers), so `npx maactl <args>` ends up here and
-// the arguments are forwarded to maactl.exe verbatim.
-
-const { main } = require('../lib/cli');
-const { MaactlError } = require('../lib/errors');
-
-main()
-  .then((code) => {
-    process.exitCode = code;
-  })
-  .catch((error) => {
-    const message = error instanceof MaactlError ? error.message : (error && error.stack) || String(error);
-    process.stderr.write(`${message}\n`);
-    process.exitCode = error instanceof MaactlError ? error.exitCode : 1;
-  });
+#!/usr/bin/env node
+'use strict';
+
+// npm installs this file as the `maactl` command on Windows
+// (maactl.cmd / maactl.ps1 wrappers), so `npx maactl <args>` ends up here and
+// the arguments are forwarded to maactl.exe verbatim.
+
+const { main } = require('../lib/cli');
+const { MaactlError } = require('../lib/errors');
+
+main()
+  .then((code) => {
+    process.exitCode = code;
+  })
+  .catch((error) => {
+    const message = error instanceof MaactlError ? error.message : (error && error.stack) || String(error);
+    process.stderr.write(`${message}\n`);
+    process.exitCode = error instanceof MaactlError ? error.exitCode : 1;
+  });

package/lib/binary.js

@@ -1,221 +1,221 @@
-'use strict';
-
-// Locating (and if necessary fetching) the maactl.exe the wrapper hands over to.
-//
-// Resolution order:
-//   1. MAACTL_BINARY            – an explicit path supplied by the user;
-//   2. <package>/vendor/maactl.exe – the executable published inside the tarball;
-//   3. <cache>/npm/<version>/maactl.exe – a previous download, reused across runs.
-//
-// When none of them exists the exe is downloaded from the GitHub release that
-// matches the package version, verified, and cached for the next run.
-
-const fs = require('node:fs');
-const os = require('node:os');
-const path = require('node:path');
-const { spawnSync } = require('node:child_process');
-
-const { downloadWithRetry, formatBytes, progressReporter } = require('./download');
-const env = require('./env');
-const { MaactlError } = require('./errors');
-const messages = require('./messages');
-
-const PACKAGE_ROOT = path.resolve(__dirname, '..');
-const PACKAGE = require(path.join(PACKAGE_ROOT, 'package.json'));
-
-// Every asset is a Windows PE binary; anything smaller than this floor is a
-// truncated download, an HTML error page or a git-lfs pointer.
-const MIN_BINARY_BYTES = 1 << 20;
-
-const EXE_NAME = 'maactl.exe';
-const DEFAULT_REPO = 'TanyaShue/MaaCtl';
-const DEFAULT_ASSET = 'maactl.exe';
-
-function version() {
-  return (env.value('MAACTL_VERSION') || PACKAGE.version).replace(/^v/, '');
-}
-
-function tag() {
-  return `v${version()}`;
-}
-
-function repo() {
-  return env.value('MAACTL_REPO') || DEFAULT_REPO;
-}
-
-function assetName() {
-  return env.value('MAACTL_ASSET') || DEFAULT_ASSET;
-}
-
-/** Cache root mirroring the CLI's own layout: %LOCALAPPDATA%\maactl on Windows. */
-function home() {
-  const explicit = env.value('MAACTL_HOME');
-  if (explicit) {
-    return path.resolve(explicit);
-  }
-  if (process.platform === 'win32') {
-    const localAppData = env.value('LOCALAPPDATA') || path.join(os.homedir(), 'AppData', 'Local');
-    return path.join(localAppData, 'maactl');
-  }
-  const cacheHome = env.value('XDG_CACHE_HOME') || path.join(os.homedir(), '.cache');
-  return path.join(cacheHome, 'maactl');
-}
-
-function cacheExePath(versionOverride) {
-  return path.join(home(), 'npm', versionOverride || version(), EXE_NAME);
-}
-
-function bundledExePath() {
-  return path.join(PACKAGE_ROOT, 'vendor', EXE_NAME);
-}
-
-function binaryUrl() {
-  const direct = env.value('MAACTL_BINARY_URL');
-  if (direct) {
-    return direct;
-  }
-  const github = `https://github.com/${repo()}/releases/download/${tag()}/${assetName()}`;
-  const mirror = env.value('MAACTL_MIRROR').replace(/\/+$/, '');
-  return mirror ? `${mirror}/${github}` : github;
-}
-
-function isUsable(file) {
-  try {
-    return fs.statSync(file).size > 0;
-  } catch {
-    return false;
-  }
-}
-
-/**
- * Return the path of an existing maactl.exe without touching the network, or
- * `null` when nothing is available locally.
- */
-function resolveBinary() {
-  const explicit = env.value('MAACTL_BINARY');
-  if (explicit) {
-    const resolved = path.resolve(explicit);
-    if (!fs.existsSync(resolved)) {
-      throw new MaactlError(messages.text('explicitMissing', resolved));
-    }
-    return resolved;
-  }
-
-  return [bundledExePath(), cacheExePath()].find(isUsable) || null;
-}
-
-/** Sanity-check a freshly downloaded executable by asking it for its version. */
-function verifyBinary(file, { spawn = spawnSync } = {}) {
-  const header = Buffer.alloc(2);
-  const fd = fs.openSync(file, 'r');
-  try {
-    fs.readSync(fd, header, 0, 2, 0);
-  } finally {
-    fs.closeSync(fd);
-  }
-  if (header.toString('latin1') !== 'MZ') {
-    throw new MaactlError(messages.text('verifyFailed', file, 'not a Windows PE executable'));
-  }
-  if (fs.statSync(file).size < MIN_BINARY_BYTES) {
-    throw new MaactlError(messages.text('verifyFailed', file, 'file is truncated'));
-  }
-
-  const result = spawn(file, ['--version'], {
-    encoding: 'utf8',
-    timeout: 60_000,
-    windowsHide: true,
-  });
-  const output = `${result.stdout || ''}${result.stderr || ''}`.trim();
-  if (result.error) {
-    throw new MaactlError(messages.text('verifyFailed', file, result.error.message), { cause: result.error });
-  }
-  if (result.status !== 0 || !/maactl/i.test(output)) {
-    throw new MaactlError(
-      messages.text('verifyFailed', file, `unexpected output: ${output || '(empty)'}`),
-    );
-  }
-  return output;
-}
-
-/**
- * Download maactl.exe into the cache unless a local copy already exists.
- * `write(text)` receives human readable progress lines; pass `quiet` to
- * suppress them.
- */
-async function ensureBinary({ write = () => {}, quiet = false, verify = verifyBinary } = {}) {
-  const existing = resolveBinary();
-  if (existing) {
-    return existing;
-  }
-
-  const dest = cacheExePath();
-  try {
-    fs.mkdirSync(path.dirname(dest), { recursive: true });
-  } catch (error) {
-    throw new MaactlError(`${messages.text('downloadFailed', binaryUrl(), error.message)}\n  cache: ${dest}`, {
-      cause: error,
-    });
-  }
-
-  const url = binaryUrl();
-  const showProgress = !quiet && Boolean(process.stderr.isTTY);
-  if (!quiet) {
-    write(messages.text('downloading', url));
-  }
-
-  const onProgress = showProgress ? progressReporter() : undefined;
-  try {
-    await downloadWithRetry(url, dest, {
-      onProgress,
-      onRetry: (attempt, attempts, error) => {
-        if (!quiet) {
-          write(`maactl: retrying download (${attempt}/${attempts - 1}) after: ${error.message}`);
-        }
-      },
-    });
-    if (onProgress) {
-      process.stderr.write('\n');
-    }
-    try {
-      verify(dest);
-    } catch (error) {
-      fs.rmSync(dest, { force: true });
-      throw error;
-    }
-  } catch (error) {
-    if (error instanceof MaactlError) {
-      throw error;
-    }
-    throw new MaactlError(messages.text('downloadFailed', url, error.message), { cause: error });
-  }
-
-  const size = formatBytes(fs.statSync(dest).size);
-  if (!quiet) {
-    write(messages.text('downloaded', size, dest));
-  }
-  return dest;
-}
-
-/** Print the exe the wrapper will hand over to, when MAACTL_VERBOSE is set. */
-function verbose() {
-  return env.flag('MAACTL_VERBOSE');
-}
-
-module.exports = {
-  PACKAGE,
-  PACKAGE_ROOT,
-  MIN_BINARY_BYTES,
-  EXE_NAME,
-  version,
-  tag,
-  repo,
-  assetName,
-  home,
-  cacheExePath,
-  bundledExePath,
-  binaryUrl,
-  resolveBinary,
-  ensureBinary,
-  verifyBinary,
-  verbose,
-};
+'use strict';
+
+// Locating (and if necessary fetching) the maactl.exe the wrapper hands over to.
+//
+// Resolution order:
+//   1. MAACTL_BINARY            – an explicit path supplied by the user;
+//   2. <package>/vendor/maactl.exe – the executable published inside the tarball;
+//   3. <cache>/npm/<version>/maactl.exe – a previous download, reused across runs.
+//
+// When none of them exists the exe is downloaded from the GitHub release that
+// matches the package version, verified, and cached for the next run.
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+
+const { downloadWithRetry, formatBytes, progressReporter } = require('./download');
+const env = require('./env');
+const { MaactlError } = require('./errors');
+const messages = require('./messages');
+
+const PACKAGE_ROOT = path.resolve(__dirname, '..');
+const PACKAGE = require(path.join(PACKAGE_ROOT, 'package.json'));
+
+// Every asset is a Windows PE binary; anything smaller than this floor is a
+// truncated download, an HTML error page or a git-lfs pointer.
+const MIN_BINARY_BYTES = 1 << 20;
+
+const EXE_NAME = 'maactl.exe';
+const DEFAULT_REPO = 'TanyaShue/MaaCtl';
+const DEFAULT_ASSET = 'maactl.exe';
+
+function version() {
+  return (env.value('MAACTL_VERSION') || PACKAGE.version).replace(/^v/, '');
+}
+
+function tag() {
+  return `v${version()}`;
+}
+
+function repo() {
+  return env.value('MAACTL_REPO') || DEFAULT_REPO;
+}
+
+function assetName() {
+  return env.value('MAACTL_ASSET') || DEFAULT_ASSET;
+}
+
+/** Cache root mirroring the CLI's own layout: %LOCALAPPDATA%\maactl on Windows. */
+function home() {
+  const explicit = env.value('MAACTL_HOME');
+  if (explicit) {
+    return path.resolve(explicit);
+  }
+  if (process.platform === 'win32') {
+    const localAppData = env.value('LOCALAPPDATA') || path.join(os.homedir(), 'AppData', 'Local');
+    return path.join(localAppData, 'maactl');
+  }
+  const cacheHome = env.value('XDG_CACHE_HOME') || path.join(os.homedir(), '.cache');
+  return path.join(cacheHome, 'maactl');
+}
+
+function cacheExePath(versionOverride) {
+  return path.join(home(), 'npm', versionOverride || version(), EXE_NAME);
+}
+
+function bundledExePath() {
+  return path.join(PACKAGE_ROOT, 'vendor', EXE_NAME);
+}
+
+function binaryUrl() {
+  const direct = env.value('MAACTL_BINARY_URL');
+  if (direct) {
+    return direct;
+  }
+  const github = `https://github.com/${repo()}/releases/download/${tag()}/${assetName()}`;
+  const mirror = env.value('MAACTL_MIRROR').replace(/\/+$/, '');
+  return mirror ? `${mirror}/${github}` : github;
+}
+
+function isUsable(file) {
+  try {
+    return fs.statSync(file).size > 0;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Return the path of an existing maactl.exe without touching the network, or
+ * `null` when nothing is available locally.
+ */
+function resolveBinary() {
+  const explicit = env.value('MAACTL_BINARY');
+  if (explicit) {
+    const resolved = path.resolve(explicit);
+    if (!fs.existsSync(resolved)) {
+      throw new MaactlError(messages.text('explicitMissing', resolved));
+    }
+    return resolved;
+  }
+
+  return [bundledExePath(), cacheExePath()].find(isUsable) || null;
+}
+
+/** Sanity-check a freshly downloaded executable by asking it for its version. */
+function verifyBinary(file, { spawn = spawnSync } = {}) {
+  const header = Buffer.alloc(2);
+  const fd = fs.openSync(file, 'r');
+  try {
+    fs.readSync(fd, header, 0, 2, 0);
+  } finally {
+    fs.closeSync(fd);
+  }
+  if (header.toString('latin1') !== 'MZ') {
+    throw new MaactlError(messages.text('verifyFailed', file, 'not a Windows PE executable'));
+  }
+  if (fs.statSync(file).size < MIN_BINARY_BYTES) {
+    throw new MaactlError(messages.text('verifyFailed', file, 'file is truncated'));
+  }
+
+  const result = spawn(file, ['--version'], {
+    encoding: 'utf8',
+    timeout: 60_000,
+    windowsHide: true,
+  });
+  const output = `${result.stdout || ''}${result.stderr || ''}`.trim();
+  if (result.error) {
+    throw new MaactlError(messages.text('verifyFailed', file, result.error.message), { cause: result.error });
+  }
+  if (result.status !== 0 || !/maactl/i.test(output)) {
+    throw new MaactlError(
+      messages.text('verifyFailed', file, `unexpected output: ${output || '(empty)'}`),
+    );
+  }
+  return output;
+}
+
+/**
+ * Download maactl.exe into the cache unless a local copy already exists.
+ * `write(text)` receives human readable progress lines; pass `quiet` to
+ * suppress them.
+ */
+async function ensureBinary({ write = () => {}, quiet = false, verify = verifyBinary } = {}) {
+  const existing = resolveBinary();
+  if (existing) {
+    return existing;
+  }
+
+  const dest = cacheExePath();
+  try {
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+  } catch (error) {
+    throw new MaactlError(`${messages.text('downloadFailed', binaryUrl(), error.message)}\n  cache: ${dest}`, {
+      cause: error,
+    });
+  }
+
+  const url = binaryUrl();
+  const showProgress = !quiet && Boolean(process.stderr.isTTY);
+  if (!quiet) {
+    write(messages.text('downloading', url));
+  }
+
+  const onProgress = showProgress ? progressReporter() : undefined;
+  try {
+    await downloadWithRetry(url, dest, {
+      onProgress,
+      onRetry: (attempt, attempts, error) => {
+        if (!quiet) {
+          write(`maactl: retrying download (${attempt}/${attempts - 1}) after: ${error.message}`);
+        }
+      },
+    });
+    if (onProgress) {
+      process.stderr.write('\n');
+    }
+    try {
+      verify(dest);
+    } catch (error) {
+      fs.rmSync(dest, { force: true });
+      throw error;
+    }
+  } catch (error) {
+    if (error instanceof MaactlError) {
+      throw error;
+    }
+    throw new MaactlError(messages.text('downloadFailed', url, error.message), { cause: error });
+  }
+
+  const size = formatBytes(fs.statSync(dest).size);
+  if (!quiet) {
+    write(messages.text('downloaded', size, dest));
+  }
+  return dest;
+}
+
+/** Print the exe the wrapper will hand over to, when MAACTL_VERBOSE is set. */
+function verbose() {
+  return env.flag('MAACTL_VERBOSE');
+}
+
+module.exports = {
+  PACKAGE,
+  PACKAGE_ROOT,
+  MIN_BINARY_BYTES,
+  EXE_NAME,
+  version,
+  tag,
+  repo,
+  assetName,
+  home,
+  cacheExePath,
+  bundledExePath,
+  binaryUrl,
+  resolveBinary,
+  ensureBinary,
+  verifyBinary,
+  verbose,
+};