flet-box 0.0.0-stage → 1.0.2

package/bin/commands/buildAndroid.js

@@ -0,0 +1,200 @@
+/**
+ * @file bin/commands/buildAndroid.js
+ * @description Synchronizes a FletBox project with Capacitor and builds a debug
+ *              APK, an unsigned release APK, or an unsigned release AAB.
+ */
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { c, banner } from "../utils/colors.js";
+import {
+  assertCapacitorProject,
+  commandExists,
+  ensureNpmDependencies,
+  run,
+} from "../utils/capacitor.js";
+
+const requiredPackages = [
+  "@capacitor/android",
+  "@capacitor/cli",
+  "@capacitor/core",
+  "flet-box",
+  "sharp",
+];
+
+const requiredScripts = ["android:init", "android:sync"];
+
+/** Well-known Android SDK locations per platform, most specific first. */
+const androidSdkCandidates = () => {
+  const candidates = [
+    process.env.ANDROID_SDK_ROOT,
+    process.env.ANDROID_HOME,
+  ].filter(Boolean);
+
+  if (process.platform === "darwin") {
+    candidates.push(path.join(os.homedir(), "Library", "Android", "sdk"));
+  } else if (process.platform === "win32") {
+    candidates.push(
+      path.join(process.env.LOCALAPPDATA || "", "Android", "Sdk"),
+    );
+  } else {
+    candidates.push(path.join(os.homedir(), "Android", "Sdk"));
+  }
+
+  return candidates;
+};
+
+export const prepareAndroidEnvironment = () => {
+  const sdkPath = androidSdkCandidates().find(
+    (candidate) => candidate && fs.existsSync(candidate),
+  );
+  if (!sdkPath) {
+    throw new Error(
+      "Android SDK was not found. Install Android Studio and its Android SDK, or set ANDROID_HOME/ANDROID_SDK_ROOT.",
+    );
+  }
+
+  if (!commandExists("java", ["-version"])) {
+    throw new Error(
+      "Java was not found. Install a JDK supported by your Android Gradle project and ensure `java` is on PATH.",
+    );
+  }
+
+  return {
+    ...process.env,
+    ANDROID_HOME: sdkPath,
+    ANDROID_SDK_ROOT: sdkPath,
+  };
+};
+
+/**
+ * Entry point for `flet-box build android`.
+ *
+ * @param {string[]} [rawArgs=[]] - Raw CLI flags: `--debug` (default) or
+ *   `--release` (unsigned release APK/AAB, ready for your own signing).
+ * @returns {void}
+ */
+export const buildAndroid = (rawArgs = []) => {
+  const supportedFlags = ["--debug", "--release", "--aab"];
+  const unknownFlags = rawArgs.filter((arg) => !supportedFlags.includes(arg));
+  if (unknownFlags.length > 0) {
+    throw new Error(
+      `Unknown option for \`build android\`: ${unknownFlags.join(", ")}. Supported options: ${supportedFlags.join(", ")}.`,
+    );
+  }
+
+  const release = rawArgs.includes("--release");
+  const aab = rawArgs.includes("--aab");
+  if (aab && !release) {
+    throw new Error("`--aab` requires `--release`. Example: `flet-box build android --release --aab`.");
+  }
+
+  const mode = aab ? "release AAB" : release ? "unsigned release APK" : "debug APK";
+  const gradleTask = aab ? "bundleRelease" : release ? "assembleRelease" : "assembleDebug";
+
+  const { projectRoot } = assertCapacitorProject(requiredScripts);
+
+  console.log(banner("🤖 Flet-Box Android", mode));
+  ensureNpmDependencies(projectRoot, requiredPackages);
+  const androidEnv = prepareAndroidEnvironment();
+
+  const androidDir = path.join(projectRoot, "android");
+  if (!fs.existsSync(androidDir)) {
+    console.log(c("blue", "\n📱 Initializing the Android platform..."));
+    run(
+      "npm",
+      ["run", "android:init"],
+      projectRoot,
+      "Android initialization",
+      androidEnv,
+    );
+  }
+
+  console.log(c("blue", "\n🔄 Building and synchronizing the app..."));
+  run(
+    "npm",
+    ["run", "android:sync"],
+    projectRoot,
+    "Android synchronization",
+    androidEnv,
+  );
+
+  const gradleWrapper =
+    process.platform === "win32" ? "gradlew.bat" : "gradlew";
+  const gradlePath = path.join(androidDir, gradleWrapper);
+  if (!fs.existsSync(gradlePath)) {
+    throw new Error(
+      `Gradle wrapper not found at ${gradlePath}. Check that Capacitor Android initialization completed.`,
+    );
+  }
+
+  console.log(c("blue", `\n🏗️ Compiling the ${mode}...`));
+  run(
+    process.platform === "win32" ? gradleWrapper : `./${gradleWrapper}`,
+    [gradleTask],
+    androidDir,
+    "Gradle Android build",
+    androidEnv,
+  );
+
+  const outputsDir = path.join(androidDir, "app", "build", "outputs");
+  const artifact = findArtifact(outputsDir, aab, release);
+  if (!artifact) {
+    throw new Error(
+      `Gradle completed, but the ${mode} was not found under ${outputsDir}.`,
+    );
+  }
+
+  if (!release) {
+    console.log(
+      c(
+        "green",
+        `\n✅ Android APK created successfully.\n📍 APK path: adb install "${path.resolve(artifact)}"`,
+      ),
+    );
+    return;
+  }
+
+  const signHint = aab
+    ? `Sign it for Play with your upload key: jarsigner -keystore <tu.keystore> <alias> "${path.resolve(artifact)}"\n   Then upload it to the Play Console (Play App Signing applies the final key).`
+    : `Sign it yourself (already aligned by Gradle, skip zipalign):\n   apksigner sign --ks <tu.keystore> --ks-key-alias <alias> --out app-firmado.apk "${path.resolve(artifact)}"\n   Then verify: apksigner verify --verbose --print-certs app-firmado.apk`;
+
+  console.log(
+    c(
+      "green",
+      `\n✅ Android ${mode} created successfully (unsigned by design).\n📍 Path: ${path.resolve(artifact)}\nℹ️ ${signHint}`,
+    ),
+  );
+};
+
+/**
+ * Locates the Gradle output artifact for the selected build mode.
+ *
+ * Debug APKs land in `apk/debug/app-debug.apk`. Unsigned release APKs land in
+ * `apk/release/` and may be named `app-release.apk` or `app-release-unsigned.apk`
+ * depending on the Android Gradle Plugin version. AABs land in
+ * `bundle/release/app-release.aab`.
+ *
+ * @param {string} outputsDir - The Gradle `app/build/outputs` directory.
+ * @param {boolean} aab - Whether the target is a bundle instead of an APK.
+ * @param {boolean} release - Whether the build is a release build.
+ * @returns {string | null} Absolute path to the artifact, or null.
+ */
+const findArtifact = (outputsDir, aab, release) => {
+  const candidates = [];
+  if (aab) {
+    candidates.push(path.join(outputsDir, "bundle", "release", "app-release.aab"));
+  } else if (release) {
+    const releaseDir = path.join(outputsDir, "apk", "release");
+    if (fs.existsSync(releaseDir)) {
+      const apks = fs.readdirSync(releaseDir).filter((file) => file.endsWith(".apk"));
+      candidates.push(path.join(releaseDir, "app-release.apk"));
+      candidates.push(path.join(releaseDir, "app-release-unsigned.apk"));
+      for (const apk of apks) candidates.push(path.join(releaseDir, apk));
+    }
+  } else {
+    candidates.push(path.join(outputsDir, "apk", "debug", "app-debug.apk"));
+  }
+  return candidates.find((candidate) => fs.existsSync(candidate)) || null;
+};

