@cityholdings/minicube-dev 0.0.0-stage → 0.1.0

package/src/config.js

@@ -0,0 +1,126 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync, chmodSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { CliError } from './log.js';
+
+/**
+ * Global configuration. The installed package ships no endpoints, environments or credentials:
+ * everything comes from this file (or MINICUBE_DEV_CONFIG / --config).
+ */
+export function globalConfigPath(flags = {}) {
+  if (flags.config) return path.resolve(String(flags.config));
+  if (process.env.MINICUBE_DEV_CONFIG) return path.resolve(process.env.MINICUBE_DEV_CONFIG);
+  return path.join(os.homedir(), '.minicube-dev', 'config.json');
+}
+
+export function loadGlobalConfig(flags = {}) {
+  const file = globalConfigPath(flags);
+  if (!existsSync(file)) {
+    return { file, exists: false, data: { environments: {} } };
+  }
+  let data;
+  try {
+    data = JSON.parse(readFileSync(file, 'utf8'));
+  } catch (error) {
+    throw new CliError(`Cannot parse ${file}: ${error.message}`);
+  }
+  data.environments ??= {};
+  return { file, exists: true, data };
+}
+
+export function saveGlobalConfig(config) {
+  mkdirSync(path.dirname(config.file), { recursive: true });
+  writeFileSync(config.file, `${JSON.stringify(config.data, null, 2)}\n`, { mode: 0o600 });
+  try {
+    chmodSync(config.file, 0o600);
+  } catch {
+    // Windows ignores POSIX modes; the file lives in the user's profile directory.
+  }
+}
+
+export const CONFIG_TEMPLATE = {
+  defaultEnv: 'tst',
+  environments: {
+    tst: {
+      description: 'Test environment',
+      baseUrl: 'https://<tst-gateway-host>/core',
+      token: '<issued by: minicube-dev admin token create --env tst>',
+      previewScheme: 'citysuper',
+      kube: { context: '<kubectl context>', namespace: '<namespace>', service: '<mpaas-core service>', port: 8301 },
+    },
+  },
+  devices: {
+    android: {
+      package: '<android application id>',
+      cubeConnectActivity: '<debug activity that accepts cubeActHost/cubeActPort>',
+    },
+    ios: {
+      bundleId: '<ios bundle id>',
+    },
+  },
+  builders: {
+    mini: '<path to mini-pkg-builder executable or its runtime index.js>',
+  },
+};
+
+/**
+ * Resolve the environment to use: --env, then project defaultEnv, then global defaultEnv.
+ * Tokens can be inline (`token`) or read from an environment variable (`tokenEnv`).
+ */
+export function resolveEnv(globalConfig, flags = {}, project = null) {
+  const environments = globalConfig.data.environments ?? {};
+  const name = flags.env ?? project?.data?.env ?? globalConfig.data.defaultEnv;
+  if (!name) {
+    throw new CliError('No environment selected', `Pass --env <name> or set defaultEnv in ${globalConfig.file}`);
+  }
+  const env = environments[name];
+  if (!env) {
+    const known = Object.keys(environments);
+    throw new CliError(
+      `Environment "${name}" is not configured in ${globalConfig.file}`,
+      known.length ? `Known environments: ${known.join(', ')}` : 'Run `minicube-dev config init` and fill in your environments.',
+    );
+  }
+  const token = env.tokenEnv ? process.env[env.tokenEnv] : env.token;
+  return { name, ...env, token: token && !String(token).startsWith('<') ? token : undefined };
+}
+
+export const PROJECT_FILE = 'minicube.json';
+
+/** Project configuration (minicube.json) found in or above `start`. */
+export function loadProject(start = process.cwd(), { required = true } = {}) {
+  let dir = path.resolve(start);
+  for (;;) {
+    const file = path.join(dir, PROJECT_FILE);
+    if (existsSync(file)) {
+      let data;
+      try {
+        data = JSON.parse(readFileSync(file, 'utf8'));
+      } catch (error) {
+        throw new CliError(`Cannot parse ${file}: ${error.message}`);
+      }
+      validateProject(data, file);
+      return { file, root: dir, data };
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  if (required) {
+    throw new CliError(`No ${PROJECT_FILE} found in ${path.resolve(start)} or its parents`, 'Run `minicube-dev init` in the project directory.');
+  }
+  return null;
+}
+
+export function validateProject(data, file) {
+  if (!['mini', 'h5', 'card'].includes(data.type)) {
+    throw new CliError(`${file}: "type" must be one of mini, h5, card`);
+  }
+  if (!data.resourceId || typeof data.resourceId !== 'string') {
+    throw new CliError(`${file}: "resourceId" is required (mini program ID, H5 offline package ID or card ID)`);
+  }
+}
+
+export function saveProject(project) {
+  writeFileSync(project.file, `${JSON.stringify(project.data, null, 2)}\n`);
+}

package/src/device.js

@@ -0,0 +1,73 @@
+import { CliError, log } from './log.js';
+import { runSync, which } from './proc.js';
+
+/**
+ * Device targets:
+ *   android            the only connected adb device (or --serial / devices.android.serial)
+ *   android:<serial>   a specific adb device or emulator
+ *   ios-sim            the booted iOS simulator
+ *   ios-sim:<udid>     a specific simulator
+ *   ios:<udid>         a physical iPhone (Xcode 15+ devicectl)
+ */
+export function parseTarget(value, devices = {}) {
+  const raw = String(value ?? devices.default ?? '');
+  const [kind, id] = raw.split(/:(.*)/s);
+  if (kind === 'android') return { kind, id: id || devices.android?.serial };
+  if (kind === 'ios-sim' || kind === 'simulator') return { kind: 'ios-sim', id: id || 'booted' };
+  if (kind === 'ios') {
+    if (!id) throw new CliError('ios needs a device id: --device ios:<udid>', 'List devices with `xcrun devicectl list devices`, or use --device ios-sim for the simulator.');
+    return { kind, id };
+  }
+  throw new CliError(`Unknown device "${raw}"`, 'Use android, android:<serial>, ios-sim, ios-sim:<udid> or ios:<udid>.');
+}
+
+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;
+}
+
+export function androidDevices() {
+  const result = runSync(adbPath(), ['devices']);
+  return result.stdout.split(/\r?\n/).slice(1).map((l) => l.trim().split(/\s+/)).filter(([s, state]) => s && state === 'device').map(([s]) => s);
+}
+
+export function androidSerial(target) {
+  if (target.id) return target.id;
+  const devices = androidDevices();
+  if (devices.length === 0) throw new CliError('No Android device or emulator is connected', 'Check `adb devices`.');
+  if (devices.length > 1) throw new CliError(`${devices.length} Android devices are connected`, `Pick one: --device android:<serial> (${devices.join(', ')})`);
+  return devices[0];
+}
+
+export function adb(serial, args) {
+  const result = runSync(adbPath(), ['-s', serial, ...args]);
+  if (result.code !== 0) throw new CliError(`adb ${args.join(' ')} failed: ${(result.stderr || result.stdout).trim()}`);
+  return result.stdout;
+}
+
+/** Open a citysuper:// (or other app scheme) URL in the host app on the target device. */
+export function openUrl(target, url, devices = {}) {
+  if (target.kind === 'android') {
+    const serial = androidSerial(target);
+    const pkg = devices.android?.package;
+    // The remote shell splits on whitespace and interprets &, so quote the URL for it.
+    const args = ['shell', 'am', 'start', '-a', 'android.intent.action.VIEW', '-d', `'${url}'`];
+    if (pkg && !pkg.includes('<')) args.push(pkg);
+    const out = adb(serial, args);
+    if (/Error:/i.test(out)) throw new CliError(`Android refused the URL: ${out.trim()}`);
+    log.success(`Opened on Android ${serial}`);
+    return;
+  }
+  if (target.kind === 'ios-sim') {
+    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}`);
+    return;
+  }
+  const bundleId = devices.ios?.bundleId;
+  if (!bundleId || bundleId.includes('<')) throw new CliError('devices.ios.bundleId is not configured');
+  const result = runSync('xcrun', ['devicectl', 'device', 'process', 'launch', '--device', target.id, '--terminate-existing', '--payload-url', url, bundleId]);
+  if (result.code !== 0) throw new CliError(`devicectl launch failed: ${(result.stderr || result.stdout).trim()}`);
+  log.success(`Opened on iPhone ${target.id}`);
+}

package/src/kube.js

@@ -0,0 +1,54 @@
+import { spawn } from 'node:child_process';
+import { createServer } from 'node:net';
+import { CliError, log } from './log.js';
+import { which } from './proc.js';
+
+function freePort() {
+  return new Promise((resolve, reject) => {
+    const server = createServer();
+    server.once('error', reject);
+    server.listen(0, '127.0.0.1', () => {
+      const { port } = server.address();
+      server.close(() => resolve(port));
+    });
+  });
+}
+
+/**
+ * `kubectl port-forward svc/<service> <local>:<port>` using the local kubeconfig.
+ * Requests through the tunnel reach the pod on its loopback interface, which is what the
+ * token administration endpoints require.
+ */
+export async function openPortForward(kube) {
+  if (!kube?.service || !kube?.namespace) {
+    throw new CliError('This environment has no "kube" section (context, namespace, service, port)', 'Add it to the environment in your minicube-dev config.');
+  }
+  const kubectl = which(kube.kubectl ?? 'kubectl');
+  if (!kubectl) throw new CliError('kubectl not found', 'Install kubectl and configure the kubeconfig for this cluster.');
+  const localPort = await freePort();
+  const args = [];
+  if (kube.kubeconfig) args.push('--kubeconfig', kube.kubeconfig);
+  if (kube.context) args.push('--context', kube.context);
+  args.push('-n', kube.namespace, 'port-forward', `svc/${kube.service}`, `${localPort}:${kube.port ?? 8301}`, '--address', '127.0.0.1');
+  log.detail(`kubectl ${args.join(' ')}`);
+  const child = spawn(kubectl, args, { stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true });
+  let stderr = '';
+  await new Promise((resolve, reject) => {
+    const timer = setTimeout(() => reject(new CliError(`kubectl port-forward did not become ready: ${stderr.trim()}`)), 20_000);
+    child.stdout.on('data', (data) => {
+      if (String(data).includes('Forwarding from')) {
+        clearTimeout(timer);
+        resolve();
+      }
+    });
+    child.stderr.on('data', (data) => (stderr += data));
+    child.once('exit', (code) => {
+      clearTimeout(timer);
+      reject(new CliError(`kubectl port-forward exited (${code}): ${stderr.trim()}`));
+    });
+  });
+  return {
+    baseUrl: `http://127.0.0.1:${localPort}`,
+    close: () => child.kill(),
+  };
+}

