@cityholdings/minicube-dev 0.1.4 → 0.1.5

package/README.md

@@ -67,7 +67,7 @@ by `MINICUBE_DEV_CONFIG` / `--config`. Create a skeleton with `minicube-dev conf
   },
   "devices": {
     "android": { "package": "<android application id>", "cubeConnectActivity": "<debug activity accepting cubeActHost/cubeActPort>" },
-    "ios": { "bundleId": "<bundle id, physical devices only>" }
+    "ios": { "bundleId": "<host app bundle id>" }
   }
 }
 ```
@@ -143,11 +143,36 @@ minicube-dev debug --whitelist-create qa --items 10001 # new whitelist for this
 
 * Mini program / H5 previews open `citysuper://platformapi/startapp?…` links (the mPaaS IDE
   preview layout with the app scheme instead of `mpaas`). Only non-production builds accept them.
+* On iOS the host app resumes a mini program that is already open and ignores a new link, so the
+  new package would not load. minicube-dev therefore quits the app (`devices.ios.bundleId`) before
+  opening the link on the simulator and on physical iPhones; the link then cold-starts it.
 * Card previews attach the app to `act server` without scanning: Android starts the debug-only
   connect activity (emulators get an `adb reverse` tunnel); the iOS simulator opens
   `citysuper://cubedebug/connect?host=127.0.0.1&port=9001` (UAT target, which links CubeDev).
   Physical phones scan the ACT QR code.
 
+## Installed versions on a device
+
+```bash
+minicube-dev installed --device ios-sim            # alias: versions
+minicube-dev installed --device android --type mini
+minicube-dev installed --device ios:<udid> --id 1000000000000001 --json
+```
+
+Lists every mini program, H5 offline package and Cube card the app has installed, newest version
+first, with older copies still on disk. Mini programs and H5 packages come from each package's
+`Manifest.xml`. Cards come from the Cube cache and show the card's own version together with the
+server resource version. Names come from the server when that environment has a token; cards show
+their template name.
+
+- iOS keeps packages per environment. The ENV column is matched to your configured environments by
+  `baseUrl` host (`Documents/NebulaEnvironments/<sha256(host)[:16]>`).
+- Android and cards are not stored per environment and are labelled with `--env` / `defaultEnv`.
+- Only debug / development builds can be read: Android uses `run-as`; a USB iPhone uses go-ios
+  (`npm i -g go-ios`; iOS 17+ also needs `ios tunnel start --userspace`); the simulator needs nothing.
+- Speed on a USB iPhone: about 45 s on iOS 16, where files are read in parallel. On iOS 17+ the tunnel only copes with
+  one file at a time, so it takes about 2–3 minutes; the command prints an estimate first.
+
 ## Release
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cityholdings/minicube-dev",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "Command-line workflow for mPaaS mini programs, H5 offline packages and Cube cards: build, debug upload, device preview and release",
   "type": "module",
   "bin": {

package/src/cli.js

@@ -10,6 +10,7 @@ import {
   CONFIG_TEMPLATE, PROJECT_FILE, globalConfigPath, loadGlobalConfig, loadProject, resolveEnv, saveGlobalConfig, saveProject, validateProject,
 } from './config.js';
 import { openUrl, parseTarget } from './device.js';
+import { groupInstalled, readInstalled } from './installed.js';
 import { CliError, color, log, table } from './log.js';
 import { which } from './proc.js';
 import { chooseVersion, previewUrl, resolveWhitelistIds, uploadMeta } from './workflow.js';
@@ -33,6 +34,9 @@ Develop
         --items <userIds>         add members to the (first) whitelist
         --remote                  card only: upload a whitelist-gray card instead of a local push
   preview [<url>|dir] --device <target>             open a preview link, or the project's latest debug package
+  installed --device <target> [--type mini|h5|card] [--id <resourceId>]   (alias: versions)
+        versions of mini programs, H5 offline packages and cards installed in the app on the
+        device (debug / development builds), with names from the server when a token is set
 
 Release
   release [dir] [--version x.y.z] [--publish full|whitelist] [--whitelist <id|name>] [--yes]
@@ -190,6 +194,60 @@ const COMMANDS = {
     });
   },
 
