@leonxin/meetgames 0.1.7 → 0.1.11

package/docs/{ → archive/product/}/346/212/200/346/234/257/346/226/271/346/241/210/350/260/203/347/240/224.md

@@ -86,7 +86,7 @@ PRD「AST 替代正则」指 **后续 Groovy Gradle 编辑** 与 **游戏源码
 | 接口 | 路径 | 鉴权 | 返回 | 工具 |
 |------|------|------|------|------|
 | 老接口 | `GET /openSDK/getSDKConfig` | sign + timestamp | `channelAuthConfig` 片段 | 库内保留映射，CLI 不用 |
-| **新接口（采用）** | `GET /console/openSDK/downloadSDKConfig` | 仅 `appId` + `channelType` | 完整 `meetsdk-remote-config.json` | **`fetch-config`** |
+| **新接口（采用）** | `GET /console/openSDK/downloadSDKConfig` | sign + timestamp | 完整 `meetsdk-remote-config.json` | **`fetch-config`** |
 | 老接口 | `GET /openSDK/getSDKConfig` | sign | `channelAuthConfig` 片段 | 不用于 CLI 拉参 |
 
 JSON 内渠道字段：**根级 `channel` only**（无 `channelType`、无 `topsdk.channel`）。
@@ -182,7 +182,7 @@ flowchart LR
 
 ### 5.3 Firebase
 
-- `firebase_file_url` 在 analytics.firebase 对象中；  
+- `firebaseUrl` 在 analytics.firebase 对象中；  
 - 集成时拉取或引用 URL（具体拷贝逻辑见 recipe / firebase 相关 op）。
 
 ---
@@ -251,14 +251,14 @@ meetgames fetch-config --project-root <原生工程根> \
   --app-id <APP_ID> --channel-type GOOGLE --env test
 
 meetgames setup --project-root <原生工程根> \
-  --app-id <APP_ID> --channel-type GOOGLE
+  --app-id <APP_ID> --app-secret <APP_SECRET> --channel-type GOOGLE
 ```
 
 | 说明 | |
 |------|--|
 | `channel-type` | 商店渠道枚举，对应 HTTP 参数 `channelType` |
-| `app-secret` | **不必**在 fetch-config 传入；由 `downloadSDKConfig` 响应写入 JSON |
-| CI | 设置 `TOPSDK_APP_ID`、`TOPSDK_CHANNEL_TYPE` 或依赖已提交的 JSON 缓存 |
+| `app-secret` | **必须**在 fetch-config/setup 传入，或通过 `TOPSDK_APP_SECRET` 设置；仅用于计算 `sign` |
+| CI | 设置 `TOPSDK_APP_ID`、`TOPSDK_APP_SECRET`、`TOPSDK_CHANNEL_TYPE` 或依赖已提交的 JSON 缓存 |
 
 ### 7.2 MCP（MVP）
 
@@ -276,7 +276,7 @@ meetgames setup --project-root <原生工程根> \
 | 项 | 技术要点 |
 |----|----------|
 | 渠道配置下载 | 与 `downloadSDKConfig` 字节流一致，避免前端再拼 JSON |
-| 三方文件 | 对象存储原文件 + 下载 URL 写入 JSON（如 `firebase_file_url`） |
+| 三方文件 | 对象存储原文件 + 下载 URL 写入 JSON（如 `firebaseUrl`） |
 | SDK 版本 | 后台配置 → 下发或随工具 `meetsdk-android.json` 同步策略 **【待与发版流程对齐】** |
 | 后台改 JSON 字段 | 与工具约定根级 `channel`，避免回退 `topsdk.channel` |
 
@@ -300,7 +300,7 @@ meetgames setup --project-root <原生工程根> \
 | 层级 | 内容 |
 |------|------|
 | 单元 | Gradle upsert、JSON 解析、Manifest |
-| 集成 | `test-projects/android-sample`、`pipeline.*.test.ts` |
+| 集成 | `fixtures/android-test-project/android-latest-project`、`fixtures/android-test-project/power-raid`、`pipeline.*.test.ts` |
 | CI 建议 | `npm ci && npm test && meetgames setup --dry-run`（需 secrets 与 API 可用） |
 
 **宿主限制**：流水线仅针对标准 Android **Groovy** Gradle / Xcode 原生工程；**不支持** `build.gradle.kts`；Unity / Unreal 不在支持矩阵内。

package/docs/{ → archive/product/}/351/234/200/346/261/202/346/226/207/346/241/243.md

@@ -143,19 +143,20 @@ dependencies {
 |------|------|
 | `--project-root` | 游戏工程根路径 |
 | `--app-id` | MG / TOPSDK 应用 ID |
+| `--app-secret` | 应用密钥，仅用于本地计算 `downloadSDKConfig` 的 `sign`，不会从本地缓存读取 |
 | `--channel-type` | 商店渠道：`GOOGLE` / `APPLE` 等（HTTP 查询参数，非 android/ios） |
 | `--env` | `prod` / `pre` / `test` |
 
-说明：`downloadSDKConfig` **无需** CLI 传 `appSecret`，密钥由接口写入 JSON 的 `topsdk.appSecret`。旧文档中的 `--app-secret` 仅适用于已废弃的 `getSDKConfig` 签名流程。
+说明：`downloadSDKConfig` **必须**带 `sign` / `timestamp`。`sign = base64(md5(appId + appSecret + timestamp))`，`appSecret` 通过 `--app-secret` 或 `TOPSDK_APP_SECRET` 传入，仅用于签名；工具不会从本地 `meetsdk-remote-config.json` 读取密钥再签名。
 
 ```bash
 # 仅拉配置
 meetgames fetch-config --project-root . \
