catalyst-core 1.2.0-canary.2 → 1.2.0-canary.4

package/changelog.md

@@ -1,5 +1,39 @@
 # Changelog
 
+## [1.2.0] - Unreleased
+
+This release builds, runs and releases the Android and iOS apps from the CLI, without opening Android Studio or Xcode. The web runtime has no breaking changes. Universal apps should read the breaking changes below and the 1.1.x to 1.2.0 section of the Version Upgrades guide. After upgrading, run `npm audit fix`: the `body-parser` floor is raised to `^1.20.9`.
+
+### One command to run, one to release
+
+New apps have four scripts. `npm run android` and `npm run ios` check the toolchain and install what is missing after asking, start the dev server when nothing answers on `NODE_SERVER_PORT`, and build, install and open the app on an emulator, simulator or phone. Android also saves the app as a debug APK in `build-output/android/debug/` that can be shared. `npm run android:release` writes a signed App Bundle, a signed APK and `upload_certificate.pem` to `build-output/android/<version>-<build>/`, and `npm run ios:release` writes a signed IPA and a zip of its dSYMs to `build-output/ios/<version>-<build>/`. The scripts run `catalyst buildApp:android` and `catalyst buildApp:ios`, with `--release` for the store builds, so older apps keep `buildApp:<platform>` and build a release with `npm run buildApp:<platform> -- --release`. `setupEmulator:android` and `setupEmulator:ios` still work and are no longer needed.
+
+### App config
+
+A native app needs `WEBVIEW_CONFIG.appId`, `appName` and `url`. `appId` is the Android application id and the iOS bundle id, and `android.packageName` and `ios.bundleIdentifier` (then `ios.appBundleId`) win over it. `url` is the deployed site a release opens; debug builds load the dev server. New apps get `appId` and `appName` from the project name. A release run in a terminal asks once for an app id or website that is missing or a placeholder, and saves the answer to `config/config.json`.
+
+### Signing
+
+Signing files live in `credentials/android/` and `credentials/ios/`, which new apps keep out of git. The first Android release in a terminal creates one upload key per app after asking; back it up, because Google Play only accepts updates signed with it. `npx catalyst credentials:export <platform>` prints the folder as one value for the `CATALYST_ANDROID_CREDENTIALS` or `CATALYST_IOS_CREDENTIALS` CI secret. On a Mac signed in to Xcode, an iOS release signs with the Apple account or an installed App Store profile and needs no files; the order the build tries is in the iOS release guide. The version comes from `package.json`, and the build number is `CATALYST_BUILD_NUMBER` or the minutes since 2024-01-01 UTC. Android apps target API 36 and align their native libraries for 16 KB memory pages.
+
+### Breaking changes
+
+- An iOS bundle id with an underscore fails with `NATIVE-010`. Set `ios.bundleIdentifier` to an id without one.
+- A release with a placeholder app id (any `com.example.` id or a template id) fails with `NATIVE-003`. A release whose start URL is `localhost`, a private or link-local address, a `.local` name or this machine fails with `NATIVE-001`, unless `WEBVIEW_CONFIG.allowPrivateHost` is `true`. Run in a terminal, the build asks for the value instead.
+- A debug build no longer installs on a connected phone by itself. A terminal run asks once where to run the app and remembers the answer in `.catalyst/local.json`; without a terminal the emulator or simulator is used. Pass `--device` for the phone.
+- The first debug build rewrites `config/config.json` once: a value equal to this machine's LAN address, and a private `LOCAL_IP` that `NODE_SERVER_HOSTNAME` also holds, go back to `localhost`. Each change is printed. It never runs for a release, in CI or with `allowPrivateHost: true`.
+- Keystore passwords in `android.keystoreConfig` and `android.keystore` are no longer used. Apps that uploaded a build signed with the keystore shipped in the template, or with a key generated by an earlier release build, need an upload key reset in Play Console.
+
+### create-catalyst-app
+
+New apps get a new starter page, an animated HTML splash screen that is on by default (`splashScreen.minDuration` `7000`), a restyled offline page, a placeholder `public/icon.png`, and a `server/index.js` with an empty stub for `preServerInit` and each per-request hook. Their `.gitignore` covers `credentials/`, `.catalyst/` and `build-output/`.
+
+### Fixes
+
+- `MetaTag` waits for a `split()` route's chunk before it replaces the head tags, so the server's tags are no longer removed before the route's `setMetaData` is available.
+- Startup warns when `server/index.js` puts a lifecycle hook inside `export default { ... }`, where Catalyst never calls it. Export each hook by name.
+- `npm run start` prints a hint when `NODE_SERVER_HOSTNAME` is not an address of this machine.
+
 ## [1.1.0] - 2026-10-22
 
 This release contains everything in 1.0.2, namely the HTML splash screen, experimental WebMCP support and the new CLI output, plus one fix. There are no breaking API changes.

