maactl 0.1.0

package/README.md

@@ -0,0 +1,62 @@
+# 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)。

package/bin/maactl.js

@@ -0,0 +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;
+  });

package/lib/binary.js

@@ -0,0 +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,
+};

package/lib/cli.js

@@ -0,0 +1,136 @@
+'use strict';
+
+// Thin launcher: hand every argument over to maactl.exe untouched, inherit the
+// stdio of the calling shell, and relay the exit status back to npm/npx.
+
+const { spawn } = require('node:child_process');
+
+const { resolveBinary, ensureBinary, verbose } = require('./binary');
+const env = require('./env');
+const { MaactlError } = require('./errors');
+const messages = require('./messages');
+
+// Signals worth relaying on POSIX hosts. On Windows the console broadcasts
+// Ctrl+C to the whole process group, so the Go process receives it directly.
+const POSIX_SIGNALS = ['SIGINT', 'SIGTERM', 'SIGQUIT', 'SIGHUP'];
+
+function describeSpawnError(file, error) {
+  const reason = error && error.message ? error.message : String(error);
+  return new MaactlError(messages.text('spawnFailed', file, reason), { cause: error });
+}
+
+/**
+ * Run `exe` with `argv`, inheriting stdio.
+ *
+ * Resolves with the numeric exit code of the child. When the child is killed
+ * by a signal on POSIX the shim re-raises that signal so the caller sees the
+ * same failure it would have seen without the wrapper.
+ */
+function runBinary(exe, argv, options = {}) {
+  const spawnImpl = options.spawn || spawn;
+  const proc = options.process || process;
+  const platform = options.platform || process.platform;
+  const child = spawnImpl(exe, argv, {
+    stdio: options.stdio || 'inherit',
+    cwd: options.cwd || process.cwd(),
+    env: options.env || process.env,
+    windowsHide: false,
+  });
+
+  return new Promise((resolve, reject) => {
+    const listeners = [];
+    const cleanup = () => {
+      for (const [signal, handler] of listeners) {
+        proc.removeListener(signal, handler);
+      }
+      listeners.length = 0;
+    };
+
+    child.once('error', (error) => {
+      cleanup();
+      reject(describeSpawnError(exe, error));
+    });
+    child.once('exit', (code, signal) => {
+      cleanup();
+      if (signal) {
+        try {
+          proc.kill(proc.pid, signal);
+        } catch {
+          // Re-raising is a courtesy; fall through to a generic failure code.
+        }
+        resolve(1);
+        return;
+      }
+      resolve(code === null || code === undefined ? 1 : code);
+    });
+
+    const forward = (signal) => {
+      if (child.exitCode !== null || child.signalCode !== null) {
+        return;
+      }
+      try {
+        child.kill(signal);
+      } catch {
+        // The child already exited; its exit handler reports the status.
+      }
+    };
+
+    if (platform === 'win32') {
+      // Windows has no POSIX signals: the console broadcasts Ctrl+C/Ctrl+Break
+      // to the whole process group, so maactl.exe already received it. Swallowing
+      // the first signal keeps the shim alive long enough to report the child's
+      // exit code; a second Ctrl+C falls back to the default behaviour and kills
+      // the shim, which is the escape hatch when the child will not stop.
+      const swallowOnce = () => cleanup();
+      for (const signal of ['SIGINT', 'SIGBREAK']) {
+        try {
+          proc.on(signal, swallowOnce);
+          listeners.push([signal, swallowOnce]);
+        } catch {
+          // Signal not supported on this platform.
+        }
+      }
+    } else {
+      for (const signal of POSIX_SIGNALS) {
+        const handler = () => forward(signal);
+        try {
+          proc.on(signal, handler);
+          listeners.push([signal, handler]);
+        } catch {
+          // Signal not supported on this platform.
+        }
+      }
+    }
+  });
+}
+
+/**
+ * Resolve (downloading once if needed) and run maactl.exe with `argv`.
+ *
+ * `argv` is forwarded verbatim, so `npx maactl run task "自动挂机卖蛋" -f D:\proj`
+ * reaches the executable exactly as typed.
+ */
+async function main(argv = process.argv.slice(2), options = {}) {
+  const write = options.write || ((line) => process.stderr.write(`${line}\n`));
+  const resolve = options.resolveBinary || resolveBinary;
+  const ensure = options.ensureBinary || ensureBinary;
+  const quiet = options.quiet ?? env.flag('MAACTL_QUIET');
+
+  let exe = options.binary || (await resolve());
+  if (!exe) {
+    try {
+      exe = await ensure({ write, quiet });
+    } catch (error) {
+      const detail = error instanceof MaactlError ? error.message : String(error && error.message);
+      throw new MaactlError(`${detail}\n${messages.text('resolveHint')}`, { cause: error });
+    }
+  }
+
+  if (verbose() && !options.binary) {
+    write(messages.text('usingBinary', exe));
+  }
+
+  return runBinary(exe, argv, options);
+}
+
+module.exports = { main, runBinary };