-  --app-id "$SDK_APP_ID" --channel-type GOOGLE --env test
+  --app-id "$SDK_APP_ID" --app-secret "$SDK_APP_SECRET" --channel-type GOOGLE --env test
 
 # 拉配置 + 集成（推荐流水线）
 meetgames setup --project-root . \
-  --app-id "$SDK_APP_ID" --channel-type GOOGLE --env test
+  --app-id "$SDK_APP_ID" --app-secret "$SDK_APP_SECRET" --channel-type GOOGLE --env test
 
 # 仅集成（已有 meetsdk-remote-config.json）
 meetgames integrate --project-root . --dry-run
@@ -199,18 +200,18 @@ meetgames integrate --project-root . --dry-run
       "guest": {},
       "email": {},
       "facebook": {
-        "facebookAppId": "0000000000000000",
-        "fbLoginProtocolScheme": "fb0000000000000000",
-        "facebookClientToken": "mockfacebookclienttoken00000000"
+        "clientId": "0000000000000000",
+        "scheme": "fb0000000000000000",
+        "secret": "mockfacebookclienttoken00000000"
       },
-      "google": { "googleClientId": "mock-client-id.apps.googleusercontent.com" }
+      "google": { "clientId": "mock-client-id.apps.googleusercontent.com" }
     },
     "payment": { "googleIap": {} },
     "analytics": {
-      "appsflyer": { "enableDebugLog": true, "devKey": "MOCK_APPSFLYER_DEV_KEY" },
+      "appsflyer": { "devKey": "MOCK_APPSFLYER_DEV_KEY" },
       "facebookdata": {},
-      "firebase": { "firebase_file_url": "https://example.invalid/firebase/google-services.json" },
-      "adjust": { "appId": "MOCK_ADJUST_APP_ID" }
+      "firebase": { "firebaseUrl": "https://example.invalid/firebase/google-services.json" },
+      "adjust": { "appCode": "MOCK_ADJUST_APP_ID" }
     }
   }
 }
@@ -241,15 +242,15 @@ meetgames integrate --project-root . --dry-run
 | 项 | 内容 |
 |----|------|
 | **新接口** | `GET {baseUrl}console/openSDK/downloadSDKConfig` |
