flet-box 0.0.0-stage → 1.0.2

package/bin/commands/killServer.js

@@ -0,0 +1,107 @@
+// bin/commands/killServer.js
+import { execSync } from "child_process";
+import { c, banner, gradient, rainbow } from "../utils/colors.js";
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+const isAlive = (pid) => {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+const waitGone = async (pid, timeout) => {
+  const start = Date.now();
+  while (isAlive(pid) && Date.now() - start < timeout) {
+    await sleep(100);
+  }
+  return !isAlive(pid);
+};
+
+const hasLsof = () => {
+  try {
+    execSync("command -v lsof", { stdio: "pipe" });
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+const listenersOnPort = (port) => {
+  try {
+    const out = execSync(`lsof -ti tcp:${port} -sTCP:LISTEN`, {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    });
+    return out.split("\n").map((s) => s.trim()).filter(Boolean);
+  } catch {
+    return [];
+  }
+};
+
+export const killServer = async (portArg, { dryRun = false } = {}) => {
+  const PORT = Number(portArg) || 8000;
+
+  console.log(banner("🗡️  Kill Server", `port ${PORT}`));
+
+  if (!hasLsof()) {
+    console.error(c("red", "❌ lsof not found (needed to find processes)"));
+    console.log(c("gray", `    Try manually: kill $(lsof -ti tcp:${PORT})`));
+    process.exit(1);
+  }
+
+  const pids = listenersOnPort(PORT);
+
+  if (pids.length === 0) {
+    console.log(gradient(` ✅ No servers listening on port ${PORT}`, "#34d399", "#22d3ee"));
+    return;
+  }
+
+  console.log(
+    gradient(`Found ${pids.length} process(es) on port ${PORT}:`, "#fbbf24", "#fb923c"),
+  );
+  for (const pid of pids) {
+    let name = "?";
+    try {
+      name = execSync(`ps -p ${pid} -o command=`, { encoding: "utf8" }).trim();
+    } catch {
+      // ignore
+    }
+    console.log(c("gray", `  · ${c("bold", rainbow(pid))}  ${c("dim", name)}`));
+  }
+
+  if (dryRun) {
+    console.log(
+      "\n" + gradient("--dry-run: nothing killed. Run without --dry-run to kill them.", "#22d3ee", "#38bdf8"),
+    );
+    return;
+  }
+
+  for (const pid of pids) {
+    if (!isAlive(pid)) continue;
+    try {
+      execSync(`kill -TERM ${pid}`, { stdio: "ignore" });
+      const gone = await waitGone(pid, 1500);
+      if (!gone) {
+        execSync(`kill -KILL ${pid}`, { stdio: "ignore" });
+        await waitGone(pid, 1000);
+      }
+      console.log(gradient(` 💀 Killed: ${pid}`, "#f43f5e", "#fb923c"));
+    } catch (e) {
+      console.error(c("red", `❌ No se pudo matar ${pid}: ${e && e.message}`));
+    }
+  }
+
+  await sleep(300);
+  const restantes = listenersOnPort(PORT);
+  if (restantes.length > 0) {
+    console.log(c("yellow", `⚠️ Processes still on port ${PORT}: ${restantes.join(", ")}`));
+  } else {
+    console.log(gradient(` ✅ Port ${PORT} released.`, "#34d399", "#22d3ee"));
+  }
+};
+
+export default killServer;

package/bin/commands/package.js

@@ -0,0 +1,131 @@
+// bin/commands/package.js
+import readline from "readline";
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+import { execCmd } from "../utils/helpers.js";
+import { c, gradient, rainbow, section, divider, panel } from "../utils/colors.js";
+import { execSpin } from "../utils/spinner.js";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+let FRAMEWORK_VERSION = "v1.0.0";
+try {
+  FRAMEWORK_VERSION =
+    "v" +
+    JSON.parse(
+      fs.readFileSync(path.join(__dirname, "../../package.json"), "utf8"),
+    ).version;
+} catch {}
+
+export const packageManager = async () => {
+  const PACKAGE = "flet-box";
+  const PKG_PATH = path.join(__dirname, "../..");
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+  const question = (q) => new Promise((resolve) => rl.question(q, resolve));
+
+  process.on("SIGINT", () => {
+    console.log(`\n${rainbow("👋 Bye!")}\n`);
+    rl.close();
+    process.exit(0);
+  });
+
+  const run = (label, icon, color = "#6366f1") =>
+    console.log(`\n${divider(`${icon}  ${label}`, color)}`);
+
+  const opt = (n, name, desc, from = "#34d399", to = "#22d3ee") =>
+    `  ${gradient(`${n}.`, from, to)} ${c("bold", name.padEnd(10))}${c("dim", "·")} ${c("gray", desc)}`;
+
+  while (true) {
+    console.clear();
+    console.log(`\n${panel("📦 FletBox Package Manager", FRAMEWORK_VERSION, { minW: 64 })}`);
+    console.log(
+      `
+${section("🔧", "LOCAL DEVELOPMENT")}
+${opt(1, "link", "Create global link")}
+${opt(2, "use", "Use link in current project")}
+${opt(3, "unlink", "Remove the link")}
+${opt(4, "list", "Show link status")}
+
+${section("📦", "NPM REGISTRY")}
+${opt(5, "publish", "Publish to npm", "#38bdf8", "#6366f1")}
+${opt(6, "install", "npm install flet-box", "#38bdf8", "#6366f1")}
+${opt(7, "uninstall", "npm uninstall flet-box", "#38bdf8", "#6366f1")}
+
+${section("👤", "UTILS")}
+${opt(8, "whoami", "Show npm user", "#d946ef", "#8b5cf6")}
+${opt(9, "login", "Login to npm", "#d946ef", "#8b5cf6")}
+${opt(0, "exit", "Leave the manager", "#f43f5e", "#fb923c")}
+
+${divider("", "#3730a3")}
+${c("gray", "  Press Ctrl+C to exit at any time")} ${c("dim", "· " + FRAMEWORK_VERSION)}
+`,
+    );
+
+    const choice = await question(
+      `\n  ${gradient("❯", "#22d3ee", "#a855f7")} ${c("brightCyan", "Select option")}: `,
+    );
+
+    switch (choice) {
+      case "1":
+        execSpin("Creating global link...", `cd "${PKG_PATH}" && npm link`);
+        break;
+
+      case "2":
+        execSpin("Linking flet-box in current project...", `npm link ${PACKAGE}`);
+        break;
+
+      case "3":
+        execSpin("Unlinking flet-box...", `npm unlink ${PACKAGE}`);
+        break;
+
+      case "4":
+        run("STATUS", "📋");
+        execCmd(
+          `npm list -g --depth=0 2>/dev/null | grep ${PACKAGE} || echo "Not linked globally"`,
+        );
+        const localPath = path.join(process.cwd(), "node_modules", PACKAGE);
+        if (fs.existsSync(localPath)) {
+          console.log(` ${gradient("✅ Installed locally", "#34d399", "#22d3ee")}`);
+        } else {
+          console.log(` ${c("gray", "❌ Not installed locally")}`);
+        }
+        break;
+
+      case "5":
+        execSpin("Publishing to npm...", `cd "${PKG_PATH}" && npm publish`);
+        break;
+
+      case "6":
+        execSpin("Installing flet-box from npm...", `npm install ${PACKAGE}`);
+        break;
+
+      case "7":
+        execSpin("Uninstalling flet-box...", `npm uninstall ${PACKAGE}`);
+        break;
+
+      case "8":
+        run("WHOAMI", "👤");
+        execCmd(`npm whoami 2>/dev/null || echo "Not logged in"`);
+        break;
+
+      case "9":
+        run("LOGIN", "🔐");
+        execCmd(`npm adduser`);
+        break;
+
+      case "0":
+        console.log(`\n${rainbow("👋 Bye!")}\n`);
+        rl.close();
+        return;
+
+      default:
+        console.log(`\n ${c("red", "❌ Invalid option")}`);
+    }
+    await question(`\n  ${c("gray", "Press Enter to continue...")}`);
+  }
+};

package/bin/commands/release.js

@@ -0,0 +1,189 @@
+/**
+ * @file bin/commands/release.js
+ * @description `flet-box release` — cut a new OTA release of the current project.
+ *
+ * A release is the moment the code is considered *stable*: the version is
+ * bumped (odometer scheme), the production bundle is rebuilt (which regenerates
+ * `www/config.json` with the new version + hash), and the bump is committed and
+ * tagged `vX.Y.Z`. When the tag is pushed, CI builds and deploys `www/` to
+ * GitHub Pages; running apps then fetch the new `config.json`, notice the hash
+ * changed, and self-update — no new store submission required (web layer only).
+ *
+ * The version increments ONLY here, never on a test/preview build, so that
+ * "prueba" builds stay cheap and only a deliberate release moves the number.
+ *
+ * Usage:
+ *   flet-box release [--major|--minor|--patch] [dir] [--push]
+ *
+ *   --patch (default)  bump PATCH  (1.0.0 → 1.0.1)
+ *   --minor            bump MINOR  (1.0.0 → 1.1.0)
+ *   --major            bump MAJOR  (1.0.0 → 2.0.0)
+ *   dir                bundle target folder (default "www")
+ *   --push             push the commit AND the tag to origin after tagging
+ */
+
+import { execSync } from "child_process";
+import fs from "fs";
+import path from "path";
+import { c, banner, gradient } from "../utils/colors.js";
+import { createBundle } from "./createBundle.js";
+import { INITIAL_VERSION, incrementVersion, isValidVersion } from "../utils/version.js";
+
+/**
+ * Runs a git command in `cwd`, returning trimmed stdout. Throws on failure.
+ *
+ * @param {string} cmd - Git subcommand + args (without the leading "git").
+ * @param {string} cwd - Working directory.
+ * @returns {string} Trimmed stdout.
+ */
+const git = (cmd, cwd) =>
+  execSync(`git ${cmd}`, { cwd, encoding: "utf8", stdio: ["pipe", "pipe", "pipe"] }).trim();
+
+/**
+ * Cuts a new release.
+ *
+ * @async
+ * @param {string[]} argv - Args after the `release` keyword,
+ *   e.g. `["--minor", "--push"]`.
+ * @returns {Promise<void>}
+ */
+export const release = async (argv = []) => {
+  const projectRoot = process.cwd();
+
+  // ---- Parse flags --------------------------------------------------------
+  let type = "patch";
+  let push = false;
+  let target = null;
+  for (const arg of argv) {
+    if (arg === "--major" || arg === "--minor" || arg === "--patch") {
+      type = arg.slice(2);
+    } else if (arg === "--push") {
+      push = true;
+    } else if (!arg.startsWith("-") && !target) {
+      // First bare positional is the bundle target directory.
+      target = arg;
+    }
+  }
+
+  console.log(banner("🚀 FletBox Release", `--${type}`));
+
+  // ---- Guard: must be inside a FletBox project ---------------------------
+  if (!fs.existsSync(path.join(projectRoot, "src", "app.js"))) {
+    console.error(c("red", "❌ Not inside a FletBox project"));
+    console.log(c("gray", "Run this in a project folder with src/app.js (flet-box create <name>)."));
+    process.exit(1);
+  }
+
+  // ---- Guard: must be a git repository -----------------------------------
+  // The release flow relies on tags so CI can deploy the exact released commit.
+  try {
+    git("rev-parse --is-inside-work-tree", projectRoot);
+  } catch {
+    console.error(c("red", "❌ Not a git repository"));
+    console.log(
+      c("gray", "Releases are tagged so CI can deploy them. Run: git init && git add -A && git commit -m \"init\""),
+    );
+    process.exit(1);
+  }
+
+  // ---- Guard: working tree must be clean ---------------------------------
+  // A dirty tree means the tag would NOT capture what you think you released
+  // (CI checks out the tag = committed state). Force the dev to commit first.
+  const dirty = git("status --porcelain", projectRoot);
+  if (dirty) {
+    console.error(c("red", "❌ Working tree has uncommitted changes"));
+    console.log(c("gray", "Commit or stash them first so the release tag captures exactly this state:"));
+    console.log(c("dim", dirty.split("\n").slice(0, 20).map((l) => "   " + l).join("\n")));
+    process.exit(1);
+  }
+
+  // ---- Bump version in package.json --------------------------------------
+  const pkgPath = path.join(projectRoot, "package.json");
+  if (!fs.existsSync(pkgPath)) {
+    console.error(c("red", "❌ No package.json found"));
+    process.exit(1);
+  }
+  const pkgRaw = fs.readFileSync(pkgPath, "utf8");
+  const pkg = JSON.parse(pkgRaw);
+  const current = isValidVersion(pkg.version) ? pkg.version : INITIAL_VERSION;
+  const next = incrementVersion(current, type);
+
+  pkg.version = next;
+  // Preserve the file's existing 2-space style + trailing newline.
+  fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + "\n");
+  console.log(
+    c("blue", "\n🔢 Version ") +
+      c("gray", current) +
+      c("blue", " → ") +
+      gradient(next, "#34d399", "#22d3ee"),
+  );
+
+  // Safety net: createBundle can hard-exit (e.g. esbuild install failure). If we
+  // leave without committing, roll package.json back so the tree isn't left
+  // dirty with a version bump for a release that never happened (which would
+  // also wedge the clean-tree guard on the next attempt).
+  let committed = false;
+  process.once("exit", () => {
+    if (!committed) {
+      try {
+        fs.writeFileSync(pkgPath, pkgRaw);
+      } catch {
+        /* best effort */
+      }
+    }
+  });
+
+  // ---- Rebuild the bundle (regenerates www/config.json) ------------------
+  await createBundle(target);
+
+  // ---- Commit + tag ------------------------------------------------------
+  const tag = `v${next}`;
+  try {
+    // Stage exactly what the release produced. The clean-tree guard above
+    // guarantees the only changes now are the version bump + the freshly built
+    // bundle, so `add -A` captures the release faithfully. git still honours
+    // .gitignore: a gitignored target (e.g. a generated project's www/) is
+    // skipped, leaving only package.json for CI to rebuild from the tag, while a
+    // tracked/untracked target is committed so the tag matches what shipped and
+    // the tree ends clean (release stays repeatable).
+    git("add -A", projectRoot);
+    git(`commit -m "chore(release): ${tag}"`, projectRoot);
+    git(`tag -a ${tag} -m "Release ${tag}"`, projectRoot);
+    committed = true;
+    console.log(c("green", `\n✅ Committed and tagged ${tag}`));
+  } catch (error) {
+    committed = true; // keep the bump; the message below tells the dev how to finish
+    console.error(c("red", "❌ Git commit/tag failed:"), error.message);
+    console.log(
+      c("yellow", `⚠️ package.json was bumped to ${next} but the release was not committed. `) +
+        c("gray", "Fix the git issue, then: git add package.json && git commit && git tag " + tag),
+    );
+    process.exit(1);
+  }
+
+  // ---- Optional push -----------------------------------------------------
+  if (push) {
+    try {
+      git("push", projectRoot);
+      git(`push origin ${tag}`, projectRoot);
+      console.log(c("green", `✅ Pushed commit + tag ${tag} to origin`));
+    } catch (error) {
+      console.error(c("red", "❌ Push failed:"), error.message);
+      console.log(c("gray", `Push manually with: git push && git push origin ${tag}`));
+      process.exit(1);
+    }
+  }
+
+  // ---- Summary -----------------------------------------------------------
+  console.log(
+    c("gray", `\n      📦 Bundle: ${gradient((target || "www") + "/", "#8b5cf6", "#d946ef")}`),
+  );
+  if (!push) {
+    console.log(
+      c("gray", `      ⬆️  Publish it: ${gradient(`git push && git push origin ${tag}`, "#22d3ee", "#38bdf8")}`),
+    );
+  }
+  console.log(
+    c("dim", "      ℹ️  CI deploys www/ to GitHub Pages on the tag; open apps self-update from config.json."),
+  );
+};

package/bin/commands/runBundle.js

@@ -0,0 +1,62 @@
+/**
+ * @file bin/commands/runBundle.js
+ * @description Builds the project bundle and immediately serves it for production preview.
+ *
+ * Combines `createBundle` and `runDevServer` into a single command so developers
+ * can verify the production artefact (a single `src/app.js`) without manually
+ * running two separate commands.  Hot reload is intentionally disabled — the goal
+ * is to test exactly what would ship, not to iterate on source.
+ */
+
+import { createBundle } from "./createBundle.js";
+import { runDevServer } from "./runServer.js";
+import { c, banner, gradient, dot } from "../utils/colors.js";
+
+/**
+ * Builds the project bundle and serves it with a static dev server.
+ *
+ * Workflow:
+ * 1. Runs `createBundle(target)` to produce the minified output directory.
+ * 2. Changes the working directory to the bundle folder.
+ * 3. Starts `runDevServer` in SPA mode (all unknown paths fall back to `index.html`)
+ *    with hot reload disabled so the served content exactly matches the build output.
+ *
+ * @async
+ * @param {object}  [options={}]               - Configuration options.
+ * @param {string}  [options.target="www"]      - Name of the bundle directory relative
+ *   to the project root.  Passed directly to `createBundle`.
+ * @param {number}  [options.port=8000]         - TCP port the server should listen on.
+ * @param {boolean} [options.askPort=false]     - When `true`, prompt the user for a port
+ *   if the chosen one is unavailable.
+ * @param {boolean} [options.logRequests=true]  - Whether to log each HTTP request to stdout.
+ * @returns {Promise<void>}
+ */
+export const runBundle = async ({
+  target = "www",
+  port = 8000,
+  askPort = false,
+  logRequests = true,
+} = {}) => {
+  console.log(banner("🚀 Run Bundle", `build + serve ${target}/`));
+
+  // Step 1: Produce the bundle from the current source tree.
+  await createBundle(target);
+
+  // Step 2: Notify the user that the build succeeded and the server is about to start.
+  console.log(
+    `\n  ${dot("#34d399")} ${c("bold", "Bundle ready")} ${c("gray", target + "/ · SPA · hot reload OFF")}\n`,
+  );
+
+  // Step 3: Serve from inside the bundle directory so relative paths resolve correctly.
+  process.chdir(target);
+
+  await runDevServer({
+    spaMode: true,      // Enable SPA fallback (index.html for unknown routes).
+    hotReload: false,   // Hot reload is off — we're previewing the production build.
+    port,
+    askPort,
+    logRequests,
+  });
+};
+
+export default runBundle;

package/bin/commands/runCloudflare.js

@@ -0,0 +1,89 @@
+// bin/commands/runCloudflare.js
+import { spawn, spawnSync } from "child_process";
+import { c, banner, divider } from "../utils/colors.js";
+import { spinner } from "../utils/spinner.js";
+import { runDevServer } from "./runServer.js";
+
+const TUNNEL_URL_RE = /https:\/\/[a-z0-9-]+\.trycloudflare\.com/;
+
+/**
+ * Starts the local dev server and exposes it through a free Cloudflare quick
+ * tunnel (no account required), printing the public HTTPS link to the console.
+ *
+ * @param {{ port?: number, logRequests?: boolean }} [options]
+ * @returns {Promise<void>}
+ */
+export const runCloudflareDemo = async (options = {}) => {
+  const { port = 8000, logRequests = false } = options;
+
+  const probe = spawnSync("cloudflared", ["--version"], { encoding: "utf-8" });
+  if (probe.error) {
+    console.error(c("red", "❌ cloudflared is not installed"));
+    console.log(c("gray", "  Install it first:"));
+    console.log(c("cyan", "    macOS:   brew install cloudflared"));
+    console.log(
+      c("cyan", "    Linux:   https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/"),
+    );
+    process.exit(1);
+  }
+
+  console.log(banner("☁️  FletBox Cloudflare Demo", "public HTTPS tunnel"));
+
+  await runDevServer({
+    spaMode: false,
+    hotReload: true,
+    port,
+    askPort: false,
+    logRequests,
+  });
+
+  const boot = spinner("Opening Cloudflare quick tunnel...");
+  const tunnel = spawn(
+    "cloudflared",
+    ["tunnel", "--url", `http://localhost:${port}`],
+    { stdio: ["ignore", "pipe", "pipe"] },
+  );
+
+  let announced = false;
+
+  const announce = (url) => {
+    announced = true;
+    boot.succeed("Cloudflare tunnel ready");
+    console.log("");
+    console.log(c("brightCyan", "  🌐 Public link (open this):"));
+    console.log(`  ${c("bold", c("brightGreen", url))}`);
+    console.log("");
+    console.log(c("gray", `  Local:  http://localhost:${port}`));
+    console.log(
+      c("gray", "  The tunnel stays alive while this process runs. Ctrl+C to stop."),
+    );
+    console.log(divider("", "#3730a3"));
+  };
+
+  const onData = (chunk) => {
+    if (announced) return;
+    const match = chunk.toString().match(TUNNEL_URL_RE);
+    if (match) announce(match[0]);
+  };
+
+  tunnel.stdout.on("data", onData);
+  tunnel.stderr.on("data", onData);
+
+  tunnel.on("exit", (code) => {
+    if (announced) return;
+    boot.fail(`Cloudflare tunnel exited (code ${code})`);
+    console.log(
+      c("gray", "  The local server is still running; the tunnel could not start."),
+    );
+  });
+
+  // runDevServer's SIGINT handler calls process.exit, so also release the
+  // tunnel on the synchronous "exit" event to avoid leaving it orphaned.
+  process.on("exit", () => {
+    try {
+      tunnel.kill("SIGTERM");
+    } catch (e) {}
+  });
+};
+
+export default runCloudflareDemo;

package/bin/commands/runNative.js

@@ -0,0 +1,109 @@
+/**
+ * @file bin/commands/runNative.js
+ * @description Compiles and launches a FletBox app on an Android emulator or
+ * physical device, or on the iOS Simulator, wrapping Capacitor's `cap run`.
+ *
+ * Usage: `flet-box run-native <android|ios> [--device] [--livereload]`
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { c, banner } from "../utils/colors.js";
+import {
+  assertCapacitorProject,
+  ensureNpmDependencies,
+  run,
+} from "../utils/capacitor.js";
+import { prepareAndroidEnvironment } from "./buildAndroid.js";
+import { requireAppleToolchain } from "./buildIOS.js";
+
+const androidPackages = [
+  "@capacitor/android",
+  "@capacitor/cli",
+  "@capacitor/core",
+  "flet-box",
+  "sharp",
+];
+
+const iosPackages = [
+  "@capacitor/cli",
+  "@capacitor/core",
+  "@capacitor/ios",
+  "flet-box",
+  "sharp",
+];
+
+/**
+ * Entry point for `flet-box run-native`.
+ *
+ * @param {string[]} [rawArgs=[]] - Raw CLI args: `<android|ios>` platform plus
+ *   `--device` (physical device) and `--livereload` (hot reload) flags.
+ * @returns {void}
+ */
+export const runNative = (rawArgs = []) => {
+  const platform = rawArgs[0];
+  if (platform !== "android" && platform !== "ios") {
+    throw new Error(
+      'Usage: `flet-box run-native <android|ios>` — for example `flet-box run-native android`.',
+    );
+  }
+
+  const supportedFlags = ["--device", "--livereload"];
+  const unknownFlags = rawArgs.slice(1).filter((arg) => !supportedFlags.includes(arg));
+  if (unknownFlags.length > 0) {
+    throw new Error(
+      `Unknown option for \`run-native ${platform}\`: ${unknownFlags.join(", ")}. Supported options: ${supportedFlags.join(", ")}.`,
+    );
+  }
+  const device = rawArgs.includes("--device");
+  const livereload = rawArgs.includes("--livereload");
+
+  const isAndroid = platform === "android";
+  const scripts = isAndroid ? ["android:init", "android:sync"] : ["ios:init", "ios:sync"];
+  const packages = isAndroid ? androidPackages : iosPackages;
+
+  const { projectRoot } = assertCapacitorProject(scripts);
+  console.log(
+    banner(
+      "🚀 Flet-Box Native",
+      isAndroid
+        ? device ? "Android device" : "Android emulator"
+        : device ? "iOS device" : "iOS Simulator",
+    ),
+  );
+
+  ensureNpmDependencies(projectRoot, packages);
+
+  let env = process.env;
+  if (isAndroid) {
+    env = prepareAndroidEnvironment();
+  } else {
+    requireAppleToolchain({ simulator: !device });
+  }
+
+  const platformDir = path.join(projectRoot, isAndroid ? "android" : "ios");
+  if (!fs.existsSync(platformDir)) {
+    console.log(c("blue", `\n📱 Initializing the ${isAndroid ? "Android" : "iOS"} platform...`));
+    run("npm", ["run", isAndroid ? "android:init" : "ios:init"], projectRoot, `${platform} initialization`, env);
+  }
+
+  console.log(c("blue", "\n🔄 Building and synchronizing the app..."));
+  run("npm", ["run", isAndroid ? "android:sync" : "ios:sync"], projectRoot, `${platform} synchronization`, env);
+
+  const capArgs = ["cap", "run", platform];
+  if (device) capArgs.push("--device");
+  if (livereload) capArgs.push("--livereload");
+
+  console.log(
+    c("blue", `\n🏗️ Compiling and launching on the ${isAndroid ? "Android" : "iOS"} ${device ? "device" : "emulator/simulator"}...`),
+  );
+  run("npx", capArgs, projectRoot, `${platform} launch`, env);
+
+  console.log(
+    c(
+      "green",
+      `\n🚀 App launched on the ${isAndroid ? "Android" : "iOS"} ${device ? "device" : "emulator/simulator"}.` +
+        `\n📍 Re-run \`flet-box run-native ${platform}\` to rebuild, or add \`--livereload\` for hot reload.`,
+    ),
+  );
+};