package/lib/download.js

@@ -0,0 +1,188 @@
+'use strict';
+
+// Minimal HTTPS downloader for the maactl.exe release asset.
+//
+// Node built-ins only: the npm package ships no runtime dependencies. GitHub
+// release downloads answer with a 302 to objects.githubusercontent.com, so
+// redirects are followed manually and the Authorization header (when a
+// GH_TOKEN is provided to dodge rate limits) is dropped on cross-host hops.
+
+const fs = require('node:fs');
+const http = require('node:http');
+const https = require('node:https');
+
+const MAX_REDIRECTS = 5;
+const REQUEST_TIMEOUT_MS = 60_000;
+// A slow-but-alive transfer is fine; a silent socket is not. If no bytes arrive
+// for this long the download is aborted with a readable error.
+const STALL_TIMEOUT_MS = 120_000;
+
+const REDIRECT_CODES = new Set([301, 302, 303, 307, 308]);
+
+function userAgent() {
+  const pkg = require('../package.json');
+  return `maactl-npm/${pkg.version} (node/${process.versions.node}; ${process.platform})`;
+}
+
+function githubToken() {
+  return (process.env.GH_TOKEN || process.env.GITHUB_TOKEN || '').trim();
+}
+
+function baseHeaders(url) {
+  const headers = {
+    'user-agent': userAgent(),
+    accept: 'application/octet-stream',
+  };
+  const token = githubToken();
+  if (token && /(^|\.)github\.com$/i.test(new URL(url).hostname)) {
+    headers.authorization = `Bearer ${token}`;
+  }
+  return headers;
+}
+
+function requestOnce(url, headers) {
+  return new Promise((resolve, reject) => {
+    const target = new URL(url);
+    const transport = target.protocol === 'http:' ? http : https;
+    const request = transport.get(target, { headers, timeout: REQUEST_TIMEOUT_MS }, (response) => {
+      response.setTimeout(STALL_TIMEOUT_MS);
+      response.on('timeout', () => {
+        response.destroy(new Error(`no data received for ${STALL_TIMEOUT_MS} ms`));
+      });
+      resolve(response);
+    });
+    request.on('timeout', () => request.destroy(new Error(`request timed out after ${REQUEST_TIMEOUT_MS} ms`)));
+    request.on('error', reject);
+  });
+}
+
+function writeBody(response, dest, onProgress) {
+  return new Promise((resolve, reject) => {
+    const total = Number(response.headers['content-length'] || 0);
+    let received = 0;
+    let finished = false;
+    const settle = (fn, value) => {
+      if (!finished) {
+        finished = true;
+        fn(value);
+      }
+    };
+    const output = fs.createWriteStream(dest);
+
+    response.on('data', (chunk) => {
+      received += chunk.length;
+      if (onProgress) {
+        onProgress(received, total);
+      }
+    });
+    response.on('error', (error) => settle(reject, error));
+    output.on('error', (error) => settle(reject, error));
+    output.on('finish', () => {
+      if (total > 0 && received !== total) {
+        settle(reject, new Error(`truncated download: received ${received} of ${total} bytes`));
+        return;
+      }
+      settle(resolve, received);
+    });
+    response.pipe(output);
+  });
+}
+
+/**
+ * Download `url` into `dest` (written to `dest.part` first, renamed on
+ * success). `onProgress(received, total)` is called for every chunk.
+ */
+async function download(url, dest, { onProgress } = {}) {
+  const partial = `${dest}.part`;
+  const headers = baseHeaders(url);
+  let current = url;
+
+  try {
+    for (let hop = 0; hop <= MAX_REDIRECTS; hop += 1) {
+      const response = await requestOnce(current, headers);
+      const status = response.statusCode || 0;
+
+      if (REDIRECT_CODES.has(status)) {
+        const location = response.headers.location;
+        response.resume();
+        if (!location) {
+          throw new Error(`HTTP ${status} without a Location header`);
+        }
+        const next = new URL(location, current);
+        if (next.hostname !== new URL(current).hostname) {
+          delete headers.authorization;
+        }
+        current = next.href;
+        continue;
+      }
+
+      if (status !== 200) {
+        response.resume();
+        throw new Error(`HTTP ${status} ${response.statusMessage || ''}`.trim());
+      }
+
+      await writeBody(response, partial, onProgress);
+      fs.renameSync(partial, dest);
+      return dest;
+    }
+    throw new Error(`too many redirects (limit ${MAX_REDIRECTS})`);
+  } catch (error) {
+    try {
+      fs.rmSync(partial, { force: true });
+    } catch {
+      // Best effort: a stale .part file only costs disk space.
+    }
+    throw error;
+  }
+}
+
+/** Try `download` up to `attempts` times, backing off between attempts. */
+async function downloadWithRetry(url, dest, options = {}) {
+  const attempts = options.attempts || 3;
+  const delay = options.retryDelayMs ?? 1_000;
+  let lastError;
+  for (let attempt = 1; attempt <= attempts; attempt += 1) {
+    try {
+      return await download(url, dest, options);
+    } catch (error) {
+      lastError = error;
+      if (attempt < attempts && options.onRetry) {
+        options.onRetry(attempt, attempts, error);
+      }
+      if (attempt < attempts) {
+        await new Promise((resolve) => setTimeout(resolve, delay * attempt));
+      }
+    }
+  }
+  throw lastError;
+}
+
+/** Human readable byte count, e.g. 34.2 MiB. */
+function formatBytes(bytes) {
+  if (!Number.isFinite(bytes) || bytes <= 0) {
+    return '0 B';
+  }
+  const units = ['B', 'KiB', 'MiB', 'GiB'];
+  let value = bytes;
+  let unit = 0;
+  while (value >= 1024 && unit < units.length - 1) {
+    value /= 1024;
+    unit += 1;
+  }
+  return `${value.toFixed(unit === 0 ? 0 : 1)} ${units[unit]}`;
+}
+
+/** Render a single-line progress indicator to stderr. */
+function progressReporter(stream = process.stderr) {
+  let lastLength = 0;
+  return (received, total) => {
+    const line = total > 0
+      ? `  ${formatBytes(received)} / ${formatBytes(total)} (${Math.floor((received / total) * 100)}%)`
+      : `  ${formatBytes(received)}`;
+    const padding = ' '.repeat(Math.max(0, lastLength - line.length));
+    lastLength = line.length;
+    stream.write(`\r${line}${padding}`);
+  };
+}
+
+module.exports = { download, downloadWithRetry, formatBytes, progressReporter, userAgent };