-| **Query** | `appId`、`channelType`（商店渠道，如 `GOOGLE` / `APPLE`） |
-| **鉴权** | 无需 sign |
+| **Query** | `appId`、`channelType`（商店渠道，如 `GOOGLE` / `APPLE`）、`sign`、`timestamp` |
+| **鉴权** | 必须带 `sign + timestamp`，签名算法与 `getSDKConfig` 一致 |
 | **响应** | 响应体即为 `meetsdk-remote-config.json` 全文（附件下载） |
 | **CLI** | `meetgames fetch-config` / `meetgames setup` |
 
 示例：
 
 ```http
-GET https://{api-sdk-gameplus-host}/console/openSDK/downloadSDKConfig?appId=791251136341225472&channelType=GOOGLE
+GET https://{api-sdk-gameplus-host}/console/openSDK/downloadSDKConfig?appId=791251136341225472&channelType=GOOGLE&sign=...&timestamp=...
 ```
 
 响应 JSON **必须**含根级 `channel`（与 `channelType` 查询值一致）、`devicePlatform`，且 **`topsdk` 内不含 `channel`**。
@@ -304,7 +305,7 @@ GET https://{api-sdk-gameplus-host}/console/openSDK/downloadSDKConfig?appId=7912
 |------|------|
 | 接口调用诊断 | 对约定 API 列表输出静态检查报告 |
 | Snapchat Manifest placeholders | 与 PRD 示例一致的 `addManifestPlaceholders` |
-| 三方配置文件原文件下载 | OSS 直链写入 JSON（如 `firebase_file_url`） |
+| 三方配置文件原文件下载 | OSS 直链写入 JSON（如 `firebaseUrl`） |
 | 接入客服 | 可回答 FAQ 范围内接入问题 |
 
 ---

package/logs/convert-20260622-155037.log

@@ -0,0 +1,5 @@
+[2026-06-22T07:50:37.206Z] [INFO] AAB: /Users/work/Workspace/Projects/meet-sdk-tool/test-assets/aab-converter/sample.aab
+[2026-06-22T07:50:37.206Z] [INFO] Output directory: /private/tmp/aab2apk-out
+[2026-06-22T07:50:37.206Z] [INFO] APK set: /private/tmp/aab2apk-out/sample.apks
+[2026-06-22T07:50:37.206Z] [INFO] Output APK: /private/tmp/aab2apk-out/sample_universal.apk
+[2026-06-22T07:50:37.207Z] [INFO] Running bundletool: java -jar /Users/work/Workspace/Projects/meet-sdk-tool/tools/bundletool.jar build-apks --bundle=/Users/work/Workspace/Projects/meet-sdk-tool/test-assets/aab-converter/sample.aab --output=/private/tmp/aab2apk-out/sample.apks --mode=universal --ks=/Users/work/Workspace/Projects/meet-sdk-tool/test-assets/aab-converter/dragonstone.jks --ks-key-alias=dragonstone --ks-pass=pass:****** --key-pass=pass:****** --overwrite

package/logs/convert-20260622-155226.log

@@ -0,0 +1,6 @@
+[2026-06-22T07:52:26.222Z] [INFO] AAB: /Users/work/Workspace/Projects/meet-sdk-tool/test-assets/aab-converter/sample.aab
+[2026-06-22T07:52:26.222Z] [INFO] Output directory: /private/tmp/aab2apk-out
+[2026-06-22T07:52:26.222Z] [INFO] APK set: /private/tmp/aab2apk-out/sample.apks
+[2026-06-22T07:52:26.222Z] [INFO] Output APK: /private/tmp/aab2apk-out/sample_universal.apk
+[2026-06-22T07:52:26.222Z] [INFO] Running bundletool: java -jar /Users/work/Workspace/Projects/meet-sdk-tool/tools/bundletool.jar build-apks --bundle=/Users/work/Workspace/Projects/meet-sdk-tool/test-assets/aab-converter/sample.aab --output=/private/tmp/aab2apk-out/sample.apks --mode=universal --ks=/Users/work/Workspace/Projects/meet-sdk-tool/test-assets/aab-converter/dragonstone.jks --ks-key-alias=dragonstone --ks-pass=pass:****** --key-pass=pass:****** --overwrite
+[2026-06-22T07:52:58.806Z] [INFO] Extracted universal APK: /private/tmp/aab2apk-out/sample_universal.apk

package/meetsdk-android.json