+  async installed(ctx) {
+    const config = loadGlobalConfig(ctx.flags);
+    const devices = config.data.devices ?? {};
+    const device = one(ctx.flags.device) ?? devices.default;
+    if (!device) throw new CliError('Usage: minicube-dev installed --device <target>', 'Targets: android, android:<serial>, ios-sim, ios-sim:<udid>, ios:<udid>');
+    const target = parseTarget(device, devices);
+    const environments = config.data.environments ?? {};
+    const found = await readInstalled(target, devices, environments);
+    const type = one(ctx.flags.type);
+    const id = one(ctx.flags.id);
+    // Android and cards are not stored per environment; label them with the selected one.
+    const selected = ctx.flags.env ? one(ctx.flags.env) : config.data.defaultEnv;
+    let rows = groupInstalled(found).map((row) => ({ ...row, env: row.env ?? (row.type === 'card' ? null : selected) }));
+    if (ctx.flags.env) rows = rows.filter((row) => !row.env || row.env === selected);
+
+    // Names (and mini/H5 types on iOS) from the server, best effort: needs that environment's token.
+    const known = new Map();
+    for (const name of new Set(rows.map((row) => row.env).filter((env) => env && environments[env]))) {
+      try {
+        const api = await connect(resolveEnv(config, { env: name }));
+        try {
+          for (const resource of await api.resources()) known.set(`${name}|${resource.resourceId}`, resource);
+        } finally {
+          api.close();
+        }
+      } catch (error) {
+        log.detail(`No resource names from ${name}: ${error.message}`);
+      }
+    }
+    rows = rows.map((row) => {
+      const resource = known.get(`${row.env}|${row.appId}`);
+      return { ...row, type: row.type ?? resource?.type ?? 'mini/h5', name: resource?.name ?? '' };
+    });
+    if (type) rows = rows.filter((row) => row.type === type);
+    if (id) rows = rows.filter((row) => row.appId === id);
+
+    log.detail(`Read from ${found.source}`);
+    output(ctx.flags, rows, (r) => (r.length === 0 ? 'Nothing installed matches.' : table(r.map((row) => ({
+      env: row.env ?? '-',
+      type: row.type,
+      appId: row.appId,
+      name: row.name,
+      installed: row.versions[0]?.label ?? '',
+      older: row.versions.slice(1).map((v) => v.label).join(', '),
+    })), [
+      { key: 'env', title: 'ENV' }, { key: 'type', title: 'TYPE' }, { key: 'appId', title: 'ID' }, { key: 'name', title: 'NAME' },
+      { key: 'installed', title: 'NEWEST INSTALLED' }, { key: 'older', title: 'OLDER COPIES' },
+    ])));
+  },
+
+  async versions(ctx) {
+    return COMMANDS.installed(ctx);
+  },
+
   async packages(ctx) {
     const project = ctx.args[0] ? null : loadProject('.', { required: false });
     const id = ctx.args[0] ?? project?.data.resourceId;

package/src/device.js

@@ -21,7 +21,7 @@ export function parseTarget(value, devices = {}) {
   throw new CliError(`Unknown device "${raw}"`, 'Use android, android:<serial>, ios-sim, ios-sim:<udid> or ios:<udid>.');
 }
 
-function adbPath() {
+export function adbPath() {
   const adb = process.env.ADB_BINARY ?? which('adb');
   if (!adb) throw new CliError('adb not found', 'Install Android platform-tools and add them to PATH (or set ADB_BINARY).');
   return adb;
@@ -60,6 +60,15 @@ export function openUrl(target, url, devices = {}) {
     return;
   }
   if (target.kind === 'ios-sim') {
+    // An iOS host app that already shows this mini program resumes it and ignores the link, so
+    // the new package never loads. Quit the app first (like devicectl --terminate-existing below);
+    // the link then cold-starts it.
+    const bundleId = devices.ios?.bundleId;
+    if (bundleId && !bundleId.includes('<')) {
+      if (runSync('xcrun', ['simctl', 'terminate', target.id, bundleId]).code === 0) log.detail(`Restarted ${bundleId} so the new package loads`);
+    } else {
+      log.warn('devices.ios.bundleId is not set: if the mini program is already open on the simulator, close it first or the new package will not load.');
+    }
     const result = runSync('xcrun', ['simctl', 'openurl', target.id, url]);
     if (result.code !== 0) throw new CliError(`simctl openurl failed: ${result.stderr.trim()}`, 'Is a simulator booted with the app installed? `xcrun simctl list devices booted`');
     log.success(`Opened on iOS simulator ${target.id}`);

package/src/installed.js

@@ -0,0 +1,228 @@
+import { createHash } from 'node:crypto';
+import { existsSync, mkdtempSync, readdirSync, readFileSync, rmSync, statSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { adbPath, androidSerial } from './device.js';
+import { CliError, log } from './log.js';
+import { run, runSync, which } from './proc.js';
+
+/**
+ * Package versions installed in the host app's sandbox on a device, read straight from the
+ * container the way the app stores them:
+ *   - mini programs and H5 offline packages: one directory per installed version holding the
+ *     package's Manifest.xml (<uid>, <version>). iOS keeps them per environment under
+ *     Documents/NebulaEnvironments/<sha256(gateway host)[:16]>/NAMAPP_UNZIP/; Android under
+ *     files/MriverInstallApps (mini programs) and files/nebulaInstallApps (H5 offline packages).
+ *   - Cube cards: cubeCrystal/<hash>/<server version a_b_c_d>/<n>.template, whose header names the
+ *     card and its own version.
+ * Reading another app's sandbox needs a debuggable / development-signed build.
+ */
+export async function readInstalled(target, devices, environments) {
+  const raw = target.kind === 'android' ? readAndroid(target, devices)
+    : target.kind === 'ios-sim' ? readSimulator(target, devices)
+      : await readIosDevice(target, devices);
+  const envByKey = new Map(Object.entries(environments ?? {}).map(([name, env]) => [environmentKey(env.baseUrl), name]));
+  const packages = [];
+  for (const { file, text } of raw.manifests) {
+    const appId = text.match(/<uid>\s*([^<\s]+)\s*<\/uid>/)?.[1];
+    const version = text.match(/<version>\s*([^<\s]+)\s*<\/version>/)?.[1];
+    if (!appId || !version) continue;
+    const parts = file.split('/');
+    const envKey = parts[parts.indexOf('NebulaEnvironments') + 1];
+    const type = file.includes('MriverInstallApps') ? 'mini' : file.includes('nebulaInstallApps') ? 'h5' : null;
+    packages.push({ appId, version, type, env: parts.includes('NebulaEnvironments') ? envByKey.get(envKey) ?? envKey : null });
+  }
+  const cards = [];
+  for (const { file, text } of raw.templates) {
+    const parts = file.split('/');
+    const serverVersion = parts[parts.length - 2]?.replaceAll('_', '.');
+    // The header is JSON with a few binary bytes interleaved; read the fields leniently.
+    const name = text.match(/"name"\s*:\s*"([^"]+)"/)?.[1] ?? text.match(/"assetId"\s*:\s*"([^"]+)"/)?.[1];
+    const cardVersion = text.match(/"vers[^"]{0,4}"\s*:\s*"([\d.]+)"/)?.[1];
+    if (name) cards.push({ appId: name, version: cardVersion ?? serverVersion, serverVersion, type: 'card', env: null });
+  }
+  return { packages, cards, source: raw.source };
+}
+
+/** Group installed versions per resource, newest first. */
+export function groupInstalled({ packages, cards }) {
+  const groups = new Map();
+  for (const item of [...packages, ...cards]) {
+    const key = `${item.env ?? ''}|${item.type ?? ''}|${item.appId}`;
+    const group = groups.get(key) ?? { env: item.env, type: item.type, appId: item.appId, versions: [] };
+    const label = item.serverVersion ? `${item.version} (server ${item.serverVersion})` : item.version;
+    if (!group.versions.some((v) => v.label === label)) group.versions.push({ version: item.version, serverVersion: item.serverVersion, label });
+    groups.set(key, group);
+  }
+  for (const group of groups.values()) {
+    group.versions.sort((a, b) => compareVersions(b.serverVersion ?? b.version, a.serverVersion ?? a.version));
+  }
+  return [...groups.values()].sort((a, b) => `${a.env}|${a.type}|${a.appId}`.localeCompare(`${b.env}|${b.type}|${b.appId}`));
+}
+
+export function compareVersions(a, b) {
+  const pa = String(a).split('.').map((n) => Number.parseInt(n, 10) || 0);
+  const pb = String(b).split('.').map((n) => Number.parseInt(n, 10) || 0);
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+    if ((pa[i] ?? 0) !== (pb[i] ?? 0)) return (pa[i] ?? 0) - (pb[i] ?? 0);
+  }
+  return 0;
+}
+
+/** The iOS app's per-environment storage key: sha256 of the gateway hostname, first 16 hex chars. */
+export function environmentKey(baseUrl) {
+  try {
+    const host = new URL(baseUrl).hostname.toLowerCase().replace(/\.+$/, '');
+    return createHash('sha256').update(host).digest('hex').slice(0, 16);
+  } catch {
+    return null;
+  }
+}
+
+// --- Android: one run-as shell pass (debuggable builds) ---------------------------------------------
+
+function readAndroid(target, devices) {
+  const serial = androidSerial(target);
+  const pkg = devices.android?.package;
+  if (!pkg || pkg.includes('<')) throw new CliError('devices.android.package is not configured');
+  const script = [
+    'for f in files/MriverInstallApps/*/*/Manifest.xml files/nebulaInstallApps/*/*/Manifest.xml; do',
+    '[ -f "$f" ] && { echo "@@M $f"; cat "$f"; echo; }; done;',
+    'for t in cache/cubeCrystal/*/*/*.template; do [ -f "$t" ] && { echo "@@T $t"; head -c 400 "$t"; echo; }; done',
+  ].join(' ');
+  const result = runSync(adbPath(), ['-s', serial, 'exec-out', 'run-as', pkg, 'sh', '-c', script], { encoding: 'latin1' });
+  if (/not debuggable|unknown package|is unknown/i.test(result.stdout + result.stderr)) {
+    throw new CliError(`Cannot read ${pkg} on ${serial}: ${(result.stderr || result.stdout).trim()}`,
+      'Installed versions can only be read from debug builds of the app (run-as).');
+  }
+  const manifests = [];
+  const templates = [];
+  for (const block of result.stdout.split(/\n(?=@@[MT] )/)) {
+    const match = block.match(/^@@([MT]) (\S+)\n?([\s\S]*)$/);
+    if (!match) continue;
+    (match[1] === 'M' ? manifests : templates).push({ file: match[2], text: match[3] });
+  }
+  return { manifests, templates, source: `Android ${serial} (${pkg})` };
+}
+
+// --- iOS simulator: the data container is a local directory ------------------------------------------
+
+function readSimulator(target, devices) {
+  const bundleId = iosBundleId(devices);
+  const result = runSync('xcrun', ['simctl', 'get_app_container', target.id, bundleId, 'data']);
+  if (result.code !== 0) throw new CliError(`${bundleId} is not installed on simulator ${target.id}: ${result.stderr.trim()}`);
+  const container = result.stdout.trim();
+  const manifests = [];
+  for (const root of [path.join(container, 'Documents', 'NebulaEnvironments'), path.join(container, 'Documents')]) {
+    for (const file of findFiles(root, (rel) => /(^|\/)NAMAPP_UNZIP\/[^/]+\/Manifest\.xml$/.test(rel), root.endsWith('Documents') ? 3 : 4)) {
+      manifests.push({ file: path.relative(container, file), text: readFileSync(file, 'utf8') });
+    }
+  }
+  const cubeRoot = path.join(container, 'Library', 'Caches', 'cubeCrystal');
+  const templates = findFiles(cubeRoot, (rel) => rel.endsWith('.template'), 3)
+    .map((file) => ({ file: path.relative(container, file), text: readHead(file, 400) }));
+  return { manifests: dedupe(manifests), templates, source: `iOS simulator ${target.id} (${bundleId})` };
+}
+
+// --- iOS device over USB: go-ios house_arrest (development-signed builds) ---------------------------
+
+async function readIosDevice(target, devices) {
+  const bundleId = iosBundleId(devices);
+  const ios = which('ios');
+  if (!ios) throw new CliError('go-ios not found', 'Install it with `npm i -g go-ios` (iOS 17+ also needs `ios tunnel start --userspace`).');
+  const base = ['fsync', '--udid', target.id, `--app=${bundleId}`];
+  const tree = (dir) => {
+    const result = runSync(ios, [...base, 'tree', `--path=${dir}`]);
+    return parseGoIosTree(result.stdout).map((rel) => `${dir}/${rel}`);
+  };
+  const files = [...tree('/Documents/NebulaEnvironments'), ...tree('/Library/Caches/cubeCrystal')];
+  if (files.length === 0) {
+    throw new CliError(`Could not read ${bundleId} on ${target.id}`,
+      'The app must be a development build; on iOS 17+ keep `ios tunnel start --userspace` running.');
+  }
+  const work = mkdtempSync(path.join(os.tmpdir(), 'minicube-installed-'));
+  try {
+    // Each go-ios pull is a separate device session (~1-2 s). Over USB (iOS <= 16) they run in
+    // parallel; through the iOS 17+ tunnel parallel sessions fail or hang, so pull one at a time
+    // with a timeout per file.
+    const major = Number.parseInt(String(JSON.parse(runSync(ios, ['info', '--udid', target.id]).stdout || '{}').ProductVersion), 10) || 0;
+    const tunnelled = major >= 17;
+    const pull = async (remote) => {
+      const local = path.join(work, remote.replace(/[^\w.-]+/g, '_'));
+      const args = [...base, 'pull', `--srcPath=${remote}`, `--dstPath=${local}`];
+      if (tunnelled) runSync(ios, args, { timeout: 30_000 });
+      else await run(ios, args, { capture: true });
+      const file = existsSync(local) && statSync(local).isDirectory() ? path.join(local, path.basename(remote)) : local;
+      return existsSync(file) ? file : null;
+    };
+    const wanted = files.filter((remote) => /\/NAMAPP_UNZIP\/[^/]+\/Manifest\.xml$/.test(remote) || remote.endsWith('.template'));
+    if (tunnelled) log.detail(`Reading ${wanted.length} files one at a time through the iOS ${major} tunnel (about ${Math.ceil(wanted.length * 1.5)} s)`);
+    const pulled = await mapLimit(wanted, tunnelled ? 1 : 8, async (remote) => ({ remote, file: await pull(remote) }));
+    const manifests = [];
+    const templates = [];
+    for (const { remote, file } of pulled) {
+      if (!file) continue;
+      if (remote.endsWith('.template')) templates.push({ file: remote, text: readHead(file, 400) });
+      else manifests.push({ file: remote, text: readFileSync(file, 'utf8') });
+    }
+    return { manifests, templates, source: `iPhone ${target.id} (${bundleId})` };
+  } finally {
+    rmSync(work, { recursive: true, force: true });
+  }
+}
+
+/** go-ios prints `|  |-name` lines (directories end with "/"); return paths relative to the root. */
+export function parseGoIosTree(text) {
+  const lines = text.split(/\r?\n/).map((line) => line.match(/^((?:\|\s\s)*)\|-(.+)$/)).filter(Boolean);
+  if (lines.length === 0) return [];
+  const base = Math.min(...lines.map((m) => m[1].length / 3));
+  const stack = [];
+  const files = [];
+  for (const [, indent, rawName] of lines) {
+    const depth = indent.length / 3 - base;
+    const name = rawName.replace(/\/+$/, '');
+    stack.length = depth;
+    stack[depth] = name;
+    if (!rawName.endsWith('/')) files.push(stack.slice(0, depth + 1).join('/'));
+  }
+  return files;
+}
+
+function iosBundleId(devices) {
+  const bundleId = devices.ios?.bundleId;
+  if (!bundleId || bundleId.includes('<')) throw new CliError('devices.ios.bundleId is not configured');
+  return bundleId;
+}
+
+function findFiles(root, accept, maxDepth, depth = 0, rel = '') {
+  if (!existsSync(root) || depth > maxDepth) return [];
+  const out = [];
+  for (const entry of readdirSync(root, { withFileTypes: true })) {
+    const childRel = rel ? `${rel}/${entry.name}` : entry.name;
+    const full = path.join(root, entry.name);
+    if (entry.isDirectory()) out.push(...findFiles(full, accept, maxDepth, depth + 1, childRel));
+    else if (accept(childRel)) out.push(full);
+  }
+  return out;
+}
+
+async function mapLimit(items, limit, fn) {
+  const results = new Array(items.length);
+  let next = 0;
+  const worker = async () => {
+    while (next < items.length) {
+      const index = next++;
+      results[index] = await fn(items[index]);
+    }
+  };
+  await Promise.all(Array.from({ length: Math.min(limit, items.length) }, worker));
+  return results;
+}
+
+function readHead(file, bytes) {
+  return readFileSync(file).subarray(0, bytes).toString('latin1');
+}
+
+function dedupe(items) {
+  return [...new Map(items.map((item) => [item.file, item])).values()];
+}