package/bin/commands/buildIOS.js

@@ -0,0 +1,237 @@
+/**
+ * @file bin/commands/buildIOS.js
+ * @description Synchronizes a FletBox project with Capacitor and builds a native
+ * iOS app.
+ *
+ * Two destinations are supported:
+ * - default     → `App.app` for the iOS Simulator, no signing required.
+ * - `--archive` → `App.xcarchive` for real devices, unsigned. The IPA is
+ *                 exported from that archive in Xcode with an Apple team.
+ */
+
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { c, banner } from "../utils/colors.js";
+import {
+  assertCapacitorProject,
+  commandExists,
+  ensureNpmDependencies,
+  run,
+} from "../utils/capacitor.js";
+
+const requiredPackages = [
+  "@capacitor/cli",
+  "@capacitor/core",
+  "@capacitor/ios",
+  "flet-box",
+  "sharp",
+];
+
+const requiredScripts = ["ios:init", "ios:sync"];
+
+/** Path of the active Xcode developer directory, empty when unset. */
+const developerDir = () => {
+  const result = spawnSync("xcode-select", ["-p"], {
+    stdio: ["ignore", "pipe", "ignore"],
+  });
+  return result.stdout ? result.stdout.toString().trim() : "";
+};
+
+/**
+ * Validates the Apple toolchain needed to compile an iOS app.
+ *
+ * The Xcode Command Line Tools cannot do this job: they install a `xcodebuild`
+ * stub and no simulator runtime, so the failure would only surface later as an
+ * opaque Xcode error. Detecting that selection up front lets the command point
+ * at the actual fix.
+ *
+ * @param {{ simulator: boolean }} options - `simulator` requests a simulator
+ *   destination, which additionally needs `simctl`.
+ * @returns {void}
+ * @throws {Error} With an actionable message when a requirement is missing.
+ */
+export const requireAppleToolchain = ({ simulator }) => {
+  if (process.platform !== "darwin") {
+    throw new Error(
+      "Building iOS requires macOS with Xcode. Run `flet-box build ios` on a Mac.",
+    );
+  }
+
+  const dir = developerDir();
+  if (!dir) {
+    throw new Error(
+      "No active Xcode developer directory. Install Xcode from the App Store, then run `xcode-select --install`.",
+    );
+  }
+  if (dir.includes("CommandLineTools")) {
+    throw new Error(
+      `The active developer directory is the Command Line Tools (${dir}), which cannot build iOS apps. Install the full Xcode app, then run: sudo xcode-select -s /Applications/Xcode.app/Contents/Developer`,
+    );
+  }
+  if (!commandExists("xcodebuild", ["-version"])) {
+    throw new Error(
+      "xcodebuild is not available. Open Xcode once so it finishes installing its components.",
+    );
+  }
+  if (!commandExists("pod", ["--version"])) {
+    throw new Error(
+      "CocoaPods was not found. Capacitor links its native layer with CocoaPods, so install it with `sudo gem install cocoapods` (or `brew install cocoapods`) and run `pod setup` once.",
+    );
+  }
+  if (simulator && !commandExists("xcrun", ["--find", "simctl"])) {
+    throw new Error(
+      "Simulator tools (simctl) were not found. Install an iOS simulator runtime from Xcode → Settings → Platforms, or build for a device with `flet-box build ios --archive`.",
+    );
+  }
+};
+
+/**
+ * Runs `xcodebuild` on the generated Capacitor project.
+ *
+ * @param {object} options - Build options.
+ * @param {string} options.iosDir - Absolute path of the `ios` directory.
+ * @param {string} options.sdk - Xcode SDK to build against.
+ * @param {string} options.destination - `xcodebuild -destination` value.
+ * @param {string} options.configuration - `Debug` or `Release`.
+ * @param {"build" | "archive"} options.action - Xcode action.
+ * @param {string} [options.archivePath] - Required when the action is `archive`.
+ * @returns {void}
+ */
+const xcodebuildRun = ({
+  iosDir,
+  sdk,
+  destination,
+  configuration,
+  action,
+  archivePath,
+}) => {
+  const args = [
+    "-project",
+    "App/App.xcodeproj",
+    "-scheme",
+    "App",
+    "-configuration",
+    configuration,
+    "-sdk",
+    sdk,
+    "-destination",
+    destination,
+    "-derivedDataPath",
+    "build",
+    // Generated projects ship without a signing team, so signing is disabled.
+    // Without this, the build fails while looking for an identity instead of
+    // compiling anything.
+    "CODE_SIGNING_ALLOWED=NO",
+  ];
+
+  if (action === "archive") {
+    args.push("-archivePath", archivePath, "archive");
+  } else {
+    args.push("build");
+  }
+
+  run("xcodebuild", args, iosDir, `Xcode ${action} (${sdk})`);
+};
+
+/**
+ * Entry point for `flet-box build ios`.
+ *
+ * @param {string[]} [rawArgs=[]] - Raw CLI flags: `--simulator` (default) or `--archive`.
+ * @returns {void}
+ */
+export const buildIOS = (rawArgs = []) => {
+  const supportedFlags = ["--simulator", "--archive"];
+  const unknownFlags = rawArgs.filter((arg) => !supportedFlags.includes(arg));
+  if (unknownFlags.length > 0) {
+    throw new Error(
+      `Unknown option for \`build ios\`: ${unknownFlags.join(", ")}. Supported options: ${supportedFlags.join(", ")}.`,
+    );
+  }
+  const archive = rawArgs.includes("--archive");
+
+  const { projectRoot } = assertCapacitorProject(requiredScripts);
+
+  console.log(
+    banner(
+      "🍎 Flet-Box iOS",
+      archive ? "device archive" : "iOS Simulator app",
+    ),
+  );
+  requireAppleToolchain({ simulator: !archive });
+  ensureNpmDependencies(projectRoot, requiredPackages);
+
+  const iosDir = path.join(projectRoot, "ios");
+  if (!fs.existsSync(iosDir)) {
+    console.log(c("blue", "\n📱 Initializing the iOS platform..."));
+    run("npm", ["run", "ios:init"], projectRoot, "iOS initialization");
+  }
+
+  console.log(c("blue", "\n🔄 Building and synchronizing the app..."));
+  run("npm", ["run", "ios:sync"], projectRoot, "iOS synchronization");
+
+  const xcodeProject = path.join(iosDir, "App", "App.xcodeproj");
+  if (!fs.existsSync(xcodeProject)) {
+    throw new Error(
+      `Xcode project not found at ${xcodeProject}. Check that Capacitor iOS initialization completed.`,
+    );
+  }
+
+  const derivedDataPath = path.join(iosDir, "build");
+
+  if (archive) {
+    const archivePath = path.join(derivedDataPath, "App.xcarchive");
+    console.log(c("blue", "\n🏗️ Archiving for real devices..."));
+    xcodebuildRun({
+      iosDir,
+      sdk: "iphoneos",
+      destination: "generic/platform=iOS",
+      configuration: "Release",
+      action: "archive",
+      archivePath,
+    });
+
+    if (!fs.existsSync(archivePath)) {
+      throw new Error(
+        `Xcode completed, but no archive was found at ${archivePath}.`,
+      );
+    }
+
+    console.log(
+      c(
+        "green",
+        `\n✅ iOS archive created successfully.\n📍 Archive path: ${path.resolve(archivePath)}\nℹ️ The archive is unsigned. Export an IPA from it in Xcode (Product → Archive) with your Apple signing team, or with \`xcodebuild -exportArchive\` plus an ExportOptions.plist.`,
+      ),
+    );
+    return;
+  }
+
+  console.log(c("blue", "\n🏗️ Compiling for the iOS Simulator..."));
+  xcodebuildRun({
+    iosDir,
+    sdk: "iphonesimulator",
+    destination: "generic/platform=iOS Simulator",
+    configuration: "Debug",
+    action: "build",
+  });
+
+  const appPath = path.join(
+    derivedDataPath,
+    "Build",
+    "Products",
+    "Debug-iphonesimulator",
+    "App.app",
+  );
+  if (!fs.existsSync(appPath)) {
+    throw new Error(
+      `Xcode completed, but the simulator app was not found at ${appPath}.`,
+    );
+  }
+
+  console.log(
+    c(
+      "green",
+      `\n✅ iOS Simulator app created successfully.\n📍 App path: ${path.resolve(appPath)}\nℹ️ Install it on a running simulator with: xcrun simctl install booted ${path.resolve(appPath)}\nℹ️ For a signed IPA, run \`flet-box build ios --archive\`.`,
+    ),
+  );
+};