package/src/log.js

@@ -0,0 +1,56 @@
+const useColor = process.stdout.isTTY && !process.env.NO_COLOR;
+const paint = (code) => (text) => (useColor ? `\u001b[${code}m${text}\u001b[0m` : String(text));
+
+export const color = {
+  bold: paint(1),
+  dim: paint(2),
+  red: paint(31),
+  green: paint(32),
+  yellow: paint(33),
+  cyan: paint(36),
+};
+
+export class CliError extends Error {
+  constructor(message, hint) {
+    super(message);
+    this.hint = hint;
+  }
+}
+
+export const log = {
+  quiet: false,
+  json: false,
+  step(message) {
+    if (!this.quiet) process.stderr.write(`${color.cyan('▸')} ${message}\n`);
+  },
+  detail(message) {
+    if (!this.quiet) process.stderr.write(`  ${color.dim(message)}\n`);
+  },
+  info(message) {
+    process.stderr.write(`${message}\n`);
+  },
+  warn(message) {
+    process.stderr.write(`${color.yellow('!')} ${message}\n`);
+  },
+  success(message) {
+    process.stderr.write(`${color.green('✔')} ${message}\n`);
+  },
+  /** Machine-readable or primary output goes to stdout. */
+  out(value) {
+    if (typeof value === 'string') process.stdout.write(`${value}\n`);
+    else process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
+  },
+};
+
+export function printError(error) {
+  process.stderr.write(`${color.red('✖')} ${error?.message ?? String(error)}\n`);
+  if (error?.hint) process.stderr.write(`  ${error.hint}\n`);
+  if (process.env.MINICUBE_DEBUG && error?.stack) process.stderr.write(`${error.stack}\n`);
+}
+
+export function table(rows, columns) {
+  if (rows.length === 0) return '(none)';
+  const widths = columns.map((c) => Math.max(c.title.length, ...rows.map((r) => String(r[c.key] ?? '').length)));
+  const line = (cells) => cells.map((cell, i) => String(cell ?? '').padEnd(widths[i])).join('  ').trimEnd();
+  return [line(columns.map((c) => c.title)), line(widths.map((w) => '-'.repeat(w))), ...rows.map((r) => line(columns.map((c) => r[c.key])))].join('\n');
+}