@@ -1,6 +1,7 @@
 {
   "topsdk": {
-    "version": "1.6.1.4",
+    "version": "1.6.1.3",
+    "date": "2026-05-25",
     "groupId": "com.sino.topsdk",
     "repositories": [
       "https://storage-sdk-gameplus.meetsocial.com/repository/TopSdk/"

package/meetsdk-ios.json

@@ -0,0 +1,15 @@
+{
+  "topsdk": {
+    "version": "1.6.0.5",
+    "date": "2026-06-09",
+    "packageType": "native",
+    "plugins": [
+      "guest",
+      "facebook",
+      "google",
+      "apple",
+      "apple_pay",
+      "dataAppsFlyer"
+    ]
+  }
+}

package/package.json

@@ -1,50 +1,25 @@
 {
   "name": "@leonxin/meetgames",
-  "version": "0.1.7",
-  "description": "Meet SDK integration CLI: fetch remote config, patch Android Gradle/Manifest and iOS Xcode projects (dry-run, patch output, MCP)",
-  "type": "module",
+  "version": "0.1.11",
   "license": "MIT",
-  "author": "MeetSocial",
-  "keywords": [
-    "meetgames",
-    "meet-sdk",
-    "topsdk",
-    "android",
-    "ios",
-    "gradle",
-    "xcode",
-    "sdk-integration"
-  ],
-  "publishConfig": {
-    "access": "public"
-  },
+  "type": "module",
   "bin": {
-    "meetgames": "./dist/entry.js",
-    "meetgames-mcp": "./dist/mcp-entry.js"
+    "meetgames": "dist/entry.js",
+    "meetgames-mcp": "dist/mcp-entry.js",
+    "meetgames-aab": "dist/aab-converter/aab-entry.js"
   },
-  "files": [
-    "dist",
-    "schema",
-    "bundled/android",
-    "docs",
-    "recipes",
-    "fixtures",
-    "meetsdk-android.json"
-  ],
   "scripts": {
     "build": "tsc -p tsconfig.json",
+    "build:aab": "tsc -p tsconfig.json",
+    "package:aab-win-zip": "node scripts/package-aab-cli-win.mjs",
     "test": "vitest run",
-    "test:watch": "vitest",
-    "prepack": "npm run build",
-    "preview:integrate:android-sample": "npm run build -s && node dist/entry.js integrate --project-root test-projects/android-sample --dry-run --verbose --patch-file test-projects/_preview/cli-preview.patch",
-    "mcp:stdio": "npm run build -s && node dist/mcp-entry.js"
+    "test:mcp": "npm run build && npm run test:mcp:run",
+    "test:mcp:run": "vitest run --config vitest.mcp.config.ts",
+    "test:regression": "npm run build && npm test && npm run test:mcp:run"
   },
   "engines": {
     "node": ">=18"
   },
-  "overrides": {
-    "uuid": "^14.0.0"
-  },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
     "ajv": "^8.17.1",

package/scripts/package-aab-cli-win.mjs

@@ -0,0 +1,193 @@
+import fs from "node:fs";
+import path from "node:path";
+import zlib from "node:zlib";
+
+const root = process.cwd();
+const productName = "MeetSDKTool-AABConverter-win-x64";
+const releaseDir = path.join(root, "release");
+const stagingDir = path.join(releaseDir, productName);
+const zipPath = path.join(releaseDir, `${productName}.zip`);
+
+function fail(message) {
+  console.error(`[package:aab-win-zip] ERROR: ${message}`);
+  process.exit(1);
+}
+
+function assertExists(p, label) {
+  if (!fs.existsSync(p)) fail(`${label} not found: ${p}`);
+}
+
+function copyDir(src, dest) {
+  assertExists(src, "Source directory");
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  fs.cpSync(src, dest, { recursive: true });
+}
+
+function copyFileIfExists(src, dest) {
+  if (!fs.existsSync(src)) return;
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  fs.copyFileSync(src, dest);
+}
+
+function copyNodeRuntime(src, dest) {
+  assertExists(path.join(src, "node.exe"), "Windows node.exe");
+  fs.mkdirSync(dest, { recursive: true });
+  fs.copyFileSync(path.join(src, "node.exe"), path.join(dest, "node.exe"));
+  copyFileIfExists(path.join(src, "LICENSE"), path.join(dest, "LICENSE"));
+  copyFileIfExists(path.join(src, "README.md"), path.join(dest, "README.md"));
+}
+
+function writeCmd() {
+  const cmd = [
+    "@echo off",
+    "setlocal",
+    'set "TOOL_DIR=%~dp0"',
+    '"%TOOL_DIR%runtime\\node\\node.exe" "%TOOL_DIR%app\\aab-converter\\aab-entry.js" %*',
+    "exit /b %ERRORLEVEL%",
+    "",
+  ].join("\r\n");
+  fs.writeFileSync(path.join(stagingDir, "aab2apk.cmd"), cmd, "utf8");
+}
+
+function crc32(buf) {
+  let crc = 0xffffffff;
+  for (const b of buf) {
+    crc ^= b;
+    for (let i = 0; i < 8; i += 1) {
+      crc = (crc >>> 1) ^ (0xedb88320 & -(crc & 1));
+    }
+  }
+  return (crc ^ 0xffffffff) >>> 0;
+}
+
+function u16(value) {
+  const buf = Buffer.alloc(2);
+  buf.writeUInt16LE(value);
+  return buf;
+}
+
+function u32(value) {
+  const buf = Buffer.alloc(4);
+  buf.writeUInt32LE(value);
+  return buf;
+}
+
+function listEntries(baseDir) {
+  const out = [];
+  function walk(abs, rel) {
+    const stat = fs.statSync(abs);
+    if (stat.isDirectory()) {
+      if (rel) out.push({ rel: `${rel}/`, dir: true, content: Buffer.alloc(0) });
+      for (const name of fs.readdirSync(abs).sort()) {
+        if (name === ".DS_Store" || name === "__MACOSX") continue;
+        walk(path.join(abs, name), rel ? `${rel}/${name}` : name);
+      }
+      return;
+    }
+    if (stat.isFile()) {
+      out.push({ rel, dir: false, content: fs.readFileSync(abs) });
+    }
+  }
+  walk(baseDir, productName);
+  return out;
+}
+
+function writeZip(baseDir, outPath) {
+  const entries = listEntries(baseDir);
+  const localParts = [];
+  const centralParts = [];
+  let offset = 0;
+  for (const entry of entries) {
+    const name = Buffer.from(entry.rel, "utf8");
+    const compressed = entry.dir ? Buffer.alloc(0) : zlib.deflateRawSync(entry.content);
+    const method = entry.dir ? 0 : 8;
+    const crc = entry.dir ? 0 : crc32(entry.content);
+    const local = Buffer.concat([
+      u32(0x04034b50),
+      u16(20),
+      u16(0),
+      u16(method),
+      u16(0),
+      u16(0),
+      u32(crc),
+      u32(compressed.length),
+      u32(entry.content.length),
+      u16(name.length),
+      u16(0),
+      name,
+      compressed,
+    ]);
+    localParts.push(local);
+    centralParts.push(
+      Buffer.concat([
+        u32(0x02014b50),
+        u16(20),
+        u16(20),
+        u16(0),
+        u16(method),
+        u16(0),
+        u16(0),
+        u32(crc),
+        u32(compressed.length),
+        u32(entry.content.length),
+        u16(name.length),
+        u16(0),
+        u16(0),
+        u16(0),
+        u16(0),
+        u32(entry.dir ? 0x10 : 0),
+        u32(offset),
+        name,
+      ])
+    );
+    offset += local.length;
+  }
+  const centralDir = Buffer.concat(centralParts);
+  const eocd = Buffer.concat([
+    u32(0x06054b50),
+    u16(0),
+    u16(0),
+    u16(entries.length),
+    u16(entries.length),
+    u32(centralDir.length),
+    u32(offset),
+    u16(0),
+  ]);
+  fs.writeFileSync(outPath, Buffer.concat([...localParts, centralDir, eocd]));
+}
+
+assertExists(path.join(root, "dist", "aab-converter", "aab-entry.js"), "Compiled AAB CLI entry");
+assertExists(path.join(root, "dist", "shared"), "Compiled shared modules");
+assertExists(path.join(root, "tools", "bundletool.jar"), "bundletool.jar");
+assertExists(path.join(root, "runtime", "win-x64", "node", "node.exe"), "Windows node.exe");
+assertExists(path.join(root, "runtime", "win-x64", "jre", "bin", "java.exe"), "Windows JRE java.exe");
+
+fs.rmSync(stagingDir, { recursive: true, force: true });
+fs.rmSync(zipPath, { force: true });
+fs.mkdirSync(stagingDir, { recursive: true });
+
+copyDir(path.join(root, "dist", "aab-converter"), path.join(stagingDir, "app", "aab-converter"));
+copyDir(path.join(root, "dist", "shared"), path.join(stagingDir, "app", "shared"));
+copyNodeRuntime(path.join(root, "runtime", "win-x64", "node"), path.join(stagingDir, "runtime", "node"));
+copyDir(path.join(root, "runtime", "win-x64", "jre"), path.join(stagingDir, "runtime", "jre"));
+fs.mkdirSync(path.join(stagingDir, "tools"), { recursive: true });
+fs.copyFileSync(path.join(root, "tools", "bundletool.jar"), path.join(stagingDir, "tools", "bundletool.jar"));
+fs.mkdirSync(path.join(stagingDir, "logs"), { recursive: true });
+fs.mkdirSync(path.join(stagingDir, "output"), { recursive: true });
+writeCmd();
+fs.writeFileSync(
+  path.join(stagingDir, "README.txt"),
+  [
+    "Meet SDK AAB Converter",
+    "",
+    "Example:",
+    "  set KS_PASS=your_keystore_password",
+    "  set KEY_PASS=your_key_password",
+    "  aab2apk.cmd convert --aab D:\\packages\\game.aab --out-dir D:\\output --ks D:\\keys\\release.jks --ks-key-alias release --ks-pass-env KS_PASS --key-pass-env KEY_PASS",
+    "",
+  ].join("\r\n"),
+  "utf8"
+);
+
+writeZip(stagingDir, zipPath);
+console.log(`[package:aab-win-zip] wrote ${zipPath}`);

package/src/aab-converter/aab-entry.ts

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+import path from "node:path";
+import { UserFacingError, errorMessage } from "../shared/errors.js";
+import { createFileLogger } from "../shared/logger.js";
+import { convertAabToApk } from "./convertAabToApk.js";
+import { parseAabCliArgv, printAabHelp, validateConvertArgs } from "./cliArgs.js";
+import { resolveBundletoolPath, resolveJavaPath, resolveToolRoot } from "./resourcePaths.js";
+
+const EXIT = {
+  OK: 0,
+  INVALID_ARGS: 2,
+  CONVERT_FAILED: 3,
+} as const;
+
+export async function main(): Promise<void> {
+  const parsed = parseAabCliArgv(process.argv);
+  if (parsed.help) {
+    printAabHelp();
+    process.exit(EXIT.OK);
+  }
+
+  const toolRoot = resolveToolRoot(import.meta.url);
+  const convertArgs = validateConvertArgs(parsed);
+  const logger = createFileLogger(path.join(toolRoot, "logs"));
+  try {
+    const result = await convertAabToApk({
+      ...convertArgs,
+      javaPath: resolveJavaPath(toolRoot),
+      bundletoolPath: resolveBundletoolPath(toolRoot),
+      logger,
+    });
+    console.log(`[aab2apk] APK: ${result.apkPath}`);
+    if (result.apksPath) console.log(`[aab2apk] APKS: ${result.apksPath}`);
+    if (result.logPath) console.log(`[aab2apk] Log: ${result.logPath}`);
+  } finally {
+    logger.close();
+  }
+}
+
+main().catch((err: unknown) => {
+  if (err instanceof UserFacingError) {
+    console.error(`[aab2apk] ERROR (${err.code}): ${err.message}`);
+    if (err.details) console.error(err.details);
+    process.exit(err.code === "INVALID_ARGS" || err.code === "INVALID_COMMAND" ? EXIT.INVALID_ARGS : EXIT.CONVERT_FAILED);
+  }
+  console.error(`[aab2apk] ERROR: ${errorMessage(err)}`);
+  process.exit(EXIT.CONVERT_FAILED);
+});

package/src/aab-converter/apksExtractor.ts

@@ -0,0 +1,119 @@
+import fs from "node:fs";
+import path from "node:path";
+import zlib from "node:zlib";
+import { UserFacingError } from "../shared/errors.js";
+import { assertCanWriteFile } from "../shared/fileUtils.js";
+
+interface ZipEntry {
+  name: string;
+  method: number;
+  compressedSize: number;
+  localHeaderOffset: number;
+}
+
+function readAt(fd: number, position: number, length: number): Buffer {
+  const buf = Buffer.alloc(length);
+  const bytesRead = fs.readSync(fd, buf, 0, length, position);
+  return bytesRead === length ? buf : buf.subarray(0, bytesRead);
+}
+
+function findEndOfCentralDirectory(buf: Buffer): number {
+  const signature = 0x06054b50;
+  for (let i = buf.length - 22; i >= 0; i -= 1) {
+    if (buf.readUInt32LE(i) === signature) return i;
+  }
+  throw new UserFacingError("APKS_INVALID", "Invalid .apks file: end of central directory not found");
+}
+
+function readZipEntries(apksPath: string): ZipEntry[] {
+  const fd = fs.openSync(apksPath, "r");
+  try {
+    const fileSize = fs.fstatSync(fd).size;
+    const tailSize = Math.min(fileSize, 0xffff + 22);
+    const tailStart = fileSize - tailSize;
+    const tail = readAt(fd, tailStart, tailSize);
+    const eocd = findEndOfCentralDirectory(tail);
+    const totalEntries = tail.readUInt16LE(eocd + 10);
+    const centralDirSize = tail.readUInt32LE(eocd + 12);
+    const centralDirOffset = tail.readUInt32LE(eocd + 16);
+    if (centralDirSize === 0xffffffff || centralDirOffset === 0xffffffff || totalEntries === 0xffff) {
+      throw new UserFacingError("APKS_ZIP64_UNSUPPORTED", "ZIP64 .apks files are not supported yet");
+    }
+    const buf = readAt(fd, centralDirOffset, centralDirSize);
+    return parseCentralDirectory(buf, totalEntries);
+  } finally {
+    fs.closeSync(fd);
+  }
+}
+
+function parseCentralDirectory(buf: Buffer, totalEntries: number): ZipEntry[] {
+  const entries: ZipEntry[] = [];
+  let pos = 0;
+  for (let i = 0; i < totalEntries; i += 1) {
+    if (buf.readUInt32LE(pos) !== 0x02014b50) {
+      throw new UserFacingError("APKS_INVALID", "Invalid .apks file: central directory is corrupt");
+    }
+    const method = buf.readUInt16LE(pos + 10);
+    const compressedSize = buf.readUInt32LE(pos + 20);
+    const nameLength = buf.readUInt16LE(pos + 28);
+    const extraLength = buf.readUInt16LE(pos + 30);
+    const commentLength = buf.readUInt16LE(pos + 32);
+    const localHeaderOffset = buf.readUInt32LE(pos + 42);
+    const name = buf.subarray(pos + 46, pos + 46 + nameLength).toString("utf8");
+    entries.push({ name, method, compressedSize, localHeaderOffset });
+    pos += 46 + nameLength + extraLength + commentLength;
+  }
+  return entries;
+}
+
+async function extractEntryToFile(apksPath: string, entry: ZipEntry, outputApkPath: string): Promise<void> {
+  const fd = fs.openSync(apksPath, "r");
+  let dataStart: number;
+  try {
+    const localHeader = readAt(fd, entry.localHeaderOffset, 30);
+    if (localHeader.readUInt32LE(0) !== 0x04034b50) {
+      throw new UserFacingError("APKS_INVALID", `Invalid .apks file: local header not found for ${entry.name}`);
+    }
+    const nameLength = localHeader.readUInt16LE(26);
+    const extraLength = localHeader.readUInt16LE(28);
+    dataStart = entry.localHeaderOffset + 30 + nameLength + extraLength;
+  } finally {
+    fs.closeSync(fd);
+  }
+
+  await new Promise<void>((resolve, reject) => {
+    const input = fs.createReadStream(apksPath, {
+      start: dataStart,
+      end: dataStart + entry.compressedSize - 1,
+    });
+    const output = fs.createWriteStream(outputApkPath);
+    const source =
+      entry.method === 0
+        ? input
+        : entry.method === 8
+          ? input.pipe(zlib.createInflateRaw())
+          : null;
+    if (!source) {
+      input.destroy();
+      output.destroy();
+      reject(new UserFacingError("APKS_UNSUPPORTED_ZIP_METHOD", `Unsupported zip compression method ${entry.method}`));
+      return;
+    }
+    input.on("error", reject);
+    source.on("error", reject);
+    output.on("error", reject);
+    output.on("finish", resolve);
+    source.pipe(output);
+  });
+}
+
+export async function extractUniversalApk(apksPath: string, outputApkPath: string, overwrite: boolean): Promise<void> {
+  assertCanWriteFile(outputApkPath, overwrite, "Output APK");
+  const entries = readZipEntries(apksPath);
+  const universal = entries.find((entry) => entry.name === "universal.apk" || entry.name.endsWith("/universal.apk"));
+  if (!universal) {
+    throw new UserFacingError("UNIVERSAL_APK_NOT_FOUND", "universal.apk not found in .apks output");
+  }
+  fs.mkdirSync(path.dirname(outputApkPath), { recursive: true });
+  await extractEntryToFile(apksPath, universal, outputApkPath);
+}

package/src/aab-converter/bundletoolRunner.ts

@@ -0,0 +1,63 @@
+import path from "node:path";
+import { UserFacingError } from "../shared/errors.js";
+import { runProcess } from "../shared/processRunner.js";
+import type { Logger } from "../shared/logger.js";
+import type { SigningOptions } from "./types.js";
+
+export interface BuildApksOptions {
+  javaPath: string;
+  bundletoolPath: string;
+  aabPath: string;
+  apksPath: string;
+  signing: SigningOptions;
+  overwrite: boolean;
+  logger?: Logger;
+}
+
+export function buildBundletoolArgs(options: Omit<BuildApksOptions, "javaPath" | "logger">): string[] {
+  const args = [
+    "-jar",
+    options.bundletoolPath,
+    "build-apks",
+    `--bundle=${options.aabPath}`,
+    `--output=${options.apksPath}`,
+    "--mode=universal",
+    `--ks=${options.signing.keyStorePath}`,
+    `--ks-key-alias=${options.signing.keyAlias}`,
+    `--ks-pass=pass:${options.signing.keyStorePassword}`,
+  ];
+  if (options.signing.keyPassword) {
+    args.push(`--key-pass=pass:${options.signing.keyPassword}`);
+  }
+  if (options.overwrite) {
+    args.push("--overwrite");
+  }
+  return args;
+}
+
+function redactArg(arg: string): string {
+  if (arg.startsWith("--ks-pass=pass:")) return "--ks-pass=pass:******";
+  if (arg.startsWith("--key-pass=pass:")) return "--key-pass=pass:******";
+  return arg;
+}
+
+export function redactedBundletoolCommand(javaPath: string, args: string[]): string {
+  return [javaPath, ...args.map(redactArg)].map((part) => (part.includes(" ") ? `"${part}"` : part)).join(" ");
+}
+
+export async function buildUniversalApks(options: BuildApksOptions): Promise<void> {
+  const args = buildBundletoolArgs(options);
+  options.logger?.info(`Running bundletool: ${redactedBundletoolCommand(options.javaPath, args)}`);
+  const result = await runProcess(options.javaPath, args, {
+    cwd: path.dirname(options.apksPath),
+    onStdout: (chunk) => options.logger?.info(chunk.trimEnd()),
+    onStderr: (chunk) => options.logger?.warn(chunk.trimEnd()),
+  });
+  if (result.exitCode !== 0) {
+    throw new UserFacingError(
+      "BUNDLETOOL_FAILED",
+      "bundletool failed to build APK set",
+      (result.stderr || result.stdout).trim()
+    );
+  }
+}