flet-box 0.0.0-stage → 1.0.1

package/bin/utils/capacitor.js

@@ -0,0 +1,137 @@
+/**
+ * @file bin/utils/capacitor.js
+ * @description Shared plumbing for the Capacitor build commands (`build android`,
+ * `build ios`). Both commands do the same three things before they touch a
+ * native toolchain: validate the project, make sure the generated npm
+ * dependencies exist, and run child processes with readable failures.
+ */
+
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { c } from "./colors.js";
+
+/**
+ * Runs a command synchronously, inheriting stdio so the user watches Gradle,
+ * CocoaPods or Xcode do their work.
+ *
+ * @param {string} command - Executable to run.
+ * @param {string[]} args - Arguments for the executable.
+ * @param {string} cwd - Working directory.
+ * @param {string} label - Human readable name used in error messages.
+ * @param {NodeJS.ProcessEnv} [env] - Environment for the child process.
+ * @returns {void}
+ * @throws {Error} When the command cannot start or exits with a non-zero code.
+ */
+export const run = (command, args, cwd, label, env = process.env) => {
+  const result = spawnSync(command, args, {
+    cwd,
+    stdio: "inherit",
+    shell: process.platform === "win32",
+    env,
+  });
+
+  if (result.error) {
+    throw new Error(`${label} could not start: ${result.error.message}`);
+  }
+  if (result.status !== 0) {
+    throw new Error(
+      `${label} failed with exit code ${result.status ?? "unknown"}`,
+    );
+  }
+};
+
+/**
+ * Checks that a command exists and can report a version.
+ *
+ * @param {string} command - Executable name, resolved through PATH.
+ * @param {string[]} [args] - Arguments used as the probe (defaults to `--version`).
+ * @returns {boolean} `true` when the probe exits successfully.
+ */
+export const commandExists = (command, args = ["--version"]) => {
+  const result = spawnSync(command, args, { stdio: "ignore" });
+  return !result.error && result.status === 0;
+};
+
+const hasPackage = (projectRoot, packageName) =>
+  fs.existsSync(
+    path.join(projectRoot, "node_modules", ...packageName.split("/"), "package.json"),
+  );
+
+/**
+ * Installs the project npm dependencies when any of the packages the native
+ * build needs are missing. Projects created by `flet-box create` already declare
+ * them, this only repairs projects whose `node_modules` was never installed.
+ *
+ * @param {string} projectRoot - Absolute path of the project.
+ * @param {string[]} requiredPackages - Packages that must be resolvable.
+ * @returns {void}
+ */
+export const ensureNpmDependencies = (projectRoot, requiredPackages) => {
+  const missingPackages = requiredPackages.filter(
+    (packageName) => !hasPackage(projectRoot, packageName),
+  );
+  if (missingPackages.length === 0) return;
+
+  console.log(
+    c(
+      "yellow",
+      `\n📦 Installing project dependencies: ${missingPackages.join(", ")}`,
+    ),
+  );
+  run("npm", ["install"], projectRoot, "npm dependency installation");
+
+  const stillMissing = requiredPackages.filter(
+    (packageName) => !hasPackage(projectRoot, packageName),
+  );
+  if (stillMissing.length > 0) {
+    throw new Error(
+      `Dependencies are still missing after npm install: ${stillMissing.join(", ")}.`,
+    );
+  }
+};
+
+/**
+ * Validates that the current directory is a FletBox project scaffolded for
+ * Capacitor, and returns its parsed `package.json`.
+ *
+ * @param {string[]} requiredScripts - npm scripts the caller needs, for example `["ios:init"]`.
+ * @returns {{ projectRoot: string, projectPackage: object }} Project root and manifest.
+ * @throws {Error} When the folder is not a Capacitor-enabled FletBox project.
+ */
+export const assertCapacitorProject = (requiredScripts) => {
+  const projectRoot = process.cwd();
+  const packagePath = path.join(projectRoot, "package.json");
+  const capacitorConfig = [
+    "capacitor.config.json",
+    "capacitor.config.ts",
+    "capacitor.config.js",
+  ].some((file) => fs.existsSync(path.join(projectRoot, file)));
+
+  if (!fs.existsSync(path.join(projectRoot, "src", "app.js"))) {
+    throw new Error("Run this inside a Flet-Box project with src/app.js.");
+  }
+  if (!fs.existsSync(packagePath) || !capacitorConfig) {
+    throw new Error(
+      "This project is not configured for Capacitor. Create it with a recent version of Flet-Box.",
+    );
+  }
+
+  let projectPackage;
+  try {
+    projectPackage = JSON.parse(fs.readFileSync(packagePath, "utf8"));
+  } catch (error) {
+    throw new Error(`Could not read package.json: ${error.message}`);
+  }
+
+  const missingScripts = requiredScripts.filter(
+    (script) => !projectPackage?.scripts?.[script],
+  );
+  if (missingScripts.length > 0) {
+    throw new Error(
+      `Missing npm scripts: ${missingScripts.join(", ")}. Recreate the project with a recent version of Flet-Box.`,
+    );
+  }
+
+  return { projectRoot, projectPackage };
+};