package/lib/env.js

@@ -0,0 +1,17 @@
+'use strict';
+
+// Small helpers so every module reads the environment the same way.
+
+const TRUTHY = new Set(['1', 'true', 'yes', 'on']);
+
+/** Trimmed value of an environment variable ('' when unset). */
+function value(name) {
+  return (process.env[name] || '').trim();
+}
+
+/** True when the variable is set to 1/true/yes/on (regardless of case). */
+function flag(name) {
+  return TRUTHY.has(value(name).toLowerCase());
+}
+
+module.exports = { value, flag };

package/lib/errors.js

@@ -0,0 +1,17 @@
+'use strict';
+
+/**
+ * Error type used for every failure raised by the npm wrapper itself.
+ *
+ * The wrapper never relays these to maactl.exe: they describe problems with
+ * locating, downloading or starting the executable.
+ */
+class MaactlError extends Error {
+  constructor(message, { exitCode = 1, cause } = {}) {
+    super(message, cause ? { cause } : undefined);
+    this.name = 'MaactlError';
+    this.exitCode = exitCode;
+  }
+}
+
+module.exports = { MaactlError };

package/lib/messages.js

@@ -0,0 +1,80 @@
+'use strict';
+
+// The wrapper only prints text for error and progress paths, so the message
+// catalogue stays small. Language follows MAACTL_LANG, the same variable the
+// CLI itself honours; anything not starting with "zh" falls back to English.
+
+const MESSAGES = {
+  zh: {
+    downloading: (url) => `maactl: 首次使用，正在下载 maactl.exe\n  ${url}`,
+    downloaded: (size, dest) => `maactl: 已下载 ${size} 到 ${dest}`,
+    downloadFailed: (url, reason) =>
+      `maactl: 下载 maactl.exe 失败\n  ${url}\n  原因: ${reason}`,
+    verifyFailed: (file, reason) => `maactl: 下载的 maactl.exe 校验失败 (${file})\n  原因: ${reason}`,
+    explicitMissing: (file) => `maactl: MAACTL_BINARY 指向的文件不存在: ${file}`,
+    spawnFailed: (file, reason) => `maactl: 无法启动 maactl.exe (${file})\n  原因: ${reason}`,
+    resolveHint: () =>
+      [
+        'maactl: 找不到 maactl.exe。可用的解决办法：',
+        '  1. 设置 MAACTL_BINARY 指向本地已有的 maactl.exe；',
+        '  2. 检查网络后重试，或设置 MAACTL_MIRROR 使用镜像下载；',
+        '  3. 手动下载 release 里的 maactl.exe，放到 %LOCALAPPDATA%\\maactl\\npm\\<version>\\ 下。',
+      ].join('\n'),
+    skippingDownload: () => 'maactl: 已跳过 maactl.exe 下载 (MAACTL_SKIP_DOWNLOAD)',
+    bundledMissing: (file) => `maactl: 未找到内置的 ${file}，改为下载 maactl.exe`,
+    preDownloadFailed: (reason) => `maactl: 预下载 maactl.exe 失败 (${reason})`,
+    preDownloadHint: () =>
+      'maactl: 改为首次运行时下载；设置 MAACTL_STRICT_INSTALL=1 可让安装在此处直接失败。',
+    usingBinary: (file) => `maactl: 使用 ${file}`,
+  },
+  en: {
+    downloading: (url) => `maactl: downloading maactl.exe for first use\n  ${url}`,
+    downloaded: (size, dest) => `maactl: downloaded ${size} to ${dest}`,
+    downloadFailed: (url, reason) => `maactl: could not download maactl.exe\n  ${url}\n  reason: ${reason}`,
+    verifyFailed: (file, reason) => `maactl: the downloaded maactl.exe failed verification (${file})\n  reason: ${reason}`,
+    explicitMissing: (file) => `maactl: MAACTL_BINARY points at a missing file: ${file}`,
+    spawnFailed: (file, reason) => `maactl: could not start maactl.exe (${file})\n  reason: ${reason}`,
+    resolveHint: () =>
+      [
+        'maactl: maactl.exe could not be located. Things to try:',
+        '  1. set MAACTL_BINARY to an existing maactl.exe;',
+        '  2. check your network and retry, or set MAACTL_MIRROR to use a mirror;',
+        '  3. download maactl.exe from the release page and place it in %LOCALAPPDATA%\\maactl\\npm\\<version>\\.',
+      ].join('\n'),
+    skippingDownload: () => 'maactl: skipped downloading maactl.exe (MAACTL_SKIP_DOWNLOAD)',
+    bundledMissing: (file) => `maactl: no bundled ${file}; fetching maactl.exe instead`,
+    preDownloadFailed: (reason) => `maactl: could not pre-download maactl.exe (${reason})`,
+    preDownloadHint: () =>
+      'maactl: it will be fetched on first run instead; set MAACTL_STRICT_INSTALL=1 to fail the install here.',
+    usingBinary: (file) => `maactl: using ${file}`,
+  },
+};
+
+function language() {
+  const explicit = (process.env.MAACTL_LANG || '').trim().toLowerCase();
+  if (explicit) {
+    return explicit.startsWith('zh') ? 'zh' : 'en';
+  }
+  if (process.platform !== 'win32') {
+    const posix = `${process.env.LC_ALL || ''}${process.env.LC_MESSAGES || ''}${process.env.LANG || ''}`.toLowerCase();
+    if (posix) {
+      return posix.includes('zh') ? 'zh' : 'en';
+    }
+  }
+  let locale = '';
+  try {
+    locale = Intl.DateTimeFormat().resolvedOptions().locale || '';
+  } catch {
+    locale = '';
+  }
+  return locale.toLowerCase().startsWith('zh') ? 'zh' : 'en';
+}
+
+/** Return the localized message for `key`, formatted with `args`. */
+function text(key, ...args) {
+  const catalogue = MESSAGES[language()] || MESSAGES.en;
+  const entry = catalogue[key] || MESSAGES.en[key];
+  return typeof entry === 'function' ? entry(...args) : String(entry ?? '');
+}
+
+module.exports = { text, language };

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "maactl",
+  "version": "0.1.0",
+  "description": "MaaFramework / ProjectInterface v2 command-line client, runnable with npx on Windows",
+  "keywords": [
+    "maactl",
+    "maafw",
+    "maaframework",
+    "projectinterface",
+    "automation",
+    "adb",
+    "cli"
+  ],
+  "license": "MIT",
+  "author": "TanyaShue",
+  "homepage": "https://github.com/TanyaShue/MaaCtl#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TanyaShue/MaaCtl.git",
+    "directory": "npm"
+  },
+  "bugs": {
+    "url": "https://github.com/TanyaShue/MaaCtl/issues"
+  },
+  "bin": {
+    "maactl": "bin/maactl.js"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "scripts/",
+    "vendor/",
+    "README.md"
+  ],
+  "scripts": {
+    "postinstall": "node scripts/install.js",
+    "vendor:binary": "node scripts/vendor-binary.js",
+    "check:vendor": "node scripts/vendor-binary.js --check",
+    "test": "node --test",
+    "prepublishOnly": "npm test && npm run check:vendor"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "os": [
+    "win32"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}

package/scripts/install.js

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+'use strict';
+
+// postinstall: pre-fetch maactl.exe into the user cache.
+//
+// The published tarball already carries vendor/maactl.exe, so this only runs
+// for installs without the bundled executable (git checkouts, `npm pack` from
+// source, custom MAACTL_ASSET builds). A download failure must never break
+// `npm install`: the shim retries lazily on first use. Set
+// MAACTL_STRICT_INSTALL=1 to turn the warning into an error.
+
+const { ensureBinary, resolveBinary, bundledExePath } = require('../lib/binary');
+const env = require('../lib/env');
+const messages = require('../lib/messages');
+
+function write(line) {
+  process.stderr.write(`${line}\n`);
+}
+
+async function install() {
+  if (env.flag('MAACTL_SKIP_DOWNLOAD')) {
+    write(messages.text('skippingDownload'));
+    return;
+  }
+
+  // resolveBinary() may throw when MAACTL_BINARY is set to a missing path, and
+  // that is a configuration error the user should see right away.
+  if (resolveBinary()) {
+    return; // bundled or cached executable is already in place
+  }
+
+  try {
+    write(messages.text('bundledMissing', bundledExePath()));
+    await ensureBinary({ write, quiet: false });
+  } catch (error) {
+    const strict = env.flag('MAACTL_STRICT_INSTALL');
+    if (strict) {
+      throw error;
+    }
+    write(messages.text('preDownloadFailed', error.message));
+    write(messages.text('preDownloadHint'));
+  }
+}
+
+install().catch((error) => {
+  write(`maactl: install step failed: ${error.message}`);
+  process.exitCode = 1;
+});

package/scripts/vendor-binary.js

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+'use strict';
+
+// Copy a locally built maactl.exe into vendor/ so `npm pack` / `npm publish`
+// produce a tarball that needs no download at install time.
+//
+// The release workflow calls this with the exe it just built; developers can
+// call it with the exe from `go build` to test the packaging flow offline.
+//
+//   node scripts/vendor-binary.js [path-to-exe]        # default: ../maactl.exe
+//   node scripts/vendor-binary.js --list               # show the current state
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { bundledExePath, verifyBinary, EXE_NAME } = require('../lib/binary');
+const { formatBytes } = require('../lib/download');
+
+const ROOT = path.resolve(__dirname, '..');
+
+function usage() {
+  process.stderr.write(
+    [
+      `usage: node scripts/vendor-binary.js [<maactl.exe>] [--check]`,
+      '',
+      `Copies <maactl.exe> (default ${path.join(ROOT, '..', EXE_NAME)}) to ${bundledExePath()}.`,
+      'Use --check to verify the vendored executable without copying anything.',
+      '',
+    ].join('\n'),
+  );
+}
+
+function main(argv) {
+  const args = argv.filter((arg) => !arg.startsWith('--'));
+  const check = argv.includes('--check');
+  const source = path.resolve(args[0] || path.join(ROOT, '..', EXE_NAME));
+  const dest = bundledExePath();
+
+  if (argv.includes('--help') || argv.includes('-h')) {
+    usage();
+    return 0;
+  }
+
+  if (!check) {
+    if (!fs.existsSync(source)) {
+      throw new Error(`source executable not found: ${source}\nbuild it first: go build -tags bundled -o maactl.exe ./cmd/maactl`);
+    }
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    fs.copyFileSync(source, dest);
+  }
+
+  if (!fs.existsSync(dest)) {
+    throw new Error(`no vendored executable at ${dest}`);
+  }
+
+  const version = verifyBinary(dest);
+  const size = formatBytes(fs.statSync(dest).size);
+  process.stdout.write(`vendored ${dest}\n  ${size}\n  ${version}\n`);
+  return 0;
+}
+
+try {
+  process.exitCode = main(process.argv.slice(2));
+} catch (error) {
+  process.stderr.write(`vendor-binary: ${error.message}\n`);
+  process.exitCode = 1;
+}