wxa-runner 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 open-wxa
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,26 @@
-# Temporary Holding Version
+# wxa-runner
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+在普通浏览器里，用**微信官方基础库**运行小程序。为本地调试和 E2E 自动化测试而生。
+
+```bash
+npx wxa-runner dev ./dist/dev/mp-weixin   # 原生小程序目录，或 uni-app / Taro 编译产物
+# → http://localhost:3000
+```
+
+- 需要 Node.js ≥ 18。经常用或要在 CI 里跑，装成开发依赖：`pnpm add -D wxa-runner`
+- 基础库和编译器不用另外准备：本机有微信开发者工具就用它的，没有就用随依赖安装的内置版本。
+  内置基础库从 GitHub 安装，需要本机有 git、能访问 github.com
+- 目前只支持基础库 3.7.0 及以下
+
+| 命令 | 作用 |
+| --- | --- |
+| `wxa-runner dev <项目目录>` | 启动开发服务器，改动后热更新 |
+| `wxa-runner baselib list` | 列出可用的基础库及兼容性 |
+| `wxa-runner baselib extract [版本]` | 解包基础库（`dev` 会自动执行） |
+
+命令选项和环境变量见 [docs/cli.md](https://github.com/open-wxa/wxa-runner/blob/main/docs/cli.md)；
+跳过登录、热更新、在 Playwright 中测试见 [项目主页](https://github.com/open-wxa/wxa-runner#readme)。
+
+## 许可证
+
+MIT。内置基础库 [wxa-baselib](https://github.com/open-wxa/wxa-baselib) 是微信官方代码，版权归腾讯所有，不适用本项目的 MIT 协议。

package/bin/wxa-runner.js

@@ -0,0 +1,100 @@
+#!/usr/bin/env node
+
+const { Command } = require('commander');
+const chalk = require('chalk');
+const path = require('path');
+const { spawn } = require('child_process');
+
+const program = new Command();
+
+program
+  .name('wxa-runner')
+  .description('在浏览器中用官方基础库运行微信小程序')
+  .version(require('../package.json').version);
+
+program
+  .command('dev <project-path>')
+  .description('启动开发服务器')
+  .option('-p, --port <port>', '端口号', '3000')
+  .option('--host <host>', '监听地址', 'localhost')
+  .option('-b, --baselib <version>', '基础库版本（默认使用本机已安装的最新兼容版本）')
+  .option('--setup <file>', '小程序启动前执行的 setup 文件（默认使用项目目录下的 wxa.setup.ts / .js / .mjs）')
+  .option('--no-setup', '不执行 setup 文件')
+  .option('--no-watch', '不监听文件变化')
+  .option('-o, --open', '启动后打开浏览器')
+  .option('--real-login', '使用本机微信开发者工具登录态获取真实 code 和手机号')
+  .action(async (projectPath, options) => {
+    const { DevServer } = require('@open-wxa/wxa-runner-core');
+
+    try {
+      const server = new DevServer({
+        projectPath: path.resolve(process.cwd(), projectPath),
+        port: parseInt(options.port, 10),
+        host: options.host,
+        baseLibVersion: options.baselib,
+        setup: options.setup,
+        watch: options.watch,
+        realLogin: options.realLogin
+      });
+      const url = await server.start();
+
+      console.log('');
+      console.log(chalk.green('  wxa-runner 已启动'));
+      console.log(`  地址      ${chalk.cyan(url)}`);
+      console.log(`  项目      ${server.project.root}`);
+      console.log(`  基础库    ${server.baseLib.version}${server.baseLib.source === 'bundled' ? '（内置）' : ''}`);
+      if (server.setupFile) console.log(`  setup     ${server.setupFile}`);
+      console.log('');
+
+      if (options.open) openBrowser(url);
+
+      const shutdown = () => server.close().then(() => process.exit(0));
+      process.on('SIGINT', shutdown);
+      process.on('SIGTERM', shutdown);
+    } catch (error) {
+      console.error(chalk.red('\n启动失败：'), error.message);
+      process.exit(1);
+    }
+  });
+
+const baselib = program.command('baselib').description('管理官方基础库');
+
+baselib
+  .command('list')
+  .description('列出可用的基础库：本机微信开发者工具已下载的和内置的')
+  .action(() => {
+    const { listBaseLibs, MAX_COMPATIBLE_VERSION } = require('@open-wxa/wxa-runner-extractor');
+    const libs = listBaseLibs();
+    if (libs.length === 0) {
+      console.log(chalk.yellow('没有找到基础库，请先安装并打开一次微信开发者工具，或重新安装依赖以安装内置基础库'));
+      return;
+    }
+    const defaultLib = libs.find(lib => lib.compatible);
+    for (const lib of libs) {
+      const source = lib.source === 'bundled' ? chalk.cyan(' (内置)') : '';
+      const mark = lib === defaultLib ? chalk.green(' (默认)') : lib.compatible ? '' : chalk.gray(` (> ${MAX_COMPATIBLE_VERSION}，暂不支持)`);
+      console.log(`  ${lib.version}${source}${mark}`);
+    }
+  });
+
+baselib
+  .command('extract [version]')
+  .description('解包基础库到缓存目录（dev 命令会自动执行；内置基础库无需解包，直接输出所在目录）')
+  .action(version => {
+    const { resolveBaseLib } = require('@open-wxa/wxa-runner-extractor');
+    try {
+      const lib = resolveBaseLib({ version });
+      console.log(`${chalk.green('✓')} 基础库 ${lib.version} → ${lib.dir}`);
+    } catch (error) {
+      console.error(chalk.red(error.message));
+      process.exit(1);
+    }
+  });
+
+function openBrowser(url) {
+  const command = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'cmd' : 'xdg-open';
+  const args = process.platform === 'win32' ? ['/c', 'start', '', url] : [url];
+  spawn(command, args, { stdio: 'ignore', detached: true }).unref();
+}
+
+program.parse();

package/package.json

@@ -1,6 +1,46 @@
 {
   "name": "wxa-runner",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Run WeChat Mini Programs in the browser on the official base library, for debugging and E2E testing",
+  "keywords": [
+    "wechat",
+    "miniprogram",
+    "weapp",
+    "runtime",
+    "e2e",
+    "testing"
+  ],
+  "license": "MIT",
+  "author": "open-wxa",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/open-wxa/wxa-runner.git",
+    "directory": "packages/cli"
+  },
+  "homepage": "https://github.com/open-wxa/wxa-runner#readme",
+  "bugs": {
+    "url": "https://github.com/open-wxa/wxa-runner/issues"
+  },
+  "bin": {
+    "wxa-runner": "./bin/wxa-runner.js"
+  },
+  "files": [
+    "bin"
+  ],
+  "dependencies": {
+    "chalk": "^4.1.2",
+    "commander": "^11.1.0",
+    "@open-wxa/wxa-runner-core": "0.1.0",
+    "@open-wxa/wxa-runner-extractor": "0.1.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "dev": "node bin/wxa-runner.js"
+  }
 }