package/dist/cli/hints.js

@@ -27,6 +27,11 @@ const HINTS = [
                 : `Something is already on ${where}. Stop it, or set NODE_SERVER_PORT in config/config.json.`
         },
     },
+    {
+        test: /listen EADDRNOTAVAIL\b(?:.*?address not available\s+(\S+):\d+)?/i,
+        hint: (match) =>
+            `NODE_SERVER_HOSTNAME ${match[1] ? `${match[1]} ` : ""}is not an address of this machine; set it to localhost (or this machine's address) in config/config.json.`,
+    },
     {
         test: /SDK location not found|ANDROID_HOME/i,
         hint: () =>

package/dist/errors/registry.js

@@ -330,9 +330,9 @@ export const ERROR_DEFINITIONS = {
         category: "IOS",
         defaultMessage: "iOS code signing is not set up",
         defaultDetails:
-            "A device or release build needs a signing identity and provisioning profile. Automatic signing needs WEBVIEW_CONFIG.ios.developmentTeam plus either an App Store Connect API key in credentials/ios/ (cloud signing) or an Apple account signed in to Xcode; manual signing needs a .p12 and its provisioning profile in credentials/ios/, or an installed ios.provisioningProfile. xcodebuild reported a signing failure, or a release build has no team to sign for.",
+            "A device or release build needs a signing identity and provisioning profile. A release signs with the first of: a .p12 and its profile in credentials/ios/, an installed ios.provisioningProfile, an App Store Connect API key in credentials/ios/, an App Store profile installed on this Mac for the app id (with its certificate in the keychain), or the Apple account signed in to Xcode for WEBVIEW_CONFIG.ios.developmentTeam. xcodebuild reported a signing failure, or a release build has no team to sign for. When an App Store release finds no App Store profile for its bundle id and has nothing else to sign with, the error says so first.",
         suggestedAction:
-            "For cloud signing, put an App Store Connect API key (its AuthKey_*.p8 file, with an ascIssuerId line in signing.properties) in credentials/ios/ and set WEBVIEW_CONFIG.ios.developmentTeam; for local signing, put a distribution .p12 and its .mobileprovision there instead. In CI, set CATALYST_IOS_CREDENTIALS to the output of catalyst credentials:export ios.",
+            "For an App Store release, install the App Store provisioning profile for your bundle id (download it from developer.apple.com, or with Xcode > Settings > Accounts > Download Manual Profiles) or set WEBVIEW_CONFIG.ios.provisioningProfile to an installed profile's name. Otherwise, and for a device build, sign in to Xcode (Xcode > Settings > Accounts) with the Apple account that has your company's team. In CI, put the signing files in credentials/ios/ and set CATALYST_IOS_CREDENTIALS to the output of catalyst credentials:export ios.",
     },
     [ERROR_CODES.IOS_ASC_API_KEY_INVALID]: {
         category: "IOS",

package/dist/errors-index.json

@@ -226,8 +226,8 @@
     "IOS-010": {
         "category": "IOS",
         "message": "iOS code signing is not set up",
-        "details": "A device or release build needs a signing identity and provisioning profile. Automatic signing needs WEBVIEW_CONFIG.ios.developmentTeam plus either an App Store Connect API key in credentials/ios/ (cloud signing) or an Apple account signed in to Xcode; manual signing needs a .p12 and its provisioning profile in credentials/ios/, or an installed ios.provisioningProfile. xcodebuild reported a signing failure, or a release build has no team to sign for.",
-        "suggestedAction": "For cloud signing, put an App Store Connect API key (its AuthKey_*.p8 file, with an ascIssuerId line in signing.properties) in credentials/ios/ and set WEBVIEW_CONFIG.ios.developmentTeam; for local signing, put a distribution .p12 and its .mobileprovision there instead. In CI, set CATALYST_IOS_CREDENTIALS to the output of catalyst credentials:export ios.",
+        "details": "A device or release build needs a signing identity and provisioning profile. A release signs with the first of: a .p12 and its profile in credentials/ios/, an installed ios.provisioningProfile, an App Store Connect API key in credentials/ios/, an App Store profile installed on this Mac for the app id (with its certificate in the keychain), or the Apple account signed in to Xcode for WEBVIEW_CONFIG.ios.developmentTeam. xcodebuild reported a signing failure, or a release build has no team to sign for. When an App Store release finds no App Store profile for its bundle id and has nothing else to sign with, the error says so first.",
+        "suggestedAction": "For an App Store release, install the App Store provisioning profile for your bundle id (download it from developer.apple.com, or with Xcode > Settings > Accounts > Download Manual Profiles) or set WEBVIEW_CONFIG.ios.provisioningProfile to an installed profile's name. Otherwise, and for a device build, sign in to Xcode (Xcode > Settings > Accounts) with the Apple account that has your company's team. In CI, put the signing files in credentials/ios/ and set CATALYST_IOS_CREDENTIALS to the output of catalyst credentials:export ios.",
         "docUrl": "https://github.com/tata1mg/catalyst-core/blob/main/errors/IOS/IOS-010.md"
     },
     "IOS-011": {

package/dist/native/buildAndroid/assets.js

@@ -5,6 +5,7 @@ const path = require("path");
 const {
   checkAppIcon
 } = require("../appIcon.js");
+const splashConfig = require("../splashConfig.js");
 function createAssetsPhase(ctx) {
   const {
     configPath,
@@ -123,8 +124,24 @@ function createAssetsPhase(ctx) {
   async function copyOfflinePage() {
     await copyPublicHtml("offline.html", "offline");
   }
+
+  // The page paints the native splash colour once it takes over, so it gets the
+  // colour the native side resolves (SplashActivity and themes.xml default to white).
   async function copySplashHtml() {
-    await copyPublicHtml("splashscreen.html", "splash", true);
+    let backgroundColor = "#ffffff";
+    try {
+      const {
+        WEBVIEW_CONFIG = {}
+      } = JSON.parse(fs.readFileSync(configPath, "utf8"));
+      backgroundColor = WEBVIEW_CONFIG.splashScreen?.backgroundColor || backgroundColor;
+    } catch {
+      // An unreadable config fails the config phase; the copy itself still goes ahead.
+    }
+    try {
+      splashConfig.copySplashHtml(`${process.cwd()}/public/splashscreen.html`, `${pwd}/androidProject/app/src/main/assets/splash/splashscreen.html`, backgroundColor);
+    } catch (error) {
+      progress.log(`Warning: Error copying splashscreen.html: ${error.message}`, "warning");
+    }
   }
 
   /**

package/dist/native/buildAndroid/build.js

@@ -19,6 +19,12 @@ const {
 const {
   DEFAULT_VERSION_NAME
 } = require("../releaseOutput.js");
+const {
+  saveDebugApk
+} = require("./output.js");
+const {
+  displayPath
+} = require("../../cli/theme.js");
 
 // adb answers in milliseconds when healthy. A wedged adb server accepts the
 // connection and never replies, so without a bound the build sat on
@@ -252,13 +258,39 @@ function createBuildPhase(ctx) {
    * Build the debug APK and install it on `serial` only. Gradle's
    * installDebug installs on every connected device unless ANDROID_SERIAL
    * names one.
+   *
+   * The APK is copied to build-output/android/debug/ (see saveDebugApk),
+   * also when the install fails after Gradle packaged it: installDebug
+   * writes app-debug.apk before it installs, so one Gradle run is enough.
+   *
+   * @returns {Promise<{ apkPath: string | null }>}
    */
   async function buildApp(androidConfig, buildOptimisation, serial, {
     configPath = defaultConfigPath,
     applicationId,
-    version
+    version,
+    appRoot = process.cwd(),
+    name,
+    usesDevServer = false
   } = {}) {
     progress.status("building and installing app");
+    const builtAfter = Date.now();
+    // Best effort: a copy that fails must not fail a build that
+    // installed, or hide the error of one that did not.
+    const keepApk = () => {
+      try {
+        return saveDebugApk({
+          projectPath: `${pwd}/androidProject`,
+          appRoot,
+          name,
+          usesDevServer,
+          builtAfter
+        });
+      } catch (error) {
+        progress.log(`Could not save the APK to build-output: ${error.message}`, "warning");
+        return null;
+      }
+    };
     try {
       // Gradle needs the SDK location in local.properties. Only
       // setupEmulator:android wrote it, so building without a prior
@@ -290,11 +322,19 @@ function createBuildPhase(ctx) {
         }
       });
     } catch (error) {
+      const apkPath = keepApk();
+      if (apkPath) {
+        error.apkPath = apkPath;
+        progress.log(`The APK was built and saved to ${displayPath(apkPath, appRoot)}`, "warning");
+      }
       // Re-wrapping with a new Error dropped `output`, and with it the
       // compiler errors. Keep the original and let the reporter mine it.
       error.stage = "Building and installing the app";
       throw error;
     }
+    return {
+      apkPath: keepApk()
+    };
   }
 
   /** Open the installed app on `serial`. A failure is a warning: the app is installed. */
@@ -341,7 +381,7 @@ function createBuildPhase(ctx) {
   }
 
   /**
-   * Build the signed release bundle. The webview config is generated in
+   * Build the signed release bundle and APK. The webview config is generated in
    * the temp_build_<pkg> copy that Gradle then bundles, from the resolved
    * release config and with -PcatalystBuildType=release, so the release
    * branch of generateWebViewConfig actually runs. Signing and version
@@ -353,7 +393,8 @@ function createBuildPhase(ctx) {
     version,
     applicationId,
     buildOptimisation = false,
-    finalAabPath
+    finalAabPath,
+    finalApkPath
   } = {}) {
     progress.log("Building signed AAB for release...", "info");
     try {
@@ -362,6 +403,7 @@ function createBuildPhase(ctx) {
       if (androidConfig.sdkPath) ensureLocalProperties(`${pwd}/androidProject`, androidConfig.sdkPath);
       const aabConfig = await createAABConfig(androidConfig);
       if (finalAabPath) aabConfig.finalAabPath = finalAabPath;
+      if (finalApkPath) aabConfig.finalApkPath = finalApkPath;
       aabConfig.gradle = {
         configPath,
         buildOptimisation,

package/dist/native/buildAndroid/index.js

@@ -40,12 +40,16 @@ const {
   reachDevServer
 } = require("./devices.js");
 const {
+  RELEASE_APK_NOTE,
+  artifactName,
+  debugApkNotes,
   releaseOutputDir,
   releaseArtifactPaths
 } = require("./output.js");
 const {
   DEFAULT_VERSION_NAME,
-  assertReleaseFolderFree
+  assertReleaseFolderFree,
+  ensureBuildOutputIgnore
 } = require("../releaseOutput.js");
 const {
   applyJavaHome,
@@ -66,6 +70,10 @@ const {
 const catalystCorePath = path.dirname(require.resolve("catalyst-core/package.json"));
 const pwd = path.join(catalystCorePath, "dist/native");
 const ANDROID_PACKAGE = "io.yourname.androidproject";
+
+// The summary rows are "<key padded to 11> <value>"; a note under a value
+// starts in the value column.
+const SUMMARY_NOTE_INDENT = " ".repeat(11);
 const steps = {
   server: "Start dev server",
   config: "Initialize configuration",
@@ -190,6 +198,7 @@ function createAndroidBuild(config, {
     let resolved = null;
     let signing = null;
     let artifactPath = null;
+    let apkPath = null;
     let certificatePath = null;
     try {
       const log = (message, type) => progress.log(message, type);
@@ -223,7 +232,7 @@ function createAndroidBuild(config, {
         appRoot,
         androidConfig,
         version
-      }), [".aab"]);
+      }), [".aab", ".apk"]);
       progress.complete("config");
 
       // One-command dev: a debug build starts the dev server when
@@ -362,32 +371,45 @@ function createAndroidBuild(config, {
           androidConfig,
           version
         });
-        const names = releaseArtifactPaths(outputDir, androidConfig.newProjectName || androidConfig.appName || "app");
+        const names = releaseArtifactPaths(outputDir, artifactName(androidConfig));
+        ensureBuildOutputIgnore(outputDir, appRoot);
         const aab = await buildSignedAAB(androidConfig, {
           ...gradleOptions,
           signing,
           buildOptimisation,
-          finalAabPath: names.aab
+          finalAabPath: names.aab,
+          finalApkPath: names.apk
         });
         artifactPath = aab?.finalAabPath || names.aab;
+        apkPath = aab?.finalApkPath || names.apk;
         // The upload certificate beside the bundle (#508): Play asks
         // for it when an upload key is registered or reset.
         certificatePath = exportUploadCertificate(signing, names.certificate);
         progress.complete("aab");
       } else {
         progress.start("build");
-        await buildApp(androidConfig, buildOptimisation, targetDevice.id, gradleOptions);
-        // Debug builds load http://localhost:<port>; on the device that
-        // is the device itself. Forward every port the app uses to this
-        // machine, after the install and before the launch, every run.
-        const packageName = `${applicationId}.debug`;
-        const ports = devServerPorts(resolved.config, {
-          hmrPort: await readHmrPort({
-            cwd: appRoot
-          })
+        const debug = await buildApp(androidConfig, buildOptimisation, targetDevice.id, {
+          ...gradleOptions,
+          appRoot,
+          name: artifactName(androidConfig),
+          usesDevServer: resolved.usesDevServer
         });
-        reachDevServer(adbRunner(ADB_PATH), targetDevice.id, packageName, ports);
-        progress.log(`Forwarded ports ${ports.join(", ")} to this machine (adb reverse)`, "info");
+        apkPath = debug?.apkPath || null;
+        const packageName = `${applicationId}.debug`;
+        // A dev server build loads http://localhost:<port>; on the
+        // device that is the device itself. Forward every port the app
+        // uses to this machine, after the install and before the
+        // launch, every run. A build that loads a real host from
+        // LOCAL_IP reaches it directly and needs none of this.
+        if (resolved.usesDevServer) {
+          const ports = devServerPorts(resolved.config, {
+            hmrPort: await readHmrPort({
+              cwd: appRoot
+            })
+          });
+          reachDevServer(adbRunner(ADB_PATH), targetDevice.id, packageName, ports);
+          progress.log(`Forwarded ports ${ports.join(", ")} to this machine (adb reverse)`, "info");
+        }
         launchApp(ADB_PATH, targetDevice.id, packageName);
         progress.complete("build");
       }
@@ -401,7 +423,18 @@ function createAndroidBuild(config, {
       }];
       if (artifactPath) {
         summaryItems.push({
-          text: `artifact   ${displayPath(artifactPath, appRoot)}`,
+          text: `aab        ${displayPath(artifactPath, appRoot)}`,
+          color: "gray"
+        });
+      }
+      if (apkPath) {
+        summaryItems.push({
+          text: `apk        ${displayPath(apkPath, appRoot)}`,
+          color: "gray"
+        });
+        const notes = release ? [RELEASE_APK_NOTE] : debugApkNotes(resolved.usesDevServer);
+        for (const note of notes) summaryItems.push({
+          text: `${SUMMARY_NOTE_INDENT}${note}`,
           color: "gray"
         });
       }
@@ -421,9 +454,9 @@ function createAndroidBuild(config, {
       });
       progress.printTreeContent("Build", summaryItems);
       if (release) {
-        progress.summary("Built the signed AAB", "Upload it to Google Play");
+        progress.summary("Built the signed AAB and APK", "Upload the AAB to Google Play");
       } else {
-        progress.summary(`Running on ${deviceName}`, "Edit your app; the dev server reloads it");
+        progress.summary(`Running on ${deviceName}`, resolved.usesDevServer ? "Edit your app; the dev server reloads it" : `The app loads ${resolved.startUrl || wvConfig.LOCAL_IP}`);
       }
     } catch (error) {
       // Mark the step, then show what actually broke. The old handler

package/dist/native/buildAndroid/output.js

@@ -3,11 +3,58 @@
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
+exports.RELEASE_GRADLE_TASKS = exports.RELEASE_APK_NOTE = void 0;
+exports.apkBeside = apkBeside;
+exports.artifactName = artifactName;
+exports.builtReleaseApk = builtReleaseApk;
+exports.debugApkNotes = debugApkNotes;
+exports.debugApkPaths = debugApkPaths;
+exports.gradleOutputs = gradleOutputs;
 exports.releaseArtifactPaths = releaseArtifactPaths;
 exports.releaseOutputDir = releaseOutputDir;
+exports.saveDebugApk = saveDebugApk;
+var _fs = _interopRequireDefault(require("fs"));
 var _path = _interopRequireDefault(require("path"));
 var _releaseOutput = require("../releaseOutput.js");
 function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+/**
+ * The Gradle tasks a release runs, in one Gradle run: the bundle for Play
+ * and a universal APK for test installs. The release buildType's
+ * signingConfig signs both, and the app sets no ABI splits, so the APK is
+ * a single app-release.apk.
+ */
+const RELEASE_GRADLE_TASKS = exports.RELEASE_GRADLE_TASKS = ["clean", "bundleRelease", "assembleRelease"];
+
+/** The note printed under a release APK. */
+const RELEASE_APK_NOTE = exports.RELEASE_APK_NOTE = "The APK is for test installs; uninstall a Play-installed copy first.";
+
+/**
+ * A debug APK copied after a failed run must come from this run: a step
+ * that fails before Gradle's clean leaves the previous run's APK in place.
+ * The slack covers file systems that store mtimes in whole seconds.
+ */
+const MTIME_SLACK_MS = 2000;
+
+/** The name the AAB and APK files are given, before artifactBaseName makes it file-name safe. */
+function artifactName(androidConfig = {}) {
+  return androidConfig.newProjectName || androidConfig.appName || "app";
+}
+
+/**
+ * Where Gradle writes its outputs in an Android project (androidProject or
+ * the temp_build copy a release builds in).
+ *
+ * @param {string} projectPath
+ */
+function gradleOutputs(projectPath) {
+  const outputs = _path.default.join(projectPath, "app", "build", "outputs");
+  return {
+    debugApk: _path.default.join(outputs, "apk", "debug", "app-debug.apk"),
+    releaseAab: _path.default.join(outputs, "bundle", "release", "app-release.aab"),
+    releaseApk: _path.default.join(outputs, "apk", "release", "app-release.apk")
+  };
+}
+
 /**
  * Where a release puts its files: build-output/android/<version>-<build>/
  * in the app, or <android.outputPath>/<version>-<build>/ when the config
@@ -24,20 +71,135 @@ function releaseOutputDir({
   androidConfig = {},
   version
 }) {
-  const root = androidConfig.outputPath ? _path.default.resolve(appRoot, androidConfig.outputPath) : _path.default.join(appRoot, "build-output", "android");
+  const root = androidConfig.outputPath ? _path.default.resolve(appRoot, androidConfig.outputPath) : _path.default.join(appRoot, _releaseOutput.BUILD_OUTPUT_DIR, "android");
   return _path.default.join(root, (0, _releaseOutput.releaseFolderName)(version));
 }
 
 /**
- * The release files in that folder: the bundle for Play and the upload
- * certificate (PEM) that identifies the key that signed it.
+ * The release files in that folder: the bundle for Play, the APK for test
+ * installs, and the upload certificate (PEM) that identifies the key that
+ * signed both.
  *
  * @param {string} dir - releaseOutputDir()
  * @param {string} name - the app's name; made file-name safe here
  */
 function releaseArtifactPaths(dir, name) {
+  const base = (0, _releaseOutput.artifactBaseName)(name);
   return {
-    aab: _path.default.join(dir, `${(0, _releaseOutput.artifactBaseName)(name)}.aab`),
+    aab: _path.default.join(dir, `${base}.aab`),
+    apk: _path.default.join(dir, `${base}.apk`),
     certificate: _path.default.join(dir, "upload_certificate.pem")
   };
+}
+
+/** The APK beside an AAB: the same name with .apk. */
+function apkBeside(aabPath) {
+  return `${aabPath.replace(/\.aab$/i, "")}.apk`;
+}
+
+/**
+ * The signed release APK Gradle built, or a clear error. Without a signing
+ * config Gradle names it app-release-unsigned.apk, which no phone installs.
+ *
+ * @param {string} projectPath
+ * @returns {string}
+ */
+function builtReleaseApk(projectPath) {
+  const {
+    releaseApk
+  } = gradleOutputs(projectPath);
+  if (_fs.default.existsSync(releaseApk)) return releaseApk;
+  const unsigned = _path.default.join(_path.default.dirname(releaseApk), "app-release-unsigned.apk");
+  if (_fs.default.existsSync(unsigned)) {
+    throw new Error(`The release APK was built without the upload key (${unsigned}), so it cannot be installed`);
+  }
+  throw new Error(`Signed APK file was not generated at ${releaseApk}`);
+}
+
+/**
+ * Where a debug build keeps its APK: build-output/android/debug/, under a
+ * fixed name that each run overwrites. A build that loads this computer's
+ * dev server gets its own name, since it only works here.
+ *
+ * @param {object} options
+ * @param {string} [options.appRoot]
+ * @param {string} [options.name] - the app's name; made file-name safe here
+ * @param {boolean} [options.usesDevServer] - resolveNativeConfig().usesDevServer
+ * @returns {{ dir: string, apk: string, stale: string }} `stale` is the other variant's file
+ */
+function debugApkPaths({
+  appRoot = process.cwd(),
+  name,
+  usesDevServer = false
+} = {}) {
+  const dir = _path.default.join(appRoot, _releaseOutput.BUILD_OUTPUT_DIR, "android", "debug");
+  const base = (0, _releaseOutput.artifactBaseName)(name);
+  const realHost = _path.default.join(dir, `${base}-debug.apk`);
+  const devServer = _path.default.join(dir, `${base}-debug-devserver.apk`);
+  return usesDevServer ? {
+    dir,
+    apk: devServer,
+    stale: realHost
+  } : {
+    dir,
+    apk: realHost,
+    stale: devServer
+  };
+}
+
+/**
+ * Copy the debug APK Gradle built into build-output/android/debug/ and
+ * remove the other variant's file there, so only the current one exists.
+ * Returns null, and changes nothing, when there is no APK from this run.
+ *
+ * @param {object} options
+ * @param {string} options.projectPath - the androidProject Gradle built in
+ * @param {string} [options.appRoot]
+ * @param {string} [options.name]
+ * @param {boolean} [options.usesDevServer]
+ * @param {number} [options.builtAfter] - ms timestamp; an older APK is from an earlier run
+ * @returns {string | null} the saved APK's path
+ */
+function saveDebugApk({
+  projectPath,
+  appRoot = process.cwd(),
+  name,
+  usesDevServer = false,
+  builtAfter = 0
+}) {
+  const source = gradleOutputs(projectPath).debugApk;
+  let stat;
+  try {
+    stat = _fs.default.statSync(source);
+  } catch (error) {
+    return null;
+  }
+  if (builtAfter && stat.mtimeMs < builtAfter - MTIME_SLACK_MS) return null;
+  const {
+    dir,
+    apk,
+    stale
+  } = debugApkPaths({
+    appRoot,
+    name,
+    usesDevServer
+  });
+  (0, _releaseOutput.ensureBuildOutputIgnore)(dir, appRoot);
+  _fs.default.mkdirSync(dir, {
+    recursive: true
+  });
+  _fs.default.copyFileSync(source, apk);
+  _fs.default.rmSync(stale, {
+    force: true
+  });
+  return apk;
+}
+
+/** The lines printed under a debug APK in the build summary. */
+function debugApkNotes(usesDevServer = false) {
+  const notes = ["Test build: debuggable, for testing only."];
+  if (usesDevServer) {
+    notes.push("Only works with this computer's dev server. To share, set WEBVIEW_CONFIG.LOCAL_IP to your site, or run android:release.");
+  }
+  return notes;
 }

package/dist/native/buildAppAndroid.js

@@ -15,6 +15,10 @@ const {
   buildFailure
 } = require("../cli/diagnostic.js");
 const {
+  askReleaseConfig
+} = require("./setupServer.js");
+const {
+  isInteractive,
   parseNativeArgs
 } = require("./utils.js");
 const {
@@ -34,12 +38,33 @@ async function main() {
     }));
     process.exit(1);
   }
+  // The build reads config.json from disk when it starts (initializeConfig),
+  // so answers saved below reach it; the config passed here is not read again.
   const {
-    buildAndroidApp
+    buildAndroidApp,
+    progress
   } = createAndroidBuild({
     WEBVIEW_CONFIG,
     BUILD_OUTPUT_PATH
   }, flags);
+
+  // A store build in a terminal asks once for a missing app id or website
+  // and saves the answers. Its errors are left for the build, which
+  // resolves the config again and reports them the usual way.
+  if (isInteractive()) {
+    const log = (message, type) => progress.log(message, type);
+    try {
+      await askReleaseConfig("android", {
+        release: flags.release,
+        url: flags.url,
+        log
+      });
+    } catch (error) {
+      if (!/^NATIVE-\d{3}$/.test(error?.code)) {
+        log(`Could not read or update config/config.json: ${error.message}`, "warning");
+      }
+    }
+  }
   try {
     await buildAndroidApp();
   } catch (error) {