@webority/mobile-tools 0.0.0-stage → 0.1.0

package/lib/hooks.js

@@ -0,0 +1,96 @@
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { capture } from './exec.js';
+import { fail, say } from './output.js';
+import { findOnPath } from './platform.js';
+export const HOOK_NAMES = ['post-merge', 'post-checkout'];
+const OWNER_LINE = '# Written by @webority/mobile-tools (hooks install).';
+const EXIT_LINE = 'exit $status';
+const startMarker = (appDir) => `# >>> mobile-tools ${appDir}`;
+const endMarker = (appDir) => `# <<< mobile-tools ${appDir}`;
+/** The block one app adds: a stale-tree check that prints its one line and never fails the git command. */
+export const hookBlock = (appDir) => {
+    const cli = 'node_modules/@webority/mobile-tools/lib/cli.js';
+    return [
+        startMarker(appDir),
+        `if [ -f "${appDir}/${cli}" ]; then`,
+        `  (cd "${appDir}" && node ${cli} sync --check) || true`,
+        'fi',
+        endMarker(appDir)
+    ].join('\n');
+};
+export const chainedName = (hook) => `${hook}.chained`;
+export const isOwnHook = (content) => content.includes(OWNER_LINE);
+/**
+ * The hook file after adding or refreshing one app's block. A hook this tool did not write is
+ * never edited: the caller moves it aside and the new hook runs it first, passing its exit status
+ * through.
+ */
+export const composeHook = (hook, existing, appDir) => {
+    const block = hookBlock(appDir);
+    if (existing !== undefined && isOwnHook(existing)) {
+        const start = existing.indexOf(startMarker(appDir));
+        const end = existing.indexOf(endMarker(appDir));
+        if (start >= 0 && end > start) {
+            return `${existing.slice(0, start)}${block}${existing.slice(end + endMarker(appDir).length)}`;
+        }
+        const exitAt = existing.lastIndexOf(EXIT_LINE);
+        return exitAt >= 0
+            ? `${existing.slice(0, exitAt)}${block}\n${existing.slice(exitAt)}`
+            : `${existing.trimEnd()}\n${block}\n`;
+    }
+    return [
+        '#!/bin/sh',
+        OWNER_LINE,
+        'status=0',
+        `chained="$(dirname "$0")/${chainedName(hook)}"`,
+        'if [ -x "$chained" ]; then "$chained" "$@" || status=$?; fi',
+        block,
+        EXIT_LINE,
+        ''
+    ].join('\n');
+};
+const git = (appRoot, args) => {
+    const exe = findOnPath('git', process.env, process.platform) ?? fail('git not found on PATH');
+    const result = capture({ file: exe, args }, appRoot);
+    if (result.status !== 0) {
+        return fail(`git ${args.join(' ')} failed: ${result.stderr.trim()}`);
+    }
+    return result.stdout.trim();
+};
+/** The hooks folder git runs: core.hooksPath when set (relative to the work tree top), else the repo's own. */
+export const hooksDir = (appRoot) => {
+    const topLevel = git(appRoot, ['rev-parse', '--show-toplevel']);
+    const exe = findOnPath('git', process.env, process.platform) ?? fail('git not found on PATH');
+    const configured = capture({ file: exe, args: ['config', '--get', 'core.hooksPath'] }, appRoot);
+    const custom = configured.status === 0 ? configured.stdout.trim() : '';
+    if (custom !== '') {
+        return { dir: path.resolve(topLevel, custom), topLevel };
+    }
+    return {
+        dir: path.resolve(appRoot, git(appRoot, ['rev-parse', '--git-path', 'hooks'])),
+        topLevel
+    };
+};
+export const installHooks = (appRoot) => {
+    const { dir, topLevel } = hooksDir(appRoot);
+    const appDir = path.relative(topLevel, appRoot).split(path.sep).join('/') || '.';
+    mkdirSync(dir, { recursive: true });
+    for (const hook of HOOK_NAMES) {
+        const file = path.join(dir, hook);
+        let existing = existsSync(file) ? readFileSync(file, 'utf8') : undefined;
+        if (existing !== undefined && !isOwnHook(existing)) {
+            const chained = path.join(dir, chainedName(hook));
+            if (existsSync(chained)) {
+                fail(`${file} is not ours and ${chained} already exists; merge them by hand, then rerun`);
+            }
+            renameSync(file, chained);
+            chmodSync(chained, 0o755);
+            say(`hooks: kept your ${hook} hook as ${chainedName(hook)}; it still runs first`);
+            existing = undefined;
+        }
+        writeFileSync(file, composeHook(hook, existing, appDir), 'utf8');
+        chmodSync(file, 0o755);
+        say(`hooks: ${path.relative(topLevel, file).split(path.sep).join('/')} runs sync --check for ${appDir}`);
+    }
+};

