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

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.",
         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.",
+            "Sign in to Xcode (Xcode > Settings > Accounts) with the Apple account that has your team, or install that team's App Store profile for your appId. 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.",
+        "suggestedAction": "Sign in to Xcode (Xcode > Settings > Accounts) with the Apple account that has your team, or install that team's App Store profile for your appId. 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) {