@webority/mobile-tools 0.0.0-stage → 0.1.0

package/lib/prebuild.js

@@ -0,0 +1,206 @@
+import { copyFileSync, existsSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { applicationId, COMPILED_FILE, ENVIRONMENTS, gradleAppId, lastCompiledEnvironment, loadAppSettings, loadToolsConfig, resolveIosProjectName } from './config.js';
+import { capture } from './exec.js';
+import { fail, say } from './output.js';
+import { findOnPath } from './platform.js';
+const eolOf = (text) => (text.includes('\r\n') ? '\r\n' : '\n');
+/**
+ * Sets each key in a .properties text, keeping every other line, comment, the order, the line
+ * endings and the presence or absence of a final newline. Missing keys are appended.
+ */
+export const rewriteGradleProperties = (text, values) => {
+    const eol = eolOf(text);
+    const lines = text.split(eol);
+    const pending = new Map(Object.entries(values));
+    const out = lines.map((line) => {
+        const match = /^\s*([A-Za-z0-9_.-]+)\s*[=:]/.exec(line);
+        if (match && pending.has(match[1])) {
+            const key = match[1];
+            const value = pending.get(key);
+            pending.delete(key);
+            return `${key}=${value}`;
+        }
+        return line;
+    });
+    if (pending.size === 0) {
+        return out.join(eol);
+    }
+    const added = [...pending].map(([key, value]) => `${key}=${value}`);
+    const endsWithNewline = out.length > 1 && out[out.length - 1] === '';
+    if (endsWithNewline) {
+        out.splice(out.length - 1, 0, ...added);
+    }
+    else if (out.length === 1 && out[0] === '') {
+        out.splice(0, 1, ...added);
+    }
+    else {
+        out.push(...added);
+    }
+    return out.join(eol);
+};
+/** Xcode leaves a value bare when it is one plain token and quotes it otherwise. */
+const pbxValue = (value) => /^[A-Za-z0-9._/-]+$/.test(value) ? value : `"${value.replace(/"/g, '\\"')}"`;
+/**
+ * Sets every occurrence of each build setting in a project.pbxproj (one per build
+ * configuration). A setting the project does not carry fails: writing it in would need a guess
+ * at which configurations it belongs to.
+ */
+export const rewritePbxproj = (text, settings, options = {}) => {
+    let out = text;
+    for (const [setting, value] of Object.entries(settings)) {
+        const pattern = new RegExp(`(\\s)${setting} = [^;\\n]*;`, 'g');
+        if (!pattern.test(out)) {
+            fail(`${setting} not found in project.pbxproj`);
+        }
+        const rendered = options.quote?.includes(setting)
+            ? `"${value.replace(/"/g, '\\"')}"`
+            : pbxValue(value);
+        out = out.replace(pattern, (_match, lead) => `${lead}${setting} = ${rendered};`);
+    }
+    return out;
+};
+const escapeXml = (value) => value.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+/** Sets CFBundleDisplayName in an Info.plist text; a plist without the key fails. */
+export const rewriteInfoPlistDisplayName = (text, displayName) => {
+    const pattern = /(<key>CFBundleDisplayName<\/key>\s*<string>)[^<]*(<\/string>)/;
+    if (!pattern.test(text)) {
+        fail('CFBundleDisplayName not found in Info.plist');
+    }
+    return text.replace(pattern, (_m, open, close) => `${open}${escapeXml(displayName)}${close}`);
+};
+/** Paths, relative to the app root, that prebuild writes and the dirty check must ignore. */
+export const prebuildOutputs = (iosProjectName) => {
+    const outputs = [COMPILED_FILE, 'android/gradle.properties'];
+    if (iosProjectName) {
+        outputs.push(`ios/${iosProjectName}/Info.plist`, `ios/${iosProjectName}.xcodeproj/project.pbxproj`, `ios/${iosProjectName}/GoogleService-Info.plist`);
+    }
+    return outputs;
+};
+/**
+ * The short HEAD sha, with -dirty when the app folder has uncommitted changes other than the
+ * files prebuild itself writes (or every build after an environment switch would read dirty).
+ * "nogit" when the folder is not a git checkout.
+ */
+export const buildCommit = (appRoot, excludes) => {
+    const git = findOnPath('git', process.env, process.platform);
+    if (!git) {
+        return 'nogit';
+    }
+    const sha = capture({ file: git, args: ['rev-parse', '--short', 'HEAD'] }, appRoot);
+    if (sha.status !== 0) {
+        return 'nogit';
+    }
+    const status = capture({
+        file: git,
+        args: ['status', '--porcelain', '--', '.', ...excludes.map((p) => `:(exclude)${p}`)]
+    }, appRoot);
+    if (status.status !== 0) {
+        return fail(`git status failed in ${appRoot}: ${status.stderr.trim()}`);
+    }
+    return status.stdout.trim() === '' ? sha.stdout.trim() : `${sha.stdout.trim()}-dirty`;
+};
+/** Writes a file only when its content changes, so an unchanged native file keeps its mtime. */
+const writeIfChanged = (file, content) => {
+    if (existsSync(file) && readFileSync(file, 'utf8') === content) {
+        return false;
+    }
+    writeFileSync(file, content, 'utf8');
+    return true;
+};
+const report = (appRoot, file, changed) => {
+    say(`prebuild: ${changed ? 'wrote' : 'unchanged'} ${path.relative(appRoot, file)}`);
+};
+export const stampAndroid = (appRoot, settings, env, config) => {
+    const file = path.join(appRoot, 'android', 'gradle.properties');
+    if (!existsSync(file)) {
+        fail(`android/gradle.properties not found in ${appRoot}`);
+    }
+    const next = rewriteGradleProperties(readFileSync(file, 'utf8'), {
+        APP_NAME: String(settings.APP_NAME),
+        APP_ID: gradleAppId(settings.APP_ID, env, config.flavors),
+        VERSION_DISPLAY: String(settings.VERSION_DISPLAY),
+        VERSION_INTERNAL: String(settings.VERSION_INTERNAL)
+    });
+    report(appRoot, file, writeIfChanged(file, next));
+};
+export const stampIos = (appRoot, settings, env, config, projectName) => {
+    const projectDir = path.join(appRoot, 'ios', projectName);
+    const infoPlist = path.join(projectDir, 'Info.plist');
+    const pbxproj = path.join(appRoot, 'ios', `${projectName}.xcodeproj`, 'project.pbxproj');
+    for (const file of [infoPlist, pbxproj]) {
+        if (!existsSync(file)) {
+            fail(`${path.relative(appRoot, file)} not found: check "iosProjectName"`);
+        }
+    }
+    const iconSet = `AppIcon-${env}`;
+    const catalog = path.join(projectDir, 'Images.xcassets');
+    const hasIconSet = existsSync(path.join(catalog, `${iconSet}.appiconset`));
+    const otherSets = ENVIRONMENTS.filter((other) => other !== env && existsSync(path.join(catalog, `AppIcon-${other}.appiconset`)));
+    if (!hasIconSet && otherSets.length > 0) {
+        // Leaving the setting would ship another environment's icon.
+        fail(`ios/${projectName}/Images.xcassets has AppIcon-${otherSets[0]} but no ${iconSet}: run mobile-tools icons`);
+    }
+    report(appRoot, infoPlist, writeIfChanged(infoPlist, rewriteInfoPlistDisplayName(readFileSync(infoPlist, 'utf8'), String(settings.APP_NAME))));
+    const settingsToWrite = {
+        PRODUCT_BUNDLE_IDENTIFIER: applicationId(settings.APP_ID, env),
+        MARKETING_VERSION: String(settings.VERSION_DISPLAY),
+        CURRENT_PROJECT_VERSION: String(settings.VERSION_INTERNAL)
+    };
+    if (hasIconSet) {
+        settingsToWrite.ASSETCATALOG_COMPILER_APPICON_NAME = iconSet;
+    }
+    report(appRoot, pbxproj, writeIfChanged(pbxproj, rewritePbxproj(readFileSync(pbxproj, 'utf8'), settingsToWrite, {
+        quote: ['PRODUCT_BUNDLE_IDENTIFIER']
+    })));
+    if (!hasIconSet) {
+        say(`prebuild: no AppIcon-<Env> sets, app icon left as the project sets it`);
+    }
+    const firebaseTarget = path.join(projectDir, 'GoogleService-Info.plist');
+    const firebaseSource = path.join(appRoot, config.firebasePlistDir, `GoogleService-Info.${env}.plist`);
+    if (existsSync(firebaseSource)) {
+        const changed = !existsSync(firebaseTarget) ||
+            !readFileSync(firebaseSource).equals(readFileSync(firebaseTarget));
+        if (changed) {
+            copyFileSync(firebaseSource, firebaseTarget);
+        }
+        report(appRoot, firebaseTarget, changed);
+    }
+    else if (existsSync(firebaseTarget)) {
+        // A build must never ship another environment's Firebase identity.
+        rmSync(firebaseTarget);
+        say(`prebuild: removed ${path.relative(appRoot, firebaseTarget)}, no ${path.relative(appRoot, firebaseSource)}`);
+    }
+};
+/** Compiles appsettings and stamps the native layers. Returns the settings it compiled. */
+export const prebuild = (options) => {
+    const { appRoot, sameEnv, platform } = options;
+    if (sameEnv && options.env) {
+        fail('pass --env or --same-env, not both', 2);
+    }
+    const env = sameEnv ? lastCompiledEnvironment(appRoot) : options.env;
+    if (!env) {
+        return fail('prebuild needs --env <Development|Staging|Production> or --same-env', 2);
+    }
+    const config = loadToolsConfig(appRoot);
+    const projectName = resolveIosProjectName(appRoot, config);
+    const settings = loadAppSettings(appRoot, env);
+    const compiled = {
+        ...settings,
+        COMMIT: buildCommit(appRoot, prebuildOutputs(projectName)),
+        BUILD_TIME: new Date().toISOString()
+    };
+    writeFileSync(path.join(appRoot, COMPILED_FILE), `${JSON.stringify(compiled, null, 2)}\n`, 'utf8');
+    say(`prebuild: wrote ${COMPILED_FILE} (${env}, ${compiled.COMMIT})`);
+    const hasAndroid = existsSync(path.join(appRoot, 'android'));
+    if (platform === 'android' || (!platform && hasAndroid)) {
+        stampAndroid(appRoot, compiled, env, config);
+    }
+    if (platform === 'ios' || (!platform && projectName)) {
+        if (!projectName) {
+            return fail(`no ios/ folder in ${appRoot}`);
+        }
+        stampIos(appRoot, compiled, env, config, projectName);
+    }
+    return compiled;
+};

package/lib/rootError.js

@@ -0,0 +1,41 @@
+const MAX_LINES = 40;
+const blockFrom = (lines, start, isEnd) => {
+    const block = [];
+    for (let i = start; i < lines.length && block.length < MAX_LINES; i++) {
+        if (i > start && isEnd(lines[i])) {
+            break;
+        }
+        block.push(lines[i]);
+    }
+    while (block.length > 0 && block[block.length - 1].trim() === '') {
+        block.pop();
+    }
+    return block;
+};
+/**
+ * The one part of a build log worth printing. Metro's "Unable to resolve module" comes first
+ * when present: Gradle reports that failure only as a generic non-zero exit of the bundling
+ * command, at the very end of the build. Then Gradle's first "What went wrong" block, then
+ * compiler-style "error:" lines (xcodebuild), then the log's tail.
+ */
+export const extractRootError = (log) => {
+    const lines = log.split(/\r?\n/);
+    const metro = lines.findIndex((line) => line.includes('Unable to resolve module'));
+    if (metro >= 0) {
+        return blockFrom(lines, metro, (line) => line.trim() === '').join('\n');
+    }
+    const gradle = lines.findIndex((line) => line.trim() === '* What went wrong:');
+    if (gradle >= 0) {
+        return blockFrom(lines, gradle + 1, (line) => /^\* [A-Z]/.test(line)).join('\n');
+    }
+    const errors = [
+        ...new Set(lines.filter((line) => /(^|\s)error:/.test(line)).map((l) => l.trim()))
+    ];
+    if (errors.length > 0) {
+        return errors.slice(0, 10).join('\n');
+    }
+    return lines
+        .filter((line) => line.trim() !== '')
+        .slice(-20)
+        .join('\n');
+};

package/lib/run.js

@@ -0,0 +1,140 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { apkDir, applicationId, assembleTask, loadAppSettings, loadToolsConfig, localApiPort, resolveIosProjectName } from './config.js';
+import { describeDevice, listAndroidDevices, pickDevice } from './devices.js';
+import { capture, runToLog } from './exec.js';
+import { describeAppleDevice, listAppleDevices, xcodebuildArgs } from './ios.js';
+import { ensureMetro } from './metro.js';
+import { CliError, fail, say } from './output.js';
+import { adbPath, gradleInvocation, requireDarwin, XCODEBUILD, XCRUN } from './platform.js';
+import { prebuild } from './prebuild.js';
+import { extractRootError } from './rootError.js';
+import { checkSync } from './sync.js';
+/** The Android namespace from build.gradle (`namespace "x"` or `namespace = 'x'`); MainActivity lives in it. */
+export const readNamespace = (buildGradle) => /^\s*namespace\s*=?\s*["']([^"']+)["']/m.exec(buildGradle)?.[1];
+/** The ABI token Gradle receives; anything else from a device is refused rather than passed on. */
+export const ABI_PATTERN = /^(arm64-v8a|armeabi-v7a|x86_64|x86)$/;
+/** The APK a debug build produced, preferring one built for the device's ABI. */
+export const chooseApk = (files, abi) => {
+    const apks = files.filter((file) => file.endsWith('.apk')).sort();
+    return (apks.find((file) => file.includes(abi)) ??
+        apks.find((file) => file.includes('universal')) ??
+        apks[0]);
+};
+/** Where run writes its build and Metro logs: inside node_modules/.cache, which no repo tracks. */
+export const logDir = (appRoot) => path.join(appRoot, 'node_modules', '.cache', 'mobile-tools');
+const stamp = () => new Date().toISOString().replace(/[:.]/g, '-');
+const guardSync = (appRoot) => {
+    const problems = checkSync(appRoot, process.platform);
+    if (problems.length > 0) {
+        fail(problems.join('\n'));
+    }
+};
+const buildOrFail = async (invocation, cwd, logFile, what) => {
+    say(`${what}: building, log ${logFile}`);
+    const started = Date.now();
+    const status = await runToLog(invocation, cwd, logFile);
+    if (status !== 0) {
+        const root = existsSync(logFile) ? extractRootError(readFileSync(logFile, 'utf8')) : '';
+        throw new CliError(`${what} failed:\n${root}\nFull log: ${logFile}`);
+    }
+    say(`${what}: built in ${Math.round((Date.now() - started) / 1000)} s`);
+};
+const adbOrFail = (adb, args, cwd) => {
+    const result = capture({ file: adb, args }, cwd);
+    if (result.status !== 0) {
+        return fail(`adb ${args.join(' ')} failed: ${(result.stderr || result.stdout).trim()}`);
+    }
+    return result.stdout;
+};
+const runAndroid = async (options) => {
+    const { appRoot, env } = options;
+    const config = loadToolsConfig(appRoot);
+    const androidDir = path.join(appRoot, 'android');
+    const buildGradle = path.join(androidDir, 'app', 'build.gradle');
+    if (!existsSync(buildGradle)) {
+        fail(`android/app/build.gradle not found in ${appRoot}`);
+    }
+    const namespace = readNamespace(readFileSync(buildGradle, 'utf8')) ??
+        fail('android/app/build.gradle declares no namespace');
+    const adb = adbPath(process.env, process.platform);
+    const devices = listAndroidDevices(adb, appRoot);
+    const device = await pickDevice(devices, options.device, describeDevice, process.stdin.isTTY === true);
+    if (!ABI_PATTERN.test(device.abi)) {
+        fail(`${describeDevice(device)} reports an ABI this build cannot target: "${device.abi}"`);
+    }
+    say(`run: ${describeDevice(device)}`);
+    const settings = prebuild({ appRoot, env, platform: 'android' });
+    const task = assembleTask(env, config.flavors);
+    const logs = logDir(appRoot);
+    await buildOrFail(gradleInvocation(androidDir, [`:app:${task}`, `-PreactNativeArchitectures=${device.abi}`], process.platform, process.env), androidDir, path.join(logs, `gradle-${env}-${stamp()}.log`), `gradle ${task}`);
+    const dir = apkDir(appRoot, env, config.flavors);
+    const apk = existsSync(dir) ? chooseApk(readdirSync(dir), device.abi) : undefined;
+    if (!apk) {
+        fail(`the build produced no APK in ${dir}`);
+    }
+    say(`run: installing ${apk} on ${device.serial}`);
+    adbOrFail(adb, ['-s', device.serial, 'install', '-r', path.join(dir, apk)], appRoot);
+    const port = await ensureMetro(appRoot, path.join(logs, 'metro.log'), { fixedPort: false });
+    adbOrFail(adb, ['-s', device.serial, 'reverse', 'tcp:8081', `tcp:${port}`], appRoot);
+    if (env === 'Development') {
+        const apiPort = localApiPort(String(loadAppSettings(appRoot, 'Development').BASE_URL), config);
+        if (apiPort !== undefined) {
+            adbOrFail(adb, ['-s', device.serial, 'reverse', `tcp:${apiPort}`, `tcp:${apiPort}`], appRoot);
+            say(`run: device localhost:${apiPort} reaches this machine's API`);
+        }
+    }
+    const appId = applicationId(settings.APP_ID, env);
+    adbOrFail(adb, ['-s', device.serial, 'shell', 'am', 'start', '-n', `${appId}/${namespace}.MainActivity`], appRoot);
+    say(`run: launched ${appId} on ${device.model || device.serial}`);
+};
+const runIos = async (options) => {
+    requireDarwin(process.platform, 'run --platform ios');
+    const { appRoot, env } = options;
+    const config = loadToolsConfig(appRoot);
+    const projectName = resolveIosProjectName(appRoot, config) ?? fail(`no ios/ folder in ${appRoot}`);
+    const workspace = path.join(appRoot, 'ios', `${projectName}.xcworkspace`);
+    if (!existsSync(workspace)) {
+        fail(`ios/${projectName}.xcworkspace not found: run npx mobile-tools sync (it runs pod install)`);
+    }
+    const device = await pickDevice(listAppleDevices(appRoot), options.device, describeAppleDevice, process.stdin.isTTY === true);
+    say(`run: ${describeAppleDevice(device)}`);
+    const settings = prebuild({ appRoot, env, platform: 'ios' });
+    const logs = logDir(appRoot);
+    await buildOrFail({ file: XCODEBUILD, args: xcodebuildArgs(projectName, device.udid) }, appRoot, path.join(logs, `xcodebuild-${env}-${stamp()}.log`), 'xcodebuild');
+    const products = path.join(appRoot, 'ios', 'build', 'Build', 'Products', device.kind === 'simulator' ? 'Debug-iphonesimulator' : 'Debug-iphoneos');
+    const apps = existsSync(products) ? readdirSync(products).filter((n) => n.endsWith('.app')) : [];
+    const app = apps.find((name) => name === `${projectName}.app`) ?? apps[0];
+    if (!app) {
+        fail(`the build produced no .app in ${products}`);
+    }
+    const appPath = path.join(products, app);
+    const bundleId = applicationId(settings.APP_ID, env);
+    await ensureMetro(appRoot, path.join(logs, 'metro.log'), { fixedPort: true });
+    const steps = device.kind === 'simulator'
+        ? [
+            ['simctl', 'install', device.udid, appPath],
+            ['simctl', 'launch', device.udid, bundleId]
+        ]
+        : [
+            ['devicectl', 'device', 'install', 'app', '--device', device.udid, appPath],
+            ['devicectl', 'device', 'process', 'launch', '--device', device.udid, bundleId]
+        ];
+    for (const args of steps) {
+        const result = capture({ file: XCRUN, args }, appRoot);
+        if (result.status !== 0) {
+            fail(`xcrun ${args.slice(0, 3).join(' ')} failed: ${(result.stderr || result.stdout).trim()}`);
+        }
+    }
+    say(`run: launched ${bundleId} on ${device.name}`);
+};
+/** Guard, pick a device, prebuild, build for that device only, install, Metro, launch. */
+export const run = async (options) => {
+    guardSync(options.appRoot);
+    if (options.platform === 'ios') {
+        await runIos(options);
+    }
+    else {
+        await runAndroid(options);
+    }
+};

package/lib/sync.js

@@ -0,0 +1,205 @@
+import { createHash } from 'node:crypto';
+import { existsSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { runInherit } from './exec.js';
+import { fail, say } from './output.js';
+import { findOnPath, gradleInvocation, npmInvocation, pnpmInvocation } from './platform.js';
+export const STAMP_FILE = path.join('node_modules', '.webority-install.json');
+/** package.json fields that change what an install puts in node_modules. */
+const INSTALL_FIELDS = [
+    'dependencies',
+    'devDependencies',
+    'optionalDependencies',
+    'peerDependencies',
+    'bundleDependencies',
+    'overrides',
+    'resolutions',
+    'pnpm',
+    'workspaces'
+];
+export const lockfileOf = (appRoot) => {
+    const pnpm = path.join(appRoot, 'pnpm-lock.yaml');
+    const npm = path.join(appRoot, 'package-lock.json');
+    if (existsSync(pnpm) && existsSync(npm)) {
+        return fail('both pnpm-lock.yaml and package-lock.json exist: delete the one not in use');
+    }
+    if (existsSync(pnpm)) {
+        return { manager: 'pnpm', file: pnpm };
+    }
+    if (existsSync(npm)) {
+        return { manager: 'npm', file: npm };
+    }
+    return fail(`no package-lock.json or pnpm-lock.yaml in ${appRoot}`);
+};
+/** Every file under a folder, as forward-slash paths relative to it, sorted. */
+const filesUnder = (dir, prefix = '') => readdirSync(dir, { withFileTypes: true })
+    .flatMap((entry) => {
+    const relative = prefix === '' ? entry.name : `${prefix}/${entry.name}`;
+    return entry.isDirectory() ? filesUnder(path.join(dir, entry.name), relative) : [relative];
+})
+    .sort();
+/** One hash over the lockfile, the install-relevant package.json fields and patches/. */
+export const installHash = (appRoot) => {
+    const { file } = lockfileOf(appRoot);
+    const pkg = JSON.parse(readFileSync(path.join(appRoot, 'package.json'), 'utf8'));
+    const hash = createHash('sha256');
+    hash.update(`lockfile:${path.basename(file)}\0`);
+    hash.update(readFileSync(file));
+    hash.update('\0package.json\0');
+    hash.update(JSON.stringify(INSTALL_FIELDS.map((field) => [field, pkg[field] ?? null])));
+    const patches = path.join(appRoot, 'patches');
+    if (existsSync(patches)) {
+        for (const relative of filesUnder(patches)) {
+            hash.update(`\0patches/${relative}\0`);
+            hash.update(readFileSync(path.join(patches, ...relative.split('/'))));
+        }
+    }
+    return hash.digest('hex');
+};
+export const readStamp = (appRoot) => {
+    const file = path.join(appRoot, STAMP_FILE);
+    if (!existsSync(file)) {
+        return undefined;
+    }
+    try {
+        return JSON.parse(readFileSync(file, 'utf8'));
+    }
+    catch {
+        return undefined;
+    }
+};
+/** The fix command for an iOS Pods tree: through Bundler when the app pins CocoaPods in a Gemfile. */
+const podFix = (appRoot) => existsSync(path.join(appRoot, 'Gemfile'))
+    ? 'cd ios && bundle exec pod install'
+    : 'cd ios && pod install';
+export const podsStale = (appRoot) => {
+    const podfileLock = path.join(appRoot, 'ios', 'Podfile.lock');
+    const manifest = path.join(appRoot, 'ios', 'Pods', 'Manifest.lock');
+    if (!existsSync(podfileLock) || !existsSync(manifest)) {
+        return false;
+    }
+    return !readFileSync(podfileLock).equals(readFileSync(manifest));
+};
+/**
+ * What is stale, as messages that each end with the command that fixes it. Empty when the tree
+ * matches its lockfiles. Reads files only, so it answers well inside a second.
+ */
+export const checkSync = (appRoot, platform) => {
+    const problems = [];
+    const stamp = readStamp(appRoot);
+    const { file } = lockfileOf(appRoot);
+    if (!stamp) {
+        problems.push(`node_modules has no install stamp (never installed through mobile-tools). Fix: npx mobile-tools sync`);
+    }
+    else if (stamp.hash !== installHash(appRoot)) {
+        problems.push(`node_modules is stale: ${path.basename(file)}, package.json or patches/ changed since the last install. Fix: npx mobile-tools sync`);
+    }
+    if (platform === 'darwin' && podsStale(appRoot)) {
+        problems.push(`ios/Pods is stale: ios/Podfile.lock differs from ios/Pods/Manifest.lock. Fix: ${podFix(appRoot)}`);
+    }
+    return problems;
+};
+/** Top-level packages that ship an android/ folder, name to version. Autolinking reads only these. */
+export const nativePackages = (appRoot) => {
+    const modules = path.join(appRoot, 'node_modules');
+    if (!existsSync(modules)) {
+        return {};
+    }
+    const dirs = [];
+    for (const entry of readdirSync(modules, { withFileTypes: true })) {
+        if (entry.name.startsWith('.') || !entry.isDirectory()) {
+            continue;
+        }
+        if (entry.name.startsWith('@')) {
+            for (const scoped of readdirSync(path.join(modules, entry.name), { withFileTypes: true })) {
+                if (scoped.isDirectory()) {
+                    dirs.push(path.join(modules, entry.name, scoped.name));
+                }
+            }
+        }
+        else {
+            dirs.push(path.join(modules, entry.name));
+        }
+    }
+    const found = {};
+    for (const dir of dirs) {
+        const android = path.join(dir, 'android');
+        const manifest = path.join(dir, 'package.json');
+        if (!existsSync(android) || !statSync(android).isDirectory() || !existsSync(manifest)) {
+            continue;
+        }
+        try {
+            const pkg = JSON.parse(readFileSync(manifest, 'utf8'));
+            if (pkg.name && pkg.version) {
+                found[pkg.name] = pkg.version;
+            }
+        }
+        catch {
+            // A package with an unreadable package.json is not one autolinking can link either.
+        }
+    }
+    return found;
+};
+/** Native packages added, removed or moved between two snapshots, sorted. */
+export const changedNativePackages = (before, after) => [...new Set([...Object.keys(before), ...Object.keys(after)])]
+    .filter((name) => before[name] !== after[name])
+    .sort();
+/**
+ * Records that node_modules matches the lockfile now. `sync` calls it after its install; an app
+ * also calls it from `postinstall` (`mobile-tools sync --stamp`), so a plain `npm ci` or
+ * `pnpm install` leaves an accurate stamp and `sync --check` never asks for a needless reinstall.
+ */
+export const writeStamp = (appRoot) => {
+    const { manager } = lockfileOf(appRoot);
+    const stamp = {
+        hash: installHash(appRoot),
+        manager,
+        nativePackages: nativePackages(appRoot)
+    };
+    writeFileSync(path.join(appRoot, STAMP_FILE), `${JSON.stringify(stamp, null, 2)}\n`, 'utf8');
+    return stamp;
+};
+export const installInvocation = (manager, platform) => manager === 'pnpm'
+    ? pnpmInvocation(['install', '--frozen-lockfile'], process.env, platform, process.execPath)
+    : npmInvocation(['ci'], process.env, platform, process.execPath);
+/**
+ * Installs from the lockfile, stamps node_modules, and when a native package moved, regenerates
+ * library codegen and drops the CMake caches that still point at the old output. On macOS it
+ * also brings ios/Pods in line with Podfile.lock.
+ */
+export const sync = (appRoot, platform) => {
+    const { manager } = lockfileOf(appRoot);
+    const before = readStamp(appRoot)?.nativePackages ?? nativePackages(appRoot);
+    say(`sync: ${manager === 'pnpm' ? 'pnpm install --frozen-lockfile' : 'npm ci'}`);
+    runInherit(installInvocation(manager, platform), appRoot, `${manager} install`);
+    const after = writeStamp(appRoot).nativePackages;
+    const moved = changedNativePackages(before, after);
+    const androidDir = path.join(appRoot, 'android');
+    // With no .cxx and no app build yet there is no stale native state: the first build runs codegen itself.
+    const builtBefore = existsSync(path.join(androidDir, 'app', '.cxx')) ||
+        existsSync(path.join(androidDir, 'app', 'build'));
+    if (moved.length > 0 && builtBefore) {
+        say(`sync: native packages changed (${moved.join(', ')}): regenerating codegen`);
+        runInherit(gradleInvocation(androidDir, ['generateCodegenArtifactsFromSchema'], platform, process.env), androidDir, 'gradlew generateCodegenArtifactsFromSchema');
+        for (const stale of [
+            path.join(androidDir, 'app', '.cxx'),
+            path.join(androidDir, 'app', 'build', 'generated', 'autolinking')
+        ]) {
+            rmSync(stale, { recursive: true, force: true });
+            say(`sync: removed ${path.relative(appRoot, stale)}`);
+        }
+    }
+    if (platform === 'darwin' && existsSync(path.join(appRoot, 'ios', 'Podfile'))) {
+        const podfileLock = path.join(appRoot, 'ios', 'Podfile.lock');
+        const manifest = path.join(appRoot, 'ios', 'Pods', 'Manifest.lock');
+        if (!existsSync(podfileLock) || !existsSync(manifest) || podsStale(appRoot)) {
+            const useBundler = existsSync(path.join(appRoot, 'Gemfile'));
+            const tool = findOnPath(useBundler ? 'bundle' : 'pod', process.env, platform);
+            if (!tool) {
+                fail(`${useBundler ? 'bundle' : 'pod'} not found on PATH; install CocoaPods, then ${podFix(appRoot)}`);
+            }
+            runInherit({ file: tool, args: useBundler ? ['exec', 'pod', 'install'] : ['install'] }, path.join(appRoot, 'ios'), 'pod install');
+        }
+    }
+    say('sync: done');
+};

package/package.json

@@ -1,6 +1,53 @@
 {
   "name": "@webority/mobile-tools",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Dev-time CLI for Webority React Native apps: one prebuild, a dependency guard, a device-aware run and per-environment launcher icons, the same on Windows and macOS.",
+  "keywords": [
+    "react-native",
+    "cli",
+    "prebuild",
+    "android",
+    "ios",
+    "icons",
+    "webority"
+  ],
+  "homepage": "https://www.webority.com",
+  "license": "SEE LICENSE IN LICENSE.txt",
+  "author": {
+    "name": "Webority Technologies",
+    "email": "contact@webority.com",
+    "url": "https://www.webority.com"
+  },
+  "type": "module",
+  "bin": {
+    "mobile-tools": "lib/cli.js"
+  },
+  "exports": {
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "!**/__tests__",
+    "!**/*.test.*",
+    "!**/*.spec.*",
+    "!**/*.map"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "clean": "rimraf lib",
+    "lint": "biome lint ./src",
+    "lint:fix": "biome lint --write ./src",
+    "test": "jest",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "sharp": "^0.35.5"
+  },
+  "engines": {
+    "node": ">=24 <25"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}