package/lib/iconArt.js

@@ -0,0 +1,74 @@
+/** Production is clean; the other two carry a corner ribbon so testers can tell builds apart. */
+export const RIBBONS = {
+    Development: { label: 'DEV', color: '#2E7D32' },
+    Staging: { label: 'STAGING', color: '#EF6C00' },
+    Production: undefined
+};
+const r = (n) => (Math.round(n * 100) / 100).toString();
+/**
+ * A band across the bottom-right corner of the box, with the label along it. The band's middle
+ * sits far enough in from the corner that a circular or rounded launcher mask still shows the
+ * whole label. Text is SVG text in a generic sans-serif: no font file ships with the package.
+ */
+export const ribbonSvg = (canvas, box, ribbon) => {
+    const { x, y, size: s } = box;
+    const outer = 0.38 * s;
+    const inner = 0.66 * s;
+    const points = [
+        [x + outer, y + s],
+        [x + s, y + outer],
+        [x + s, y + inner],
+        [x + inner, y + s]
+    ]
+        .map(([px, py]) => `${r(px)},${r(py)}`)
+        .join(' ');
+    const cx = x + 0.76 * s;
+    const cy = y + 0.76 * s;
+    const fontSize = (ribbon.label.length > 4 ? 0.105 : 0.13) * s;
+    return [
+        `<svg xmlns="http://www.w3.org/2000/svg" width="${canvas}" height="${canvas}" viewBox="0 0 ${canvas} ${canvas}">`,
+        `<polygon points="${points}" fill="${ribbon.color}"/>`,
+        `<text x="${r(cx)}" y="${r(cy)}" transform="rotate(-45 ${r(cx)} ${r(cy)})" fill="#FFFFFF"`,
+        ` font-family="sans-serif" font-weight="700" font-size="${r(fontSize)}" text-anchor="middle"`,
+        ` dominant-baseline="central">${ribbon.label}</text>`,
+        '</svg>'
+    ].join('');
+};
+export const circleMaskSvg = (size) => `<svg xmlns="http://www.w3.org/2000/svg" width="${size}" height="${size}"><circle cx="${size / 2}" cy="${size / 2}" r="${size / 2}" fill="#000"/></svg>`;
+/** Density buckets and their scale from mdpi. */
+export const DENSITIES = [
+    ['mdpi', 1],
+    ['hdpi', 1.5],
+    ['xhdpi', 2],
+    ['xxhdpi', 3],
+    ['xxxhdpi', 4]
+];
+/** Legacy launcher icons are 48dp; adaptive layers are 108dp, of which the middle 72dp shows. */
+export const LEGACY_DP = 48;
+export const ADAPTIVE_DP = 108;
+export const ADAPTIVE_VISIBLE_DP = 72;
+export const ADAPTIVE_ICON_XML = [
+    '<?xml version="1.0" encoding="utf-8"?>',
+    '<adaptive-icon xmlns:android="http://schemas.android.com/apk/res/android">',
+    '    <background android:drawable="@color/ic_launcher_background"/>',
+    '    <foreground android:drawable="@mipmap/ic_launcher_foreground"/>',
+    '</adaptive-icon>',
+    ''
+].join('\n');
+export const backgroundColorXml = (color) => [
+    '<?xml version="1.0" encoding="utf-8"?>',
+    '<resources>',
+    `    <color name="ic_launcher_background">${color}</color>`,
+    '</resources>',
+    ''
+].join('\n');
+/** A single 1024 px universal icon; Xcode derives every other size from it. */
+export const IOS_ICON_FILE = 'AppIcon-1024.png';
+export const iosContentsJson = () => `${JSON.stringify({
+    images: [{ filename: IOS_ICON_FILE, idiom: 'universal', platform: 'ios', size: '1024x1024' }],
+    info: { author: 'xcode', version: 1 }
+}, null, 2)}\n`;
+export const toHex = (red, green, blue) => `#${[red, green, blue]
+    .map((v) => v.toString(16).padStart(2, '0'))
+    .join('')
+    .toUpperCase()}`;

package/lib/icons.js

@@ -0,0 +1,162 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { ENVIRONMENTS, flavorOf, loadToolsConfig, resolveIosProjectName } from './config.js';
+import { ADAPTIVE_DP, ADAPTIVE_ICON_XML, ADAPTIVE_VISIBLE_DP, backgroundColorXml, circleMaskSvg, DENSITIES, IOS_ICON_FILE, iosContentsJson, LEGACY_DP, RIBBONS, ribbonSvg, toHex } from './iconArt.js';
+import { fail, say } from './output.js';
+const MASTER = 1024;
+/** Fixed encoder settings: the same source always gives the same bytes. */
+const PNG = { compressionLevel: 9, adaptiveFiltering: false, palette: false, force: true };
+const ICON_NAMES = ['ic_launcher', 'ic_launcher_round', 'ic_launcher_foreground'];
+/** Removes a same-named launcher icon in another format, which Android would reject as a duplicate resource. */
+const removeOtherFormats = (dir) => {
+    if (!existsSync(dir)) {
+        return;
+    }
+    for (const file of readdirSync(dir)) {
+        const { name, ext } = path.parse(file);
+        if (ICON_NAMES.includes(name) && ext !== '.png') {
+            rmSync(path.join(dir, file));
+        }
+    }
+};
+const write = (file, content) => {
+    mkdirSync(path.dirname(file), { recursive: true });
+    writeFileSync(file, content);
+};
+/** A values file other than ours defining the same color would fail the resource merge. */
+const assertNoColorClash = (valuesDir, ours) => {
+    if (!existsSync(valuesDir)) {
+        return;
+    }
+    for (const file of readdirSync(valuesDir)) {
+        if (file === ours || !file.endsWith('.xml')) {
+            continue;
+        }
+        if (readFileSync(path.join(valuesDir, file), 'utf8').includes('name="ic_launcher_background"')) {
+            fail(`${path.join(valuesDir, file)} already defines ic_launcher_background; remove it there`);
+        }
+    }
+};
+const loadMaster = async (sharp, file) => {
+    const meta = await sharp(file).metadata();
+    if (meta.format !== 'png' && meta.format !== 'svg') {
+        return fail(`icon source must be a PNG or an SVG, not ${meta.format ?? 'unknown'}: ${file}`);
+    }
+    const width = meta.width ?? 0;
+    const height = meta.height ?? 0;
+    if (width !== height) {
+        return fail(`icon source must be square, ${file} is ${width}x${height}`);
+    }
+    if (meta.format === 'png' && width < MASTER) {
+        return fail(`a PNG icon source must be at least ${MASTER}x${MASTER}, ${file} is ${width}x${height}`);
+    }
+    const options = meta.format === 'svg' ? { density: (72 * MASTER) / width } : {};
+    return sharp(file, options)
+        .resize(MASTER, MASTER, { fit: 'contain', background: { r: 0, g: 0, b: 0, alpha: 0 } })
+        .ensureAlpha()
+        .png(PNG)
+        .toBuffer();
+};
+/** The adaptive background is the source's own corner colour, so a full-bleed icon reads as one piece. */
+const cornerColor = async (sharp, master) => {
+    const { data } = await sharp(master).raw().toBuffer({ resolveWithObject: true });
+    return data[3] === 0 ? '#FFFFFF' : toHex(data[0], data[1], data[2]);
+};
+const withRibbon = async (sharp, image, env, box) => {
+    const ribbon = RIBBONS[env];
+    if (!ribbon) {
+        return image;
+    }
+    return sharp(image)
+        .composite([{ input: Buffer.from(ribbonSvg(MASTER, box, ribbon)) }])
+        .png(PNG)
+        .toBuffer();
+};
+const renderAndroid = async (sharp, appRoot, env, master, background) => {
+    const res = path.join(appRoot, 'android', 'app', 'src', flavorOf(env), 'res');
+    const full = await withRibbon(sharp, master, env, { x: 0, y: 0, size: MASTER });
+    const visible = Math.round((MASTER * ADAPTIVE_VISIBLE_DP) / ADAPTIVE_DP);
+    const inset = Math.round((MASTER - visible) / 2);
+    const inner = await sharp(master).resize(visible, visible).png(PNG).toBuffer();
+    const foregroundPlain = await sharp({
+        create: {
+            width: MASTER,
+            height: MASTER,
+            channels: 4,
+            background: { r: 0, g: 0, b: 0, alpha: 0 }
+        }
+    })
+        .composite([{ input: inner, left: inset, top: inset }])
+        .png(PNG)
+        .toBuffer();
+    const foreground = await withRibbon(sharp, foregroundPlain, env, {
+        x: inset,
+        y: inset,
+        size: visible
+    });
+    for (const [density, scale] of DENSITIES) {
+        const dir = path.join(res, `mipmap-${density}`);
+        removeOtherFormats(dir);
+        const legacy = Math.round(LEGACY_DP * scale);
+        const adaptive = Math.round(ADAPTIVE_DP * scale);
+        write(path.join(dir, 'ic_launcher.png'), await sharp(full).resize(legacy, legacy).png(PNG).toBuffer());
+        write(path.join(dir, 'ic_launcher_round.png'), await sharp(await sharp(full).resize(legacy, legacy).png(PNG).toBuffer())
+            .composite([{ input: Buffer.from(circleMaskSvg(legacy)), blend: 'dest-in' }])
+            .png(PNG)
+            .toBuffer());
+        write(path.join(dir, 'ic_launcher_foreground.png'), await sharp(foreground).resize(adaptive, adaptive).png(PNG).toBuffer());
+    }
+    const anydpi = path.join(res, 'mipmap-anydpi-v26');
+    removeOtherFormats(anydpi);
+    write(path.join(anydpi, 'ic_launcher.xml'), ADAPTIVE_ICON_XML);
+    write(path.join(anydpi, 'ic_launcher_round.xml'), ADAPTIVE_ICON_XML);
+    const values = path.join(res, 'values');
+    assertNoColorClash(values, 'ic_launcher_background.xml');
+    write(path.join(values, 'ic_launcher_background.xml'), backgroundColorXml(background));
+    say(`icons: ${path.relative(appRoot, res)}`);
+};
+const renderIos = async (sharp, appRoot, projectName, env, master, background) => {
+    const catalog = path.join(appRoot, 'ios', projectName, 'Images.xcassets');
+    if (!existsSync(catalog)) {
+        fail(`${path.relative(appRoot, catalog)} not found: check "iosProjectName"`);
+    }
+    const set = path.join(catalog, `AppIcon-${env}.appiconset`);
+    // The set is generated whole: older per-size files would sit unreferenced beside the new one.
+    rmSync(set, { recursive: true, force: true });
+    const full = await withRibbon(sharp, master, env, { x: 0, y: 0, size: MASTER });
+    // The App Store rejects an icon with an alpha channel.
+    write(path.join(set, IOS_ICON_FILE), await sharp(full).flatten({ background }).png(PNG).toBuffer());
+    write(path.join(set, 'Contents.json'), iosContentsJson());
+    say(`icons: ${path.relative(appRoot, set)}`);
+};
+/**
+ * Renders every environment's launcher icons from one source: Android per flavor (legacy,
+ * round and adaptive) and an iOS AppIcon-<Env> set, which prebuild then selects.
+ */
+export const icons = async (options) => {
+    const { appRoot } = options;
+    const config = loadToolsConfig(appRoot);
+    const source = options.source ??
+        config.iconSource ??
+        fail('no icon source: pass --source <png|svg> or set "iconSource" in mobile-tools.config.json', 2);
+    const file = path.resolve(appRoot, source);
+    if (!existsSync(file)) {
+        fail(`icon source not found: ${file}`);
+    }
+    const { default: sharp } = await import('sharp');
+    const master = await loadMaster(sharp, file);
+    const background = await cornerColor(sharp, master);
+    const projectName = resolveIosProjectName(appRoot, config);
+    const hasAndroid = existsSync(path.join(appRoot, 'android'));
+    if (hasAndroid && !config.flavors) {
+        say('icons: Android skipped, "flavors" is false: per-environment icons live in flavor source sets');
+    }
+    for (const env of ENVIRONMENTS) {
+        if (hasAndroid && config.flavors) {
+            await renderAndroid(sharp, appRoot, env, master, background);
+        }
+        if (projectName) {
+            await renderIos(sharp, appRoot, projectName, env, master, background);
+        }
+    }
+};

