kasy-cli 1.2.1

package/lib/scaffold/shared/template-strings.js

@@ -0,0 +1,112 @@
+/**
+ * User-facing strings in generated template files (Makefile, .env.example).
+ * Keys must match the language used by the CLI (en, pt, es).
+ *
+ * @module scaffold/shared/template-strings
+ */
+
+const TEMPLATE_STRINGS = {
+  en: {
+    launch: { dev: 'dev', prod: 'prod' },
+    features: {
+      comment1: '/// Feature flags — generated by Kasy CLI based on user choices.',
+      comment2: '/// When false, the router skips that feature\'s routes and the guard ignores it.',
+      comment3: '/// When true, the app includes web support:',
+      comment4: '///   - anonymous sign-up is disabled on web (user is redirected to /signin)',
+      comment5: '///   - onboarding is skipped on web',
+      comment6: '///   - home widgets and background fetch are no-ops on web',
+      comment7: '/// When true, RevenueCat Web Billing is enabled for subscriptions on web.',
+    },
+    makefile: {
+      comment1: '# Run the app — Flutter picks the first available device',
+      comment2: '# Usage: make run | make run-ios | make run-android | make run-web',
+      comment3: "# Hot reload: press 'r' in the terminal while the app is running",
+      comment4: '# run-ios/run-android: shows device list — select iPhone, simulator or Android',
+      releaseIos: '# iOS App Store release (requires: kasy ios configure)',
+      releaseIosTarget: 'release-ios',
+    },
+    envExample: {
+      generated: '# Generated by Kasy CLI',
+      dartDefine: '# Copy this file to .env for local development',
+      envSource: '# .env is the local source of truth. --dart-define remains supported for CI/release.',
+      envDev: 'ENV=dev   # or prod',
+      supabase: '# Supabase',
+      apiRest: '# API REST',
+      revenuecat: '# RevenueCat',
+      sentry: '# Sentry (prod only)',
+      mixpanel: '# Mixpanel',
+      llmChat: '# LLM Chat — Cloud/Edge Function endpoint (API key stays on the server, not here)',
+    },
+  },
+  pt: {
+    launch: { dev: 'desenv', prod: 'prod' },
+    features: {
+      comment1: '/// Feature flags — gerado pelo Kasy CLI conforme escolhas do usuário.',
+      comment2: '/// Quando false, o router ignora as rotas dessa feature e o guard ignora.',
+      comment3: '/// Quando true, o app inclui suporte web:',
+      comment4: '///   - cadastro anônimo desativado na web (usuário redirecionado para /signin)',
+      comment5: '///   - onboarding ignorado na web',
+      comment6: '///   - home widgets e background fetch são no-op na web',
+      comment7: '/// Quando true, RevenueCat Web Billing está ativo para assinaturas na web.',
+    },
+    makefile: {
+      comment1: '# Rode o app — Flutter escolhe o primeiro dispositivo disponível',
+      comment2: '# Uso: make run | make run-ios | make run-android | make run-web',
+      comment3: "# Hot reload: pressione 'r' no terminal enquanto o app roda",
+      comment4: '# run-ios/run-android: mostra lista de dispositivos — selecione iPhone, simulador ou Android',
+      releaseIos: '# Release iOS na App Store (requer: kasy ios configure)',
+      releaseIosTarget: 'release-ios',
+    },
+    envExample: {
+      generated: '# Gerado pelo Kasy CLI',
+      dartDefine: '# Copie este arquivo para .env no desenvolvimento local',
+      envSource: '# O .env é a fonte local. --dart-define segue suportado para CI/release.',
+      envDev: 'ENV=dev   # ou prod',
+      supabase: '# Supabase',
+      apiRest: '# API REST',
+      revenuecat: '# RevenueCat',
+      sentry: '# Sentry (apenas prod)',
+      mixpanel: '# Mixpanel',
+      llmChat: '# LLM Chat — endpoint da Cloud/Edge Function (a chave de API fica no servidor, não aqui)',
+    },
+  },
+  es: {
+    launch: { dev: 'dev', prod: 'prod' },
+    features: {
+      comment1: '/// Feature flags — generado por Kasy CLI según elecciones del usuario.',
+      comment2: '/// Cuando false, el router ignora las rutas de esa feature y el guard ignora.',
+      comment3: '/// Cuando true, el app incluye soporte web:',
+      comment4: '///   - registro anónimo desactivado en web (usuario redirigido a /signin)',
+      comment5: '///   - onboarding ignorado en web',
+      comment6: '///   - home widgets y background fetch son no-op en web',
+      comment7: '/// Cuando true, RevenueCat Web Billing está activo para suscripciones en web.',
+    },
+    makefile: {
+      comment1: '# Ejecuta el app — Flutter elige el primer dispositivo disponible',
+      comment2: '# Uso: make run | make run-ios | make run-android | make run-web',
+      comment3: "# Hot reload: pulsa 'r' en la terminal mientras el app corre",
+      comment4: '# run-ios/run-android: muestra lista de dispositivos — selecciona iPhone, simulador o Android',
+      releaseIos: '# Release iOS en App Store (requiere: kasy ios configure)',
+      releaseIosTarget: 'release-ios',
+    },
+    envExample: {
+      generated: '# Generado por Kasy CLI',
+      dartDefine: '# Copia este archivo a .env para desarrollo local',
+      envSource: '# .env es la fuente local. --dart-define sigue soportado para CI/release.',
+      envDev: 'ENV=dev   # o prod',
+      supabase: '# Supabase',
+      apiRest: '# API REST',
+      revenuecat: '# RevenueCat',
+      sentry: '# Sentry (solo prod)',
+      mixpanel: '# Mixpanel',
+      llmChat: '# LLM Chat — endpoint de Cloud/Edge Function (la clave de API queda en el servidor, no aquí)',
+    },
+  },
+};
+
+function getStrings(lang) {
+  const l = lang && TEMPLATE_STRINGS[lang] ? lang : 'en';
+  return TEMPLATE_STRINGS[l];
+}
+
+module.exports = { TEMPLATE_STRINGS, getStrings };

package/lib/utils/apple-release.js

@@ -0,0 +1,273 @@
+'use strict';
+
+const path = require('node:path');
+const fs = require('fs-extra');
+const os = require('node:os');
+const kleur = require('kleur');
+const { exec } = require('node:child_process');
+const { promisify } = require('node:util');
+
+const execAsync = promisify(exec);
+
+const APPLE_ENV_REL = path.join('.kasy', 'apple.env');
+const APPLE_ENV_EXAMPLE = path.join('.kasy', 'apple.env.example');
+const RELEASE_SCRIPT = path.join('scripts', 'release-ios.sh');
+
+const URL_APP_STORE_CONNECT_APPS = 'https://appstoreconnect.apple.com/apps';
+const URL_APP_STORE_CONNECT_API = 'https://appstoreconnect.apple.com/access/integrations/api';
+
+/**
+ * @param {string} content
+ * @param {string|null} versionNameOverride
+ * @returns {{ updated: string, label: string }}
+ */
+function bumpPubspecVersion(content, versionNameOverride = null) {
+  const match = content.match(/^version:\s*(\d+\.\d+\.\d+)\+(\d+)\s*$/m);
+  if (!match) {
+    throw new Error('Invalid version in pubspec.yaml (expected 1.0.0+1)');
+  }
+  const name = versionNameOverride || match[1];
+  const build = parseInt(match[2], 10) + 1;
+  const next = `version: ${name}+${build}`;
+  return {
+    updated: content.replace(/^version:\s*.*/m, next),
+    label: `${name}+${build}`,
+  };
+}
+
+async function isKasyFlutterProject(projectDir) {
+  const pubspec = path.join(projectDir, 'pubspec.yaml');
+  const iosDir = path.join(projectDir, 'ios');
+  return (await fs.pathExists(pubspec)) && (await fs.pathExists(iosDir));
+}
+
+async function readBundleId(projectDir) {
+  const kitSetupPath = path.join(projectDir, 'kit_setup.json');
+  if (await fs.pathExists(kitSetupPath)) {
+    try {
+      const kit = await fs.readJson(kitSetupPath);
+      if (kit.bundleId) return kit.bundleId;
+    } catch {
+      // ignore
+    }
+  }
+  const pbxPath = path.join(projectDir, 'ios', 'Runner.xcodeproj', 'project.pbxproj');
+  if (await fs.pathExists(pbxPath)) {
+    const content = await fs.readFile(pbxPath, 'utf8');
+    const m = content.match(/PRODUCT_BUNDLE_IDENTIFIER = ([^;]+);/);
+    if (m) return m[1].trim().replace(/"/g, '');
+  }
+  return null;
+}
+
+function applePrivateKeyPath(keyId) {
+  return path.join(os.homedir(), '.appstoreconnect', 'private_keys', `AuthKey_${keyId}.p8`);
+}
+
+async function loadAppleEnv(projectDir) {
+  const envPath = path.join(projectDir, APPLE_ENV_REL);
+  if (!(await fs.pathExists(envPath))) {
+    return null;
+  }
+  const content = await fs.readFile(envPath, 'utf8');
+  const env = {};
+  for (const line of content.split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+    const eq = trimmed.indexOf('=');
+    if (eq === -1) continue;
+    env[trimmed.slice(0, eq).trim()] = trimmed.slice(eq + 1).trim();
+  }
+  return env;
+}
+
+async function validateAppleSetup(projectDir) {
+  const issues = [];
+  const env = await loadAppleEnv(projectDir);
+  if (!env) {
+    issues.push('missing_env');
+    return { ok: false, issues, env: null };
+  }
+  const keyId = env.APP_STORE_API_KEY;
+  const issuerId = env.APP_STORE_ISSUER_ID;
+  if (!keyId || !issuerId) {
+    issues.push('missing_credentials');
+  }
+  if (keyId) {
+    const p8 = applePrivateKeyPath(keyId);
+    if (!(await fs.pathExists(p8))) {
+      issues.push('missing_p8');
+    }
+  }
+  return {
+    ok: issues.length === 0,
+    issues,
+    env,
+  };
+}
+
+async function writeAppleEnv(projectDir, { apiKey, issuerId, appId }) {
+  const lines = [
+    '# Generated by kasy ios configure — do not commit',
+    `APP_STORE_API_KEY=${apiKey}`,
+    `APP_STORE_ISSUER_ID=${issuerId}`,
+  ];
+  if (appId) {
+    lines.push(`APP_STORE_APP_ID=${appId}`);
+  }
+  lines.push('');
+  await fs.ensureDir(path.join(projectDir, '.kasy'));
+  await fs.outputFile(path.join(projectDir, APPLE_ENV_REL), lines.join('\n'), 'utf8');
+}
+
+async function installPrivateKey(sourcePath, keyId) {
+  const destDir = path.join(os.homedir(), '.appstoreconnect', 'private_keys');
+  const destPath = path.join(destDir, `AuthKey_${keyId}.p8`);
+  await fs.ensureDir(destDir);
+  await fs.copy(sourcePath, destPath, { overwrite: true });
+  return destPath;
+}
+
+function openUrl(url) {
+  const platform = process.platform;
+  const cmd =
+    platform === 'darwin'
+      ? `open "${url}"`
+      : platform === 'win32'
+        ? `start "" "${url}"`
+        : `xdg-open "${url}"`;
+  exec(cmd, () => {});
+}
+
+function iosReleaseDocPath() {
+  return 'docs/ios-release.md';
+}
+
+/**
+ * Kasy removes DEVELOPMENT_TEAM from generated projects — user must set signing in Xcode once.
+ */
+async function checkIosSigning(projectDir) {
+  const pbxPath = path.join(projectDir, 'ios', 'Runner.xcodeproj', 'project.pbxproj');
+  if (!(await fs.pathExists(pbxPath))) {
+    return { ok: false, reason: 'no_pbxproj' };
+  }
+  const content = await fs.readFile(pbxPath, 'utf8');
+  if (/DEVELOPMENT_TEAM\s*=\s*[A-Z0-9]{10};/.test(content)) {
+    return { ok: true };
+  }
+  return { ok: false, reason: 'no_team' };
+}
+
+const MIN_DISK_GB_FOR_IOS_BUILD = 15;
+
+const XCODE_CACHE_ERROR_PATTERNS = [
+  /disk I\/O error/i,
+  /DerivedData/i,
+  /build\.db/i,
+  /unable to rename/i,
+  /database is locked/i,
+  /clang: error: no such file or directory:.*\.swiftmodule/i,
+];
+
+async function getFreeDiskGb(checkPath) {
+  if (process.platform !== 'darwin' && process.platform !== 'linux') {
+    return null;
+  }
+  try {
+    const target = checkPath || process.cwd();
+    const { stdout } = await execAsync(`df -g "${target}" | tail -1`);
+    const parts = stdout.trim().split(/\s+/);
+    const avail = parseInt(parts[3], 10);
+    return Number.isFinite(avail) ? avail : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * @returns {{ ok: boolean, freeGb: number|null }}
+ */
+async function checkDiskSpaceForIosBuild(projectDir) {
+  const freeGb = await getFreeDiskGb(projectDir);
+  if (freeGb === null) {
+    return { ok: true, freeGb: null };
+  }
+  return { ok: freeGb >= MIN_DISK_GB_FOR_IOS_BUILD, freeGb };
+}
+
+function isXcodeCacheBuildError(output) {
+  const text = String(output || '');
+  return XCODE_CACHE_ERROR_PATTERNS.some((re) => re.test(text));
+}
+
+function printBuildFailureHints(t, projectDir) {
+  const name = path.basename(projectDir);
+  console.log(kleur.yellow(`\n${t('ios.hints.title')}\n`));
+  console.log(kleur.dim(`  1. ${t('ios.hints.closeXcode')}`));
+  console.log(kleur.cyan(`  2. kasy ios clean${projectDir !== process.cwd() ? ` ${projectDir}` : ''}`));
+  console.log(kleur.dim(`  3. ${t('ios.hints.retry')}: kasy ios release\n`));
+  if (name) {
+    console.log(kleur.dim(`  ${t('ios.hints.manual')}:`));
+    console.log(kleur.dim(`     cd ${projectDir}`));
+    console.log(kleur.dim('     flutter clean && flutter pub get'));
+    console.log(kleur.dim('     rm -rf ~/Library/Developer/Xcode/DerivedData/Runner-*'));
+    console.log(kleur.dim('     cd ios && pod install\n'));
+  }
+}
+
+async function runIosClean(projectDir, t) {
+  const steps = [
+    { label: t('ios.clean.step.flutterClean'), cmd: 'flutter clean' },
+    { label: t('ios.clean.step.derivedData'), cmd: 'rm -rf "$HOME/Library/Developer/Xcode/DerivedData/Runner-"*' },
+    { label: t('ios.clean.step.buildDir'), cmd: 'rm -rf build ios/build' },
+    { label: t('ios.clean.step.pubGet'), cmd: 'flutter pub get' },
+    { label: t('ios.clean.step.pods'), cmd: 'cd ios && pod install' },
+  ];
+
+  for (const step of steps) {
+    console.log(kleur.dim(`  ${step.label}…`));
+    await execAsync(step.cmd, { cwd: projectDir, maxBuffer: 50 * 1024 * 1024, shell: '/bin/bash' });
+  }
+}
+
+async function runReleaseScript(projectDir, args, t) {
+  const scriptPath = path.join(projectDir, RELEASE_SCRIPT);
+  if (!(await fs.pathExists(scriptPath))) {
+    throw new Error(t('ios.error.noScript'));
+  }
+  const cmd = `bash "${scriptPath}" ${args.join(' ')}`.trim();
+  try {
+    await execAsync(cmd, { cwd: projectDir, maxBuffer: 50 * 1024 * 1024 });
+  } catch (err) {
+    const output = [err.stdout, err.stderr, err.message].filter(Boolean).join('\n');
+    const error = new Error(output || err.message);
+    error.buildOutput = output;
+    throw error;
+  }
+}
+
+module.exports = {
+  APPLE_ENV_REL,
+  APPLE_ENV_EXAMPLE,
+  RELEASE_SCRIPT,
+  URL_APP_STORE_CONNECT_APPS,
+  URL_APP_STORE_CONNECT_API,
+  bumpPubspecVersion,
+  isKasyFlutterProject,
+  readBundleId,
+  applePrivateKeyPath,
+  loadAppleEnv,
+  validateAppleSetup,
+  writeAppleEnv,
+  installPrivateKey,
+  openUrl,
+  iosReleaseDocPath,
+  runReleaseScript,
+  checkIosSigning,
+  MIN_DISK_GB_FOR_IOS_BUILD,
+  getFreeDiskGb,
+  checkDiskSpaceForIosBuild,
+  isXcodeCacheBuildError,
+  printBuildFailureHints,
+  runIosClean,
+};

package/lib/utils/checks.js

@@ -0,0 +1,319 @@
+const { exec } = require('node:child_process');
+const { promisify } = require('node:util');
+const readline = require('node:readline');
+const kleur = require('kleur');
+const oraPackage = require('ora');
+const { createTranslator, detectDefaultLanguage } = require('./i18n');
+
+const execAsync = promisify(exec);
+const ora = oraPackage.default || oraPackage;
+
+// Timeout para verificar se uma ferramenta está instalada (15 s é mais que suficiente)
+const TOOL_CHECK_TIMEOUT = 15_000;
+// Timeout para instalação automática de ferramentas (5 min)
+const INSTALL_TIMEOUT = 300_000;
+
+// Minimum supported versions for Kasy projects
+const MIN_NODE_VERSION = '18.0.0';
+const MIN_FLUTTER_VERSION = '3.24.0';
+const MIN_DART_VERSION = '3.5.0';
+
+/**
+ * Compare two semver strings. Returns true if actual >= required.
+ */
+function meetsMinVersion(actual, required) {
+  if (!actual || !required) return true;
+  const parse = (v) => v.replace(/[^0-9.]/g, '').split('.').map(Number);
+  const [aMaj, aMin, aPat = 0] = parse(actual);
+  const [rMaj, rMin, rPat = 0] = parse(required);
+  if (aMaj !== rMaj) return aMaj > rMaj;
+  if (aMin !== rMin) return aMin > rMin;
+  return aPat >= rPat;
+}
+
+const BASE_CHECKS = [
+  {
+    name: 'Node.js',
+    command: 'node --version',
+    required: true,
+    minVersion: MIN_NODE_VERSION,
+  },
+  {
+    name: 'Flutter SDK',
+    command: 'flutter --version',
+    required: false,
+    warnMessageKey: 'checks.flutter.warn',
+    minVersion: MIN_FLUTTER_VERSION,
+  },
+  {
+    name: 'Dart SDK',
+    command: 'dart --version',
+    required: false,
+    minVersion: MIN_DART_VERSION,
+  }
+];
+
+const PLATFORM_CHECKS = {
+  darwin: [
+    {
+      name: 'Ruby',
+      command: 'ruby -v',
+      required: false
+    },
+    {
+      name: 'CocoaPods',
+      command: 'pod --version',
+      required: false
+    }
+  ],
+  win32: [],
+  linux: []
+};
+
+function getGcloudInstallHint() {
+  switch (process.platform) {
+    case 'darwin':
+      return 'brew install --cask google-cloud-sdk';
+    case 'linux':
+      return 'curl https://sdk.cloud.google.com | bash && source ~/.bashrc';
+    case 'win32':
+      return 'winget install Google.CloudSDK\n    ou baixe o instalador: https://cloud.google.com/sdk/docs/install-sdk#windows';
+    default:
+      return 'https://cloud.google.com/sdk/docs/install';
+  }
+}
+
+/** Firebase CLI + FlutterFire — required for push notifications (FCM) on all backends */
+const FIREBASE_CHECKS = [
+  {
+    name: 'Firebase CLI',
+    command: 'firebase --version',
+    required: true,
+    tryInstall: 'npm install -g firebase-tools',
+    tryInstallMessageKey: 'setup.firebase.installing',
+  },
+  {
+    name: 'FlutterFire CLI',
+    command: 'flutterfire --version',
+    required: true,
+    tryInstall: 'dart pub global activate flutterfire_cli',
+    retryCommand: `${process.env.HOME}/.pub-cache/bin/flutterfire --version`,
+    tryInstallMessageKey: 'setup.flutterfire.installing',
+  },
+  {
+    name: 'gcloud CLI (create-from-scratch)',
+    command: 'gcloud --version',
+    required: false,
+    failHint: getGcloudInstallHint(),
+    waitPrompt: 'Após instalar o gcloud, pressione Enter para verificar novamente...',
+  },
+  {
+    name: 'gcloud auth (create-from-scratch)',
+    command: 'gcloud auth print-access-token',
+    required: false,
+    showVersion: false,
+    failHint: 'gcloud auth login',
+    waitPrompt: 'Após fazer login com gcloud auth login, pressione Enter para verificar...',
+  },
+];
+
+const BACKEND_CHECKS = {
+  firebase: FIREBASE_CHECKS,
+  supabase: [
+    ...FIREBASE_CHECKS,
+    {
+      name: 'Supabase CLI',
+      command: 'supabase --version',
+      required: true,
+      tryInstall: 'npm install -g supabase',
+      tryInstallMessageKey: 'setup.supabase.installing',
+    },
+  ],
+  restApi: FIREBASE_CHECKS
+};
+
+function getBaseChecks() {
+  return [...BASE_CHECKS];
+}
+
+function getPlatformChecks() {
+  return [...(PLATFORM_CHECKS[process.platform] || [])];
+}
+
+function getBackendChecks(backend) {
+  return [...(BACKEND_CHECKS[backend] || [])];
+}
+
+function extractVersion(stdout, checkName) {
+  const raw = (stdout || '').trim();
+  if (!raw) return null;
+  if (checkName === 'Node.js') {
+    const m = raw.match(/v?([\d.]+)/);
+    return m ? `v${m[1]}` : raw.slice(0, 20);
+  }
+  if (checkName === 'Flutter SDK') {
+    const m = raw.match(/Flutter\s+([\d.]+)/);
+    return m ? m[1] : raw.split('\n')[0]?.slice(0, 30) || null;
+  }
+  if (checkName === 'Dart SDK') {
+    const m = raw.match(/version:\s*([\d.]+)/);
+    return m ? m[1] : raw.split('\n')[0]?.slice(0, 25) || null;
+  }
+  const m = raw.match(/[\d.]+/);
+  return m ? m[0] : raw.slice(0, 20);
+}
+
+/**
+ * Wait for the user to press Enter in the terminal.
+ * Used to pause the flow so the user can install something or authenticate.
+ */
+function waitForUserInput(prompt) {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    const done = () => { rl.close(); resolve(); };
+    rl.question(`\n  ${kleur.cyan(prompt)}\n  `, done);
+    rl.on('close', resolve);
+    rl.on('error', resolve);
+  });
+}
+
+async function runSingleCheck(check, options = {}) {
+  const showVersion = check.showVersion !== undefined ? check.showVersion : (options.showVersion !== undefined ? options.showVersion : true);
+  const silent = options.silent === true;
+  const t = check.t || createTranslator(check.language || detectDefaultLanguage());
+  const spinner = silent ? null : ora(t('checks.checking', { name: check.name })).start();
+  let autoInstallFailed = false;
+
+  try {
+    const { stdout } = await execAsync(check.command, { encoding: 'utf8', timeout: TOOL_CHECK_TIMEOUT });
+    const version = showVersion ? extractVersion(stdout, check.name) : null;
+    const msg = version
+      ? t('checks.foundWithVersion', { name: check.name, version })
+      : t('checks.found', { name: check.name });
+
+    if (!silent) {
+      // Warn if version is below minimum requirement
+      if (version && check.minVersion && !meetsMinVersion(version, check.minVersion)) {
+        spinner.warn(`${msg} ${kleur.yellow(`(mínimo recomendado: ${check.minVersion})`)}`);
+      } else {
+        spinner.succeed(msg);
+      }
+    }
+    return { ...check, ok: true, version: version || null };
+  } catch {
+    if (check.tryInstall) {
+      if (!silent) spinner.text = t(check.tryInstallMessageKey || 'setup.flutterfire.installing');
+      try {
+        await execAsync(check.tryInstall, { encoding: 'utf8', timeout: INSTALL_TIMEOUT });
+        const { stdout: retryOut } = await execAsync(check.retryCommand || check.command, { encoding: 'utf8', timeout: TOOL_CHECK_TIMEOUT });
+        const version = showVersion ? extractVersion(retryOut, check.name) : null;
+        const msg = version
+          ? t('checks.foundWithVersion', { name: check.name, version: version || 'installed' })
+          : t('checks.found', { name: check.name });
+        if (!silent) spinner.succeed(msg);
+        return { ...check, ok: true, version: version || null };
+      } catch {
+        autoInstallFailed = true;
+      }
+    }
+
+    // Guided interactive prompt: show instructions and wait for the user to act.
+    if (check.waitPrompt && !silent) {
+      spinner.stop();
+      if (check.failHint) {
+        console.log(kleur.yellow(`\n  ⚠  ${check.name} não encontrado.\n`));
+        console.log(kleur.bold('  Execute:\n'));
+        console.log(kleur.cyan(`    ${check.failHint}\n`));
+      }
+      await waitForUserInput(check.waitPrompt);
+      try {
+        const { stdout: retryOut } = await execAsync(check.command, { encoding: 'utf8', timeout: TOOL_CHECK_TIMEOUT });
+        const version = showVersion ? extractVersion(retryOut, check.name) : null;
+        const msg = version
+          ? t('checks.foundWithVersion', { name: check.name, version })
+          : t('checks.found', { name: check.name });
+        spinner.succeed(msg);
+        return { ...check, ok: true, version: version || null };
+      } catch {
+        // Still failing — fall through to report
+      }
+    }
+
+    if (!silent) {
+      if (check.required) {
+        const detail = autoInstallFailed ? ` — ${t('checks.install.failed')}` : '';
+        spinner.fail(t('checks.missing', { name: check.name }) + detail);
+      } else {
+        const hint = !check.waitPrompt && check.failHint ? `\n    ${kleur.dim(`→ ${check.failHint}`)}` : '';
+        if (check.warnMessage) {
+          spinner.warn(check.warnMessage + hint);
+        } else if (check.warnMessageKey) {
+          spinner.warn(t(check.warnMessageKey) + hint);
+        } else {
+          spinner.warn(t('checks.notFound', { name: check.name }) + hint);
+        }
+      }
+    }
+
+    return { ...check, ok: false, autoInstallFailed };
+  }
+}
+
+async function runChecks(checks, title, options = {}) {
+  const t = options.t || createTranslator(options.language || detectDefaultLanguage());
+  const { showVersion = true, compact = false } = options;
+
+  if (!compact) {
+    console.log(kleur.bold(`\n${title}`));
+    const results = [];
+    for (const check of checks) {
+      const result = await runSingleCheck({ ...check, t }, { showVersion });
+      results.push(result);
+    }
+    return results;
+  }
+
+  // Compact mode: single spinner, show failures only
+  const { spinnerLabel = title, doneLabel = title } = options;
+  process.stdout.write(`  ${kleur.dim(spinnerLabel + '...')}\n`);
+
+  const results = [];
+  for (const check of checks) {
+    results.push(await runSingleCheck({ ...check, t }, { showVersion, silent: true }));
+  }
+
+  const failures = results.filter((r) => !r.ok);
+
+  if (failures.length === 0) {
+    console.log(kleur.green(`  ✔ ${doneLabel}`));
+    return results;
+  }
+
+  for (const result of failures) {
+    const hint = result.failHint ? `\n    ${kleur.dim(`→ ${result.failHint}`)}` : '';
+    if (result.required) {
+      const detail = result.autoInstallFailed ? ` — ${t('checks.install.failed')}` : '';
+      console.log(kleur.red(`  ✖ ${t('checks.missing', { name: result.name })}${detail}${hint}`));
+    } else if (result.warnMessage) {
+      console.log(kleur.yellow(`  ⚠ ${result.warnMessage}${hint}`));
+    } else if (result.warnMessageKey) {
+      console.log(kleur.yellow(`  ⚠ ${t(result.warnMessageKey)}${hint}`));
+    } else {
+      console.log(kleur.yellow(`  ⚠ ${t('checks.notFound', { name: result.name })}${hint}`));
+    }
+  }
+
+  return results;
+}
+
+function hasRequiredFailures(results) {
+  return results.some((result) => result.required && !result.ok);
+}
+
+module.exports = {
+  getBaseChecks,
+  getPlatformChecks,
+  getBackendChecks,
+  runChecks,
+  hasRequiredFailures,
+};