package/bin/utils/colors.js

@@ -0,0 +1,215 @@
+// bin/utils/colors.js
+// Visual system of the CLI: ANSI + truecolor (gradients) with safe fallbacks.
+
+const TRUE_COLOR = (() => {
+  if (process.env.COLORTERM === "truecolor") return true;
+  return /iTerm|vscode|kitty|ghostty|hyper|alacritty|wezterm|contour|tmux/i.test(
+    process.env.TERM_PROGRAM || "",
+  );
+})();
+
+// Colors only if there is a TTY and they weren't disabled (NO_COLOR, TERM=dumb)
+const enabled = (() => {
+  if (process.env.NO_COLOR) return false;
+  if (process.env.TERM === "dumb") return false;
+  try {
+    return Boolean(process.stdout && process.stdout.isTTY);
+  } catch {
+    return false;
+  }
+})();
+
+const code = (x) => (enabled ? x : "");
+const reset = () => code("\x1b[0m");
+
+export const colors = {
+  // Standard
+  black: code("\x1b[30m"),
+  red: code("\x1b[31m"),
+  green: code("\x1b[32m"),
+  yellow: code("\x1b[33m"),
+  blue: code("\x1b[34m"),
+  magenta: code("\x1b[35m"),
+  cyan: code("\x1b[36m"),
+  white: code("\x1b[37m"),
+  gray: code("\x1b[90m"),
+  // Bright
+  brightRed: code("\x1b[91m"),
+  brightGreen: code("\x1b[92m"),
+  brightYellow: code("\x1b[93m"),
+  brightBlue: code("\x1b[94m"),
+  brightMagenta: code("\x1b[95m"),
+  brightCyan: code("\x1b[96m"),
+  brightWhite: code("\x1b[97m"),
+  // Styles
+  bold: code("\x1b[1m"),
+  dim: code("\x1b[2m"),
+  italic: code("\x1b[3m"),
+  underline: code("\x1b[4m"),
+};
+
+export const c = (color, text) => {
+  const colorCode = colors[color];
+  if (colorCode == null) return text;
+  return `${colorCode}${text}${reset()}`;
+};
+
+// ---------- Truecolor ----------
+
+const rgb = (r, g, b) => code(`\x1b[38;2;${r};${g};${b}m`);
+const hex2rgb = (hex) => {
+  let h = (hex || "#6366f1").replace("#", "");
+  if (h.length === 3) h = h.split("").map((x) => x + x).join("");
+  return [
+    parseInt(h.slice(0, 2), 16) || 0,
+    parseInt(h.slice(2, 4), 16) || 0,
+    parseInt(h.slice(4, 6), 16) || 0,
+  ];
+};
+
+// ANSI fallback for terminals without truecolor (e.g. Terminal.app)
+const ANSI_FALLBACK = ["\x1b[36m", "\x1b[96m", "\x1b[35m", "\x1b[95m"];
+const paintFallback = (text) => {
+  const chars = [...text];
+  let out = "";
+  for (let i = 0; i < chars.length; i++) {
+    out += ANSI_FALLBACK[i % ANSI_FALLBACK.length] + chars[i];
+  }
+  return out + reset();
+};
+
+export const hex = (text, hexColor = "#6366f1") => {
+  if (!enabled || !TRUE_COLOR) return text;
+  const [r, g, b] = hex2rgb(hexColor);
+  return `${rgb(r, g, b)}${text}${reset()}`;
+};
+
+export const gradient = (text, from = "#6366f1", to = "#d946ef") => {
+  if (!enabled || text.length === 0) return text;
+  if (!TRUE_COLOR) return paintFallback(text);
+  const [f1, f2, f3] = hex2rgb(from);
+  const [t1, t2, t3] = hex2rgb(to);
+  const chars = [...text];
+  const N = Math.max(chars.length - 1, 1);
+  let out = "";
+  for (let i = 0; i < chars.length; i++) {
+    out +=
+      rgb(
+        Math.round(f1 + ((t1 - f1) * i) / N),
+        Math.round(f2 + ((t2 - f2) * i) / N),
+        Math.round(f3 + ((t3 - f3) * i) / N),
+      ) + chars[i];
+  }
+  return out + reset();
+};
+
+const PALETTE = [
+  "#6366f1",
+  "#8b5cf6",
+  "#d946ef",
+  "#ec4899",
+  "#f43f5e",
+  "#fb923c",
+  "#fbbf24",
+  "#34d399",
+  "#22d3ee",
+  "#6366f1",
+];
+
+export const rainbow = (text) => {
+  if (!enabled || text.length === 0) return text;
+  if (!TRUE_COLOR) return paintFallback(text);
+  const chars = [...text];
+  const N = chars.length;
+  let out = "";
+  for (let i = 0; i < N; i++) {
+    const [r, g, b] = hex2rgb(PALETTE[Math.floor((i / N) * (PALETTE.length - 1))]);
+    out += rgb(r, g, b) + chars[i];
+  }
+  return out + reset();
+};
+
+// ---------- Layout helpers ----------
+
+const strip = (t) => t.replace(/\x1b\[[0-9;]*m/g, "");
+export const width = (t) => [...strip(t)].length;
+
+// Display length: emoji / wide glyphs count as 2 cells
+const dispLen = (t) =>
+  [...strip(t)].reduce(
+    (n, ch) => n + (ch.codePointAt(0) >= 0x1100 ? 2 : 1),
+    0,
+  );
+
+export const divider = (text = "", color = "#8b5cf6") => {
+  const line = "─".repeat(Math.max(2, 56 - width(text)));
+  if (!text) return hex(line, color);
+  return hex(line, color) + " " + text + " " + hex(line, color);
+};
+
+export const section = (icon, text, color = "#22d3ee") =>
+  `\n  ${gradient(icon + "  " + text, color, "#a855f7")} ${hex("─".repeat(Math.max(4, 46 - width(text))), "#4338ca")}`;
+
+// Double-line panel with gradient border and centered title
+export const panel = (title, subtitle = "", { minW = 62 } = {}) => {
+  const content = rainbow(title) + (subtitle ? c("gray", "  " + subtitle) : "");
+  const cw = dispLen(content);
+  const W = Math.max(cw + 4, minW);
+  const total = W - cw;
+  const left = " ".repeat(Math.floor(total / 2));
+  const right = " ".repeat(Math.ceil(total / 2));
+  const border = TRUE_COLOR
+    ? gradient("═".repeat(W), "#6366f1", "#a855f7")
+    : c("cyan", "═".repeat(W));
+  const corner = (ch) => hex(ch, "#818cf8");
+  return (
+    "\n" +
+    corner("╔") + border + corner("╗") + "\n" +
+    corner("║") + left + content + right + corner("║") + "\n" +
+    corner("╚") + border + corner("╝") + "\n"
+  );
+};
+
+export const banner = (title, subtitle = "", opts = {}) =>
+  panel(title, subtitle, opts);
+
+export const badge = (icon, text, color = "brightCyan") =>
+  `  ${c(color, icon + " " + text)}`;
+
+// Status dot (green by default, red/amber for failures/warnings)
+export const dot = (color = "#34d399") => hex("●", color);
+
+// Typewriter effect: prints the text character by character (only on a TTY)
+export const typewriter = async (
+  text,
+  { ms = 12, color = "#34d399" } = {},
+) => {
+  if (!enabled) {
+    console.log(text);
+    return;
+  }
+  const paint = TRUE_COLOR
+    ? (() => {
+        const [r, g, b] = hex2rgb(color);
+        return (ch) => `\x1b[38;2;${r};${g};${b}m${ch}`;
+      })()
+    : (ch) => `\x1b[96m${ch}`;
+  for (const ch of [...text]) {
+    process.stdout.write(paint(ch));
+    await new Promise((res) => setTimeout(res, ms));
+  }
+  process.stdout.write("\x1b[0m\n");
+};
+
+// Global Ctrl+C handler
+export const setupCtrlC = () => {
+  process.on("SIGINT", () => {
+    console.log(`\n\n${rainbow("👋 Bye!")}\n`);
+    process.exit(0);
+  });
+};
+
+// Show help message for Ctrl+C
+export const showExitHint = () => {
+  console.log(`${c("gray", "Press Ctrl+C to exit")}`);
+};

package/bin/utils/helpers.js

@@ -0,0 +1,80 @@
+// bin/utils/helpers.js
+import fs from "fs";
+import path from "path";
+import { execSync } from "child_process";
+import { c } from "./colors.js";
+
+export const createFile = (filePath, content) => {
+  try {
+    const dir = path.dirname(filePath);
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+    fs.writeFileSync(filePath, content, "utf8");
+    console.log(`${c("green", "✅")} Created: ${path.basename(filePath)}`);
+  } catch (error) {
+    console.error(
+      `${c("red", "❌")} Failed to create ${filePath}: ${error.message}`,
+    );
+  }
+};
+
+export const copyFile = (source, dest) => {
+  try {
+    if (fs.existsSync(source)) {
+      const destDir = path.dirname(dest);
+      if (!fs.existsSync(destDir)) {
+        fs.mkdirSync(destDir, { recursive: true });
+      }
+      fs.copyFileSync(source, dest);
+      console.log(`${c("green", "✅")} Copied: ${path.basename(source)}`);
+      return true;
+    } else {
+      console.log(
+        `${c("yellow", "⚠️")} Source not found: ${path.basename(source)}`,
+      );
+      return false;
+    }
+  } catch (error) {
+    console.error(
+      `${c("red", "❌")} Failed to copy ${path.basename(source)}: ${error.message}`,
+    );
+    return false;
+  }
+};
+
+export const makeExecutable = (filePath) => {
+  try {
+    if (fs.existsSync(filePath)) {
+      fs.chmodSync(filePath, 0o755);
+      console.log(`${c("blue", "🔧")} Executable: ${path.basename(filePath)}`);
+    }
+  } catch (error) {
+    if (process.env.DEBUG) {
+      console.error(
+        `${c("red", "⚠️")} Could not make executable: ${path.basename(filePath)}`,
+      );
+    }
+  }
+};
+
+export const execCmd = (cmd) => {
+  try {
+    execSync(cmd, {
+      stdio: "inherit",
+      shell: true,
+    });
+    return true;
+  } catch (error) {
+    console.error(`${c("red", "❌")} Command failed: ${cmd}`);
+    if (process.env.DEBUG) {
+      console.error(error.message);
+    }
+    return false;
+  }
+};
+
+// Fixed: Now returns actual package path
+export const getPackagePath = () => {
+  return path.join(process.cwd(), "node_modules", "flet-box");
+};

package/bin/utils/spinner.js

@@ -0,0 +1,96 @@
+// bin/utils/spinner.js
+// Dependency-free CLI spinner (keeps flet-box zero-deps, looks like ora).
+
+import { execSync } from "child_process";
+import { c } from "./colors.js";
+
+const FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+const INTERVAL = 80;
+const RESET = "\x1b[0m";
+const CYAN = "\x1b[96m";
+
+const isTTY = () => Boolean(process.stdout && process.stdout.isTTY);
+
+class Spinner {
+  constructor(text = "") {
+    this.text = text;
+    this.frame = 0;
+    this.timer = null;
+    this.running = false;
+  }
+
+  start() {
+    if (this.running) return this;
+    this.running = true;
+    process.stdout.write("\n");
+    this.timer = setInterval(() => this.render(), INTERVAL);
+    this.render();
+    return this;
+  }
+
+  render() {
+    const f = FRAMES[this.frame % FRAMES.length];
+    process.stdout.write(`\x1b[1A\x1b[K${CYAN}${f}${RESET} ${this.text}\n`);
+    this.frame++;
+  }
+
+  stop(msg) {
+    if (!this.running) return;
+    this.running = false;
+    clearInterval(this.timer);
+    process.stdout.write(`\x1b[1A\x1b[K${msg}\n`);
+  }
+
+  succeed(text) {
+    this.stop(`${c("green", "✔")} ${text ?? this.text}`);
+  }
+
+  fail(text) {
+    this.stop(`${c("red", "✖")} ${text ?? this.text}`);
+  }
+
+  setText(text) {
+    this.text = text;
+  }
+}
+
+// Return a no-op spinner when there is no TTY (instant clean output)
+export const spinner = (text) => {
+  if (!isTTY()) {
+    console.log(c("gray", text));
+    return { succeed: () => {}, fail: () => {}, stop: () => {}, setText: () => {} };
+  }
+  return new Spinner(text).start();
+};
+
+// Run a shell command with a spinner. Silences stdout/stderr; on failure the
+// last lines of stderr are shown.
+export const execSpin = (text, cmd) => {
+  if (!isTTY()) {
+    try {
+      execSync(cmd, { stdio: "inherit", shell: true });
+      console.log(c("green", `✔ ${text}`));
+      return true;
+    } catch {
+      console.log(c("red", `✖ ${text}`));
+      return false;
+    }
+  }
+  const s = new Spinner(text).start();
+  try {
+    execSync(cmd, {
+      stdio: ["ignore", "pipe", "pipe"],
+      shell: true,
+      encoding: "utf8",
+    });
+    s.succeed(text);
+    return true;
+  } catch (e) {
+    s.fail(text);
+    const err = (e.stderr || "").toString().trim();
+    if (err) {
+      console.log(c("red", err.split("\n").slice(-4).join("\n")));
+    }
+    return false;
+  }
+};