package/src/proc.js

@@ -0,0 +1,91 @@
+import { spawn, spawnSync } from 'node:child_process';
+import { existsSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { CliError } from './log.js';
+
+const isWindows = process.platform === 'win32';
+
+/** Locate an executable on PATH (honours PATHEXT on Windows). */
+export function which(command, extraDirs = []) {
+  if (path.isAbsolute(command) || command.includes('/') || command.includes('\\')) {
+    return existsSync(command) ? command : null;
+  }
+  const dirs = [...extraDirs, ...(process.env.PATH ?? '').split(path.delimiter)].filter(Boolean);
+  const exts = isWindows ? (process.env.PATHEXT ?? '.EXE;.CMD;.BAT;.COM').split(';').map((e) => e.toLowerCase()) : [''];
+  for (const dir of dirs) {
+    for (const ext of isWindows ? ['', ...exts] : exts) {
+      const candidate = path.join(dir, command + ext);
+      try {
+        if (statSync(candidate).isFile()) return candidate;
+      } catch {
+        // keep looking
+      }
+    }
+  }
+  return null;
+}
+
+/** Windows cannot spawn .cmd/.bat directly; route those through cmd.exe with quoted arguments. */
+function spawnTarget(command, args) {
+  if (isWindows && /\.(cmd|bat)$/i.test(command)) {
+    const quote = (s) => (/[\s"&|<>^%]/.test(s) ? `"${String(s).replace(/"/g, '""')}"` : s);
+    return { file: process.env.ComSpec ?? 'cmd.exe', args: ['/d', '/s', '/c', `"${[command, ...args].map(quote).join(' ')}"`], verbatim: true };
+  }
+  return { file: command, args, verbatim: false };
+}
+
+function resolveCommand(command) {
+  const resolved = which(command);
+  if (!resolved) throw new CliError(`Command not found: ${command}`, `Install it or add it to PATH.`);
+  return resolved;
+}
+
+/** Run a command synchronously and capture its output. */
+export function runSync(command, args, options = {}) {
+  const target = spawnTarget(resolveCommand(command), args);
+  const result = spawnSync(target.file, target.args, {
+    encoding: 'utf8',
+    windowsVerbatimArguments: target.verbatim,
+    maxBuffer: 64 * 1024 * 1024,
+    ...options,
+  });
+  if (result.error) throw new CliError(`Cannot run ${command}: ${result.error.message}`);
+  return { code: result.status ?? 1, stdout: result.stdout ?? '', stderr: result.stderr ?? '' };
+}
+
+/** Run a command, streaming its output (or capturing it with `capture: true`). */
+export function run(command, args, { cwd, env, capture = false, input } = {}) {
+  const target = spawnTarget(resolveCommand(command), args);
+  return new Promise((resolve, reject) => {
+    const child = spawn(target.file, target.args, {
+      cwd,
+      env: env ? { ...process.env, ...env } : process.env,
+      stdio: [input === undefined ? 'inherit' : 'pipe', capture ? 'pipe' : 'inherit', capture ? 'pipe' : 'inherit'],
+      windowsVerbatimArguments: target.verbatim,
+    });
+    let stdout = '';
+    let stderr = '';
+    child.stdout?.on('data', (d) => (stdout += d));
+    child.stderr?.on('data', (d) => (stderr += d));
+    if (input !== undefined) child.stdin.end(input);
+    child.once('error', (error) => reject(new CliError(`Cannot run ${command}: ${error.message}`)));
+    child.once('close', (code) => resolve({ code: code ?? 1, stdout, stderr }));
+  });
+}
+
+/** Start a long-lived background process detached from this one. */
+export function spawnDetached(command, args, { cwd, logFd, env }) {
+  const target = spawnTarget(resolveCommand(command), args);
+  const child = spawn(target.file, target.args, {
+    cwd,
+    env: env ? { ...process.env, ...env } : process.env,
+    detached: true,
+    stdio: ['ignore', logFd, logFd],
+    windowsVerbatimArguments: target.verbatim,
+    windowsHide: true,
+  });
+  child.unref();
+  return child;
+}
+
+export const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

package/src/workflow.js

@@ -0,0 +1,113 @@
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { list, one } from './args.js';
+import { CliError, log } from './log.js';
+
+const VERSION = /^\d+(\.\d+){2,3}$/;
+
+export function compareVersions(a, b) {
+  const pa = a.split('.').map(Number);
+  const pb = b.split('.').map(Number);
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+    const d = (pa[i] ?? 0) - (pb[i] ?? 0);
+    if (d) return Math.sign(d);
+  }
+  return 0;
+}
+
+/** Highest existing version with its last segment incremented; `fallback` when nothing exists yet. */
+export function nextVersion(existing, fallback = '1.0.0') {
+  const versions = existing.filter((v) => VERSION.test(v ?? ''));
+  if (versions.length === 0) return fallback;
+  const max = versions.sort(compareVersions).at(-1);
+  const parts = max.split('.').map(Number);
+  parts[parts.length - 1] += 1;
+  return parts.join('.');
+}
+
+/**
+ * Version to upload: --version, then minicube.json, then (cards) manifest.json; when that one is
+ * already taken (or nothing is set) the next free version after the highest existing one.
+ */
+export function chooseVersion(flags, project, packages) {
+  const explicit = one(flags.version);
+  const existing = packages.map((p) => p.version);
+  if (explicit) {
+    if (!VERSION.test(explicit)) throw new CliError(`Invalid version ${explicit}`, 'Use 1.0.0 or 1.0.0.0');
+    if (existing.includes(explicit)) throw new CliError(`Version ${explicit} of ${project.data.resourceId} already exists on the server`);
+    return explicit;
+  }
+  let configured = project.data.version;
+  if (!configured && project.data.type === 'card') {
+    const manifest = path.join(path.resolve(project.root, project.data.card?.dir ?? '.'), 'manifest.json');
+    if (existsSync(manifest)) configured = JSON.parse(readFileSync(manifest, 'utf8')).version;
+  }
+  if (configured && VERSION.test(configured) && !existing.includes(configured) && existing.every((v) => compareVersions(configured, v) > 0)) {
+    return configured;
+  }
+  return nextVersion(existing, configured && VERSION.test(configured) ? configured : '1.0.0');
+}
+
+/** Device preview URL. Mini programs keep the IDE preview QR layout with the app's own scheme. */
+export function previewUrl(type, resourceId, version, scheme = 'citysuper') {
+  if (type === 'mini') {
+    const inner = `${scheme}://platformapi/startapp?appId=${resourceId}&nbsv=${version}&nbsource=debug&nbprefer=YES&nbsn=DEBUG&nboffline=sync&nbtoken=ide_qr&chInfo=ch_minicube&channelId=minicube&isRemoteDebug=false&enableBugme=false&xriver=false`;
+    return `${scheme}://platformapi/startapp?appId=20001101&token=ide_qr&scheme=${encodeURIComponent(inner)}`;
+  }
+  if (type === 'h5') {
+    return `${scheme}://platformapi/startapp?appId=${resourceId}&nbsv=${version}&nbsource=debug&nbprefer=YES&nbsn=DEBUG&nboffline=sync`;
+  }
+  return null;
+}
+
+/**
+ * Whitelists for a debug upload, from --whitelist <id|name> (repeatable) or minicube.json
+ * debug.whitelist. `--whitelist-create <name> --items a,b` creates a new one first.
+ */
+export async function resolveWhitelistIds(api, flags, project) {
+  const existing = await api.whitelists();
+  const ids = [];
+  const createName = one(flags['whitelist-create']);
+  if (createName) {
+    const items = list(flags.items);
+    if (items.length === 0) throw new CliError('--whitelist-create needs --items <userId,...>');
+    const created = await api.createWhitelist(createName, items);
+    log.detail(`Created whitelist ${created.name} (#${created.id}) with ${created.itemCount} member(s)`);
+    ids.push(created.id);
+  }
+  const wanted = [...list(flags.whitelist), ...(ids.length || list(flags.whitelist).length ? [] : [].concat(project?.data?.debug?.whitelist ?? []).map(String))];
+  for (const ref of wanted) {
+    const match = existing.find((w) => String(w.id) === ref) ?? existing.find((w) => w.name === ref);
+    if (!match) {
+      throw new CliError(`Whitelist "${ref}" not found`, `Available: ${existing.map((w) => `${w.id}:${w.name}`).join(', ') || '(none)'} — or create one with --whitelist-create <name> --items <userIds>`);
+    }
+    ids.push(match.id);
+  }
+  if (ids.length === 0) {
+    throw new CliError('A debug package needs at least one whitelist (only its members can download it)', 'Pass --whitelist <id|name>, set debug.whitelist in minicube.json, or --whitelist-create <name> --items <userIds>.');
+  }
+  const extraItems = createName ? [] : list(flags.items);
+  if (extraItems.length) {
+    await api.addWhitelistItems(ids[0], extraItems);
+    log.detail(`Added ${extraItems.length} member(s) to whitelist #${ids[0]}`);
+  }
+  return [...new Set(ids)];
+}
+
+export function uploadMeta(project, { version, channel, mainUrl, whitelistIds, description }) {
+  const d = project.data;
+  return {
+    resourceId: d.resourceId,
+    version,
+    channel,
+    mainUrl,
+    whitelistIds,
+    clientScopes: d.clientScopes,
+    enableTabBar: d.enableTabBar,
+    enableOptionMenu: d.enableOptionMenu,
+    // The server default expand describes a mini program (enableDSL=YES); iOS would then launch an
+    // H5 offline package as a mini program. Console-uploaded H5 packages use empty launch params.
+    expand: d.expand ? (typeof d.expand === 'string' ? d.expand : JSON.stringify(d.expand)) : d.type === 'h5' ? '{"launchParams":{}}' : undefined,
+    description,
+  };
+}

package/src/zip.js

@@ -0,0 +1,110 @@
+import { readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { deflateRawSync } from 'node:zlib';
+
+const CRC_TABLE = (() => {
+  const table = new Uint32Array(256);
+  for (let n = 0; n < 256; n++) {
+    let c = n;
+    for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+    table[n] = c >>> 0;
+  }
+  return table;
+})();
+
+export function crc32(buffer) {
+  let crc = 0xffffffff;
+  for (let i = 0; i < buffer.length; i++) crc = CRC_TABLE[(crc ^ buffer[i]) & 0xff] ^ (crc >>> 8);
+  return (crc ^ 0xffffffff) >>> 0;
+}
+
+function dosDateTime(date) {
+  const time = (date.getHours() << 11) | (date.getMinutes() << 5) | (date.getSeconds() >> 1);
+  const day = ((date.getFullYear() - 1980) << 9) | ((date.getMonth() + 1) << 5) | date.getDate();
+  return { time, day };
+}
+
+/** Files under `dir`, as forward-slash paths relative to it, sorted for reproducible archives. */
+export function listFiles(dir, base = '') {
+  const out = [];
+  for (const entry of readdirSync(path.join(dir, base), { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+    const rel = base ? `${base}/${entry.name}` : entry.name;
+    if (entry.isDirectory()) out.push(...listFiles(dir, rel));
+    else if (entry.isFile()) out.push(rel);
+  }
+  return out;
+}
+
+/**
+ * Write a ZIP archive. `entries` is a list of { name, data } (name uses forward slashes).
+ * Directory entries are emitted for every parent so Java's ZipInputStream recreates them.
+ */
+export function writeZip(file, entries) {
+  const { time, day } = dosDateTime(new Date());
+  const chunks = [];
+  const central = [];
+  let offset = 0;
+  const dirs = new Set();
+  for (const { name } of entries) {
+    const parts = name.split('/');
+    for (let i = 1; i < parts.length; i++) dirs.add(`${parts.slice(0, i).join('/')}/`);
+  }
+  const all = [...[...dirs].sort().map((name) => ({ name, data: Buffer.alloc(0), dir: true })), ...entries];
+  for (const entry of all) {
+    const nameBuf = Buffer.from(entry.name, 'utf8');
+    const raw = Buffer.isBuffer(entry.data) ? entry.data : Buffer.from(entry.data);
+    const deflated = entry.dir ? raw : deflateRawSync(raw);
+    const useDeflate = !entry.dir && deflated.length < raw.length;
+    const body = useDeflate ? deflated : raw;
+    const crc = crc32(raw);
+    const local = Buffer.alloc(30);
+    local.writeUInt32LE(0x04034b50, 0);
+    local.writeUInt16LE(20, 4);
+    local.writeUInt16LE(0x0800, 6); // UTF-8 names
+    local.writeUInt16LE(useDeflate ? 8 : 0, 8);
+    local.writeUInt16LE(time, 10);
+    local.writeUInt16LE(day, 12);
+    local.writeUInt32LE(crc, 14);
+    local.writeUInt32LE(body.length, 18);
+    local.writeUInt32LE(raw.length, 22);
+    local.writeUInt16LE(nameBuf.length, 26);
+    local.writeUInt16LE(0, 28);
+    chunks.push(local, nameBuf, body);
+
+    const header = Buffer.alloc(46);
+    header.writeUInt32LE(0x02014b50, 0);
+    header.writeUInt16LE(20, 4);
+    header.writeUInt16LE(20, 6);
+    header.writeUInt16LE(0x0800, 8);
+    header.writeUInt16LE(useDeflate ? 8 : 0, 10);
+    header.writeUInt16LE(time, 12);
+    header.writeUInt16LE(day, 14);
+    header.writeUInt32LE(crc, 16);
+    header.writeUInt32LE(body.length, 20);
+    header.writeUInt32LE(raw.length, 24);
+    header.writeUInt16LE(nameBuf.length, 28);
+    header.writeUInt32LE(entry.dir ? 0x10 : 0, 38);
+    header.writeUInt32LE(offset, 42);
+    central.push(header, nameBuf);
+    offset += local.length + nameBuf.length + body.length;
+  }
+  const centralSize = central.reduce((n, b) => n + b.length, 0);
+  const end = Buffer.alloc(22);
+  end.writeUInt32LE(0x06054b50, 0);
+  end.writeUInt16LE(all.length, 8);
+  end.writeUInt16LE(all.length, 10);
+  end.writeUInt32LE(centralSize, 12);
+  end.writeUInt32LE(offset, 16);
+  writeFileSync(file, Buffer.concat([...chunks, ...central, end]));
+  return file;
+}
+
+/** Zip the contents of `dir` under the archive folder `prefix` ('' for the archive root). */
+export function zipDirectory(dir, file, prefix = '') {
+  const entries = listFiles(dir).map((rel) => ({ name: prefix ? `${prefix}/${rel}` : rel, data: readFileSync(path.join(dir, rel)) }));
+  return writeZip(file, entries);
+}
+
+export function fileSize(file) {
+  return statSync(file).size;
+}