package/lib/ios.js

@@ -0,0 +1,78 @@
+import { mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { capture } from './exec.js';
+import { fail } from './output.js';
+import { XCRUN } from './platform.js';
+/** Booted simulators from `xcrun simctl list -j devices booted`. */
+export const parseSimctlBooted = (json) => {
+    const parsed = JSON.parse(json);
+    return Object.values(parsed.devices ?? {})
+        .flat()
+        .filter((device) => device.state === 'Booted')
+        .map((device) => ({
+        udid: device.udid,
+        name: device.name,
+        kind: 'simulator',
+        serials: [device.udid],
+        model: device.name
+    }));
+};
+/** Paired, reachable iOS devices from `xcrun devicectl list devices --json-output`. */
+export const parseDevicectl = (json) => {
+    const parsed = JSON.parse(json);
+    return (parsed.result?.devices ?? [])
+        .filter((device) => device.hardwareProperties?.platform === 'iOS' &&
+        device.connectionProperties?.pairingState === 'paired' &&
+        device.connectionProperties?.tunnelState !== 'unavailable' &&
+        device.hardwareProperties?.udid)
+        .map((device) => {
+        const udid = device.hardwareProperties?.udid;
+        const name = device.deviceProperties?.name ?? udid;
+        return {
+            udid,
+            name,
+            kind: 'device',
+            serials: [udid, device.identifier ?? udid],
+            model: name
+        };
+    });
+};
+export const listAppleDevices = (cwd) => {
+    const sims = capture({ file: XCRUN, args: ['simctl', 'list', '-j', 'devices', 'booted'] }, cwd);
+    if (sims.status !== 0) {
+        return fail(`xcrun simctl failed: ${sims.stderr.trim()}`);
+    }
+    const devices = parseSimctlBooted(sims.stdout);
+    const dir = mkdtempSync(path.join(tmpdir(), 'mobile-tools-'));
+    const out = path.join(dir, 'devices.json');
+    try {
+        const listed = capture({ file: XCRUN, args: ['devicectl', 'list', 'devices', '--json-output', out] }, cwd);
+        if (listed.status === 0) {
+            devices.push(...parseDevicectl(readFileSync(out, 'utf8')));
+        }
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+    if (devices.length === 0) {
+        return fail('no booted simulator or connected iPhone: boot one with xcrun simctl boot <name>');
+    }
+    return devices;
+};
+export const describeAppleDevice = (device) => `${device.name} (${device.kind}, ${device.udid})`;
+/** xcodebuild arguments for a Debug build of one destination into ios/build. */
+export const xcodebuildArgs = (projectName, udid) => [
+    '-workspace',
+    path.join('ios', `${projectName}.xcworkspace`),
+    '-scheme',
+    projectName,
+    '-configuration',
+    'Debug',
+    '-destination',
+    `id=${udid}`,
+    '-derivedDataPath',
+    path.join('ios', 'build'),
+    'ONLY_ACTIVE_ARCH=YES',
+    'build'
+];

package/lib/metro.js

@@ -0,0 +1,82 @@
+import { createRequire } from 'node:module';
+import { createServer } from 'node:net';
+import path from 'node:path';
+import { startDetached } from './exec.js';
+import { fail, say } from './output.js';
+export const DEFAULT_METRO_PORT = 8081;
+const samePath = (a, b) => {
+    const norm = (p) => {
+        const resolved = path.resolve(p).replace(/[\\/]+$/, '');
+        return process.platform === 'win32' ? resolved.toLowerCase() : resolved;
+    };
+    return norm(a) === norm(b);
+};
+/**
+ * Whether the Metro answering on a port serves this app. The CLI's dev server names its project
+ * root in the X-React-Native-Project-Root header; a server that does not say is treated as
+ * another project's.
+ */
+export const classifyStatus = (body, projectRootHeader, appRoot) => {
+    if (!body.includes('packager-status:running')) {
+        return 'other';
+    }
+    const root = projectRootHeader ?? /project-root:(.+)/.exec(body)?.[1]?.trim();
+    return root && samePath(root, appRoot) ? 'ours' : 'other';
+};
+const portIsFree = (port) => new Promise((resolve) => {
+    const server = createServer();
+    server.once('error', () => resolve(false));
+    server.once('listening', () => server.close(() => resolve(true)));
+    server.listen(port);
+});
+export const probeMetro = async (port, appRoot) => {
+    try {
+        const response = await fetch(`http://localhost:${port}/status`, {
+            signal: AbortSignal.timeout(1000)
+        });
+        return classifyStatus(await response.text(), response.headers.get('X-React-Native-Project-Root'), appRoot);
+    }
+    catch {
+        return (await portIsFree(port)) ? 'free' : 'other';
+    }
+};
+const waitForMetro = async (port, appRoot, logFile) => {
+    const deadline = Date.now() + 120_000;
+    while (Date.now() < deadline) {
+        if ((await probeMetro(port, appRoot)) === 'ours') {
+            return;
+        }
+        await new Promise((resolve) => setTimeout(resolve, 500));
+    }
+    fail(`Metro did not answer on port ${port} within 2 minutes; see ${logFile}`);
+};
+/**
+ * A Metro serving this app: reuses one already running for it, otherwise starts one detached on
+ * 8081 or, when another project holds 8081, the next free port. Never prompts. Returns the port.
+ */
+export const ensureMetro = async (appRoot, logFile, { fixedPort }) => {
+    const lastPort = fixedPort ? DEFAULT_METRO_PORT : DEFAULT_METRO_PORT + 19;
+    for (let port = DEFAULT_METRO_PORT; port <= lastPort; port++) {
+        const state = await probeMetro(port, appRoot);
+        if (state === 'ours') {
+            say(`metro: reusing the server on port ${port}`);
+            return port;
+        }
+        if (state === 'free') {
+            let cli;
+            try {
+                cli = createRequire(path.join(appRoot, 'package.json')).resolve('react-native/cli.js');
+            }
+            catch {
+                return fail('react-native is not installed in this app; run npx mobile-tools sync');
+            }
+            startDetached({ file: process.execPath, args: [cli, 'start', '--port', String(port)] }, appRoot, logFile);
+            say(`metro: started on port ${port}, log ${logFile}`);
+            await waitForMetro(port, appRoot, logFile);
+            return port;
+        }
+    }
+    return fail(fixedPort
+        ? 'port 8081 is held by another server (the iOS app always looks there); stop it and rerun'
+        : 'ports 8081-8100 are all held by other servers; stop one and rerun');
+};

package/lib/output.js

@@ -0,0 +1,18 @@
+/** A failure the CLI reports as one message and a non-zero exit, without a stack trace. */
+export class CliError extends Error {
+    exitCode;
+    constructor(message, exitCode = 1) {
+        super(message);
+        this.name = 'CliError';
+        this.exitCode = exitCode;
+    }
+}
+export const fail = (message, exitCode = 1) => {
+    throw new CliError(message, exitCode);
+};
+export const say = (message) => {
+    process.stdout.write(`${message}\n`);
+};
+export const warn = (message) => {
+    process.stderr.write(`${message}\n`);
+};

package/lib/platform.js

@@ -0,0 +1,122 @@
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { fail } from './output.js';
+/** The path flavour of the host, so a Windows path is built with Windows rules on any machine. */
+export const pathFor = (platform) => platform === 'win32' ? path.win32 : path.posix;
+/** Windows env keys are case-insensitive: `Path` and `PATH` are one variable. */
+const readEnv = (env, name) => {
+    const key = Object.keys(env).find((k) => k.toLowerCase() === name.toLowerCase());
+    return key === undefined ? undefined : env[key];
+};
+/**
+ * The environment every child gets. `NoDefaultCurrentDirectoryInExePath` is set by some agent
+ * shells and stops cmd.exe finding `gradlew.bat` in the current folder, so it never reaches a
+ * child, under any casing.
+ */
+export const childEnv = (env) => {
+    const out = {};
+    for (const [key, value] of Object.entries(env)) {
+        if (key.toLowerCase() !== 'nodefaultcurrentdirectoryinexepath') {
+            out[key] = value;
+        }
+    }
+    return out;
+};
+/** The absolute path of a program on PATH. On Windows only `.exe` counts: nothing here spawns a script shim. */
+export const findOnPath = (name, env, platform, exists = existsSync) => {
+    const p = pathFor(platform);
+    const searchPath = readEnv(env, 'PATH') ?? '';
+    const file = platform === 'win32' ? `${name}.exe` : name;
+    for (const dir of searchPath.split(platform === 'win32' ? ';' : ':')) {
+        if (dir === '') {
+            continue;
+        }
+        const candidate = p.join(dir, file);
+        if (exists(candidate)) {
+            return candidate;
+        }
+    }
+    return undefined;
+};
+/** adb from the SDK named by ANDROID_HOME, else the first adb on PATH. */
+export const adbPath = (env, platform, exists = existsSync) => {
+    const p = pathFor(platform);
+    const home = readEnv(env, 'ANDROID_HOME');
+    if (home) {
+        const candidate = p.join(home, 'platform-tools', platform === 'win32' ? 'adb.exe' : 'adb');
+        if (exists(candidate)) {
+            return candidate;
+        }
+    }
+    return (findOnPath('adb', env, platform, exists) ??
+        fail('adb not found: set ANDROID_HOME to the Android SDK (adb lives in its platform-tools folder) or put adb on PATH.'));
+};
+/** Gradle arguments are fixed task names and properties; anything else would need quoting cmd.exe cannot be trusted with. */
+const SAFE_GRADLE_ARG = /^[A-Za-z0-9_:.=-]+$/;
+/**
+ * How to run the Gradle wrapper. POSIX runs `android/gradlew` directly. Windows runs
+ * `android/gradlew.bat`, which Node can only start through cmd.exe (it refuses to spawn a .bat
+ * without a shell), so cmd.exe is named by absolute path and every argument is checked to be a
+ * plain token first.
+ */
+export const gradleInvocation = (androidDir, args, platform, env) => {
+    for (const arg of args) {
+        if (!SAFE_GRADLE_ARG.test(arg)) {
+            fail(`refusing Gradle argument ${JSON.stringify(arg)}: only plain task names and -Pkey=value`);
+        }
+    }
+    const p = pathFor(platform);
+    if (platform !== 'win32') {
+        return { file: p.join(androidDir, 'gradlew'), args };
+    }
+    const wrapper = p.join(androidDir, 'gradlew.bat');
+    if (/["%]/.test(wrapper)) {
+        fail(`the app path cannot hold " or %: ${wrapper}`);
+    }
+    const systemRoot = readEnv(env, 'SystemRoot') ?? 'C:\\Windows';
+    const cmd = readEnv(env, 'ComSpec') ?? p.join(systemRoot, 'System32', 'cmd.exe');
+    return {
+        file: cmd,
+        args: ['/d', '/s', '/c', `""${wrapper}" ${args.join(' ')}"`],
+        windowsVerbatimArguments: true
+    };
+};
+/** iOS commands exist only on macOS; elsewhere they stop with one line. */
+export const requireDarwin = (platform, what) => {
+    if (platform !== 'darwin') {
+        fail(`${what} needs macOS: xcodebuild and xcrun exist only there.`);
+    }
+};
+export const XCRUN = '/usr/bin/xcrun';
+export const XCODEBUILD = '/usr/bin/xcodebuild';
+/**
+ * npm as `node <npm-cli.js>`: on Windows `npm` is a .cmd shim Node will not spawn without a
+ * shell. npm_execpath is set when this CLI itself runs under npm or npx.
+ */
+export const npmInvocation = (args, env, platform, execPath, exists = existsSync) => {
+    const p = pathFor(platform);
+    const fromEnv = readEnv(env, 'npm_execpath');
+    const candidates = [
+        fromEnv && /npm-cli\.c?js$/.test(fromEnv) ? fromEnv : undefined,
+        platform === 'win32'
+            ? p.join(p.dirname(execPath), 'node_modules', 'npm', 'bin', 'npm-cli.js')
+            : p.join(p.dirname(execPath), '..', 'lib', 'node_modules', 'npm', 'bin', 'npm-cli.js')
+    ];
+    const cli = candidates.find((c) => c !== undefined && exists(c));
+    if (!cli) {
+        return fail(`npm not found beside ${execPath}; install Node 24 with its bundled npm.`);
+    }
+    return { file: execPath, args: [cli, ...args] };
+};
+/** pnpm as its own executable, or as `node <pnpm.cjs>` when this CLI runs under pnpm. */
+export const pnpmInvocation = (args, env, platform, execPath, exists = existsSync) => {
+    const fromEnv = readEnv(env, 'npm_execpath');
+    if (fromEnv && /pnpm\.c?js$/.test(fromEnv) && exists(fromEnv)) {
+        return { file: execPath, args: [fromEnv, ...args] };
+    }
+    const exe = findOnPath('pnpm', env, platform, exists);
+    if (!exe) {
+        return fail('pnpm not found on PATH (on Windows, pnpm.exe); install pnpm, or run through pnpm exec.');
+    }
+    return { file: exe, args };
+};