kasy-cli 1.14.0 → 1.15.0

package/bin/kasy.js

@@ -41,6 +41,8 @@ const { ensureLicenseKey, shouldRequireLicenseForArgv } = require('../lib/utils/
 const { checkForUpdates } = require('../lib/utils/updates');
 const { printCompactHeader } = require('../lib/utils/brand');
 const ui = require('../lib/utils/ui');
+const { stripVerboseFlag, isVerbose, printVerboseError } = require('../lib/utils/debug');
+const { formatError } = require('../lib/utils/friendly-error');
 
 function createLocalizedHelpConfig(t) {
   return {
@@ -360,6 +362,7 @@ function buildProgram(language) {
       .option('--web', 'Show web reset instructions only')
       .option('-d, --device <id>', 'Reset specific device ID')
       .option('--no-reinstall', 'Only uninstall, skip reinstall')
+      .option('--no-clear-launcher', 'Android only: skip clearing the launcher cache (widget previews may stay gray)')
       .description(t('cli.command.reset.description'))
       .action(async (directory, options) => {
         await runReset(directory, { language, ...options });
@@ -718,18 +721,28 @@ async function resolveLanguage(argv) {
   return detectDefaultLanguage();
 }
 
+// Track the resolved language so the global catch can localize hints.
+let activeLanguage = null;
+
 async function main() {
-  const argv = process.argv.slice(2);
-  const language = await resolveLanguage(argv);
+  // Strip --verbose before commander sees it — that flag is handled out-of-band
+  // by lib/utils/debug.js (reads process.argv directly).
+  const argv = stripVerboseFlag(process.argv.slice(2));
+  activeLanguage = await resolveLanguage(argv);
   if (shouldRequireLicenseForArgv(argv)) {
-    await ensureLicenseKey({ language, argv });
+    await ensureLicenseKey({ language: activeLanguage, argv });
   }
   await checkForUpdates();
-  const program = buildProgram(language);
+  const program = buildProgram(activeLanguage);
   await program.parseAsync([process.argv[0], process.argv[1], ...argv]);
 }
 
 main().catch((error) => {
-  console.error(kleur.red(`\n✗ ${error.message}`));
+  const t = activeLanguage ? createTranslator(activeLanguage) : null;
+  console.error(formatError(error, t));
+  printVerboseError(error);
+  if (!isVerbose()) {
+    console.error(kleur.dim('  Run again with --verbose (or set KASY_DEBUG=1) for full output.'));
+  }
   process.exitCode = 1;
 });

package/lib/commands/ios.js

@@ -19,7 +19,9 @@ const {
   checkIosSigning,
   checkDiskSpaceForIosBuild,
   isXcodeCacheBuildError,
+  isPodNetworkError,
   printBuildFailureHints,
+  printPodNetworkHints,
   runIosClean,
   MIN_DISK_GB_FOR_IOS_BUILD,
   URL_APP_STORE_CONNECT_APPS,
@@ -180,9 +182,13 @@ async function runBuildOrRelease(directory, options = {}, mode) {
     ui.outro(mode === 'build' ? t('ios.build.success') : t('ios.release.success'));
   } catch (err) {
     const output = err.buildOutput || err.message;
-    ui.log.error(output.slice(-4000));
-    if (isXcodeCacheBuildError(output)) {
+    if (isPodNetworkError(output)) {
+      printPodNetworkHints(t);
+    } else if (isXcodeCacheBuildError(output)) {
+      ui.log.error(output.slice(-4000));
       printBuildFailureHints(t, projectDir);
+    } else {
+      ui.log.error(output.slice(-4000));
     }
     process.exitCode = 1;
   }

package/lib/commands/reset.js

@@ -123,9 +123,13 @@ function resetIosDevice(device, bundleId, t) {
 }
 
 function resetAndroid(device, packageName, t) {
+  // Force-stop first — `adb uninstall` returns DELETE_FAILED_INTERNAL_ERROR
+  // when the app has lingering processes or pending PM state (common on
+  // Pixel emulators after a crash or hot-restart).
+  runCmd('adb', ['-s', device.id, 'shell', 'am', 'force-stop', packageName]);
+
   ui.log.message(kleur.dim(`adb -s ${device.id} uninstall ${packageName}`));
   const res = runCmd('adb', ['-s', device.id, 'uninstall', packageName]);
-  // adb prints "Success" or "Failure [DELETE_FAILED_INTERNAL_ERROR]" / "not installed"
   const out = `${res.stdout}\n${res.stderr}`.toLowerCase();
   if (out.includes('success')) {
     ui.log.success(t('reset.success.uninstalled'));
@@ -135,10 +139,82 @@ function resetAndroid(device, packageName, t) {
     ui.log.message(kleur.dim(`– ${t('reset.info.notInstalled')}`));
     return true;
   }
-  ui.log.warn(res.stdout || res.stderr || t('reset.warn.androidUninstallFailed'));
+
+  // Fallback: `pm uninstall --user 0` bypasses several PM states that
+  // `adb uninstall` can't (DELETE_FAILED_INTERNAL_ERROR, multi-user, etc).
+  ui.log.message(
+    kleur.dim(`adb -s ${device.id} shell pm uninstall --user 0 ${packageName}`)
+  );
+  const fallback = runCmd('adb', [
+    '-s', device.id, 'shell', 'pm', 'uninstall', '--user', '0', packageName,
+  ]);
+  const fallbackOut = `${fallback.stdout}\n${fallback.stderr}`.toLowerCase();
+  if (fallbackOut.includes('success')) {
+    ui.log.success(t('reset.success.uninstalled'));
+    return true;
+  }
+  if (fallbackOut.includes('not installed') || fallbackOut.includes('unknown package')) {
+    ui.log.message(kleur.dim(`– ${t('reset.info.notInstalled')}`));
+    return true;
+  }
+
+  ui.log.warn(
+    res.stdout || res.stderr || fallback.stdout || fallback.stderr ||
+    t('reset.warn.androidUninstallFailed')
+  );
   return false;
 }
 
+/// Reads the package name of the device's default home launcher.
+/// Used so we can clear ITS cache (not the app's) — the launcher caches
+/// widget previews aggressively and a gray preview persists across
+/// uninstalls of the app itself.
+function detectAndroidLauncher(device) {
+  const res = runCmd('adb', [
+    '-s', device.id,
+    'shell', 'cmd', 'package', 'resolve-activity',
+    '--brief',
+    '-c', 'android.intent.category.HOME',
+    '-a', 'android.intent.action.MAIN',
+  ]);
+  if (res.code !== 0) return null;
+  // Output ends with a line like:
+  //   com.google.android.apps.nexuslauncher/.NexusLauncherActivity
+  const lines = res.stdout.split('\n').map((l) => l.trim()).filter(Boolean);
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const line = lines[i];
+    if (line.includes('/') && !line.startsWith('priority=')) {
+      return line.split('/')[0];
+    }
+  }
+  return null;
+}
+
+/// Clears the launcher's preview cache and force-stops it.
+/// pm clear-cache removes cached widget previews from disk; force-stop
+/// kicks any in-memory composition. Neither resets the user's home
+/// screen — that would be `pm clear` (which we intentionally do NOT do).
+function clearAndroidLauncherCache(device, launcherPkg, t) {
+  ui.log.message(
+    kleur.dim(`adb -s ${device.id} shell pm clear-cache ${launcherPkg}`)
+  );
+  runCmd('adb', [
+    '-s', device.id, 'shell', 'pm', 'clear-cache', launcherPkg,
+  ]);
+  ui.log.message(
+    kleur.dim(`adb -s ${device.id} shell am force-stop ${launcherPkg}`)
+  );
+  const stop = runCmd('adb', [
+    '-s', device.id, 'shell', 'am', 'force-stop', launcherPkg,
+  ]);
+  if (stop.code !== 0) {
+    ui.log.warn(t('reset.warn.launcherCacheFailed'));
+    return false;
+  }
+  ui.log.success(t('reset.success.launcherCleared', { pkg: launcherPkg }));
+  return true;
+}
+
 function noticeIosPhysical(t) {
   ui.log.warn(t('reset.warn.iosDeviceManual'));
 }
@@ -266,6 +342,28 @@ async function runReset(directory, options = {}) {
     return;
   }
 
+  // On Android, also clear the launcher cache so widget previews refresh.
+  // Without this, the gallery keeps showing the gray placeholder even after
+  // the app is reinstalled (the launcher caches preview drawables by
+  // package + component name, which don't change between installs).
+  if (
+    (kind === 'android-emulator' || kind === 'android-device') &&
+    options.clearLauncher !== false
+  ) {
+    const launcherPkg = detectAndroidLauncher(target);
+    if (launcherPkg) {
+      const proceedClear = await ui.confirm({
+        message: t('reset.prompt.clearLauncherCache', { pkg: launcherPkg }),
+        initialValue: true,
+      });
+      if (proceedClear) {
+        clearAndroidLauncherCache(target, launcherPkg, t);
+      }
+    } else {
+      ui.log.message(kleur.dim(t('reset.warn.launcherNotDetected')));
+    }
+  }
+
   if (options.reinstall === false) {
     ui.outro(t('reset.outro.uninstalledOnly'));
     return;

package/lib/commands/splash.js

@@ -7,12 +7,15 @@ const kleur = require('kleur');
 const ui = require('../utils/ui');
 const { printCompactHeader } = require('../utils/brand');
 const { createTranslator, detectDefaultLanguage } = require('../utils/i18n');
+const { writeAndroid12Variant } = require('../utils/png-padding');
 
 const execAsync = promisify(exec);
 
 const ASSETS_DIR = path.join('assets', 'images');
 const LIGHT_NAME = 'splash_logo_light.png';
 const DARK_NAME = 'splash_logo_dark.png';
+const LIGHT_ANDROID12_NAME = 'splash_logo_light_android12.png';
+const DARK_ANDROID12_NAME = 'splash_logo_dark_android12.png';
 
 const PNG_SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
 
@@ -159,6 +162,8 @@ async function runSplash(projectDir, options = {}) {
 
   const destLight = path.join(projectDir, ASSETS_DIR, LIGHT_NAME);
   const destDark = path.join(projectDir, ASSETS_DIR, DARK_NAME);
+  const destLightA12 = path.join(projectDir, ASSETS_DIR, LIGHT_ANDROID12_NAME);
+  const destDarkA12 = path.join(projectDir, ASSETS_DIR, DARK_ANDROID12_NAME);
 
   const copySpinner = ui.spinner();
   copySpinner.start(t('splash.copying'));
@@ -166,6 +171,12 @@ async function runSplash(projectDir, options = {}) {
   await fs.copy(darkPath, destDark, { overwrite: true });
   copySpinner.stop(t('splash.copied'));
 
+  const a12Spinner = ui.spinner();
+  a12Spinner.start(t('splash.android12Generating'));
+  await writeAndroid12Variant(destLight, destLightA12);
+  await writeAndroid12Variant(destDark, destDarkA12);
+  a12Spinner.stop(t('splash.android12Generated'));
+
   if (options.skipGenerate) {
     ui.note(t('splash.skipGenerate.hint'), t('splash.skipGenerate.title'));
     ui.outro(t('splash.done'));

package/lib/scaffold/backends/api/pubspec.yaml.tpl

@@ -114,5 +114,5 @@ flutter_native_splash:
   android_12:
     color: "#FFFFFF"
     color_dark: "#000000"
-    image: assets/images/splash_logo_light.png
-    image_dark: assets/images/splash_logo_dark.png
+    image: assets/images/splash_logo_light_android12.png
+    image_dark: assets/images/splash_logo_dark_android12.png

package/lib/scaffold/backends/supabase/pubspec.yaml.tpl

@@ -116,5 +116,5 @@ flutter_native_splash:
   android_12:
     color: "#FFFFFF"
     color_dark: "#000000"
-    image: assets/images/splash_logo_light.png
-    image_dark: assets/images/splash_logo_dark.png
+    image: assets/images/splash_logo_light_android12.png
+    image_dark: assets/images/splash_logo_dark_android12.png

package/lib/utils/apple-release.js

@@ -185,6 +185,18 @@ const XCODE_CACHE_ERROR_PATTERNS = [
   /clang: error: no such file or directory:.*\.swiftmodule/i,
 ];
 
+const POD_NETWORK_ERROR_PATTERNS = [
+  /curl:\s*\(6\)/i,
+  /curl:\s*\(7\)/i,
+  /curl:\s*\(28\)/i,
+  /curl:\s*\(35\)/i,
+  /curl:\s*\(56\)/i,
+  /Connection reset by peer/i,
+  /Could not resolve host/i,
+  /Network is unreachable/i,
+  /Operation timed out/i,
+];
+
 async function getFreeDiskGb(checkPath) {
   if (process.platform !== 'darwin' && process.platform !== 'linux') {
     return null;
@@ -216,6 +228,11 @@ function isXcodeCacheBuildError(output) {
   return XCODE_CACHE_ERROR_PATTERNS.some((re) => re.test(text));
 }
 
+function isPodNetworkError(output) {
+  const text = String(output || '');
+  return POD_NETWORK_ERROR_PATTERNS.some((re) => re.test(text));
+}
+
 function printBuildFailureHints(t, projectDir) {
   const name = path.basename(projectDir);
   const cleanArg = projectDir !== process.cwd() ? ` ${projectDir}` : '';
@@ -235,6 +252,17 @@ function printBuildFailureHints(t, projectDir) {
   ui.note(lines.join('\n'), t('ios.hints.title'));
 }
 
+function printPodNetworkHints(t) {
+  const lines = [
+    t('ios.hints.network.body'),
+    '',
+    `1. ${t('ios.hints.network.step1')}`,
+    `2. ${t('ios.hints.network.step2')}: ${kleur.cyan('kasy ios')}`,
+    `3. ${t('ios.hints.network.step3')}: ${kleur.cyan('kasy ios clean')}`,
+  ];
+  ui.note(lines.join('\n'), t('ios.hints.network.title'));
+}
+
 async function runIosClean(projectDir, t) {
   const steps = [
     { label: t('ios.clean.step.flutterClean'), cmd: 'flutter clean' },
@@ -349,6 +377,8 @@ module.exports = {
   getFreeDiskGb,
   checkDiskSpaceForIosBuild,
   isXcodeCacheBuildError,
+  isPodNetworkError,
   printBuildFailureHints,
+  printPodNetworkHints,
   runIosClean,
 };

package/lib/utils/checks.js

@@ -90,7 +90,7 @@ const FIREBASE_CHECKS = [
     command: 'gcloud --version',
     required: false,
     failHint: getGcloudInstallHint(),
-    waitPrompt: 'Após instalar o gcloud, pressione Enter para verificar novamente...',
+    waitPromptKey: 'checks.waitPrompt.gcloud.install',
   },
   {
     name: 'gcloud auth (create-from-scratch)',
@@ -98,7 +98,7 @@ const FIREBASE_CHECKS = [
     required: false,
     showVersion: false,
     failHint: 'gcloud auth login',
-    waitPrompt: 'Após fazer login com gcloud auth login, pressione Enter para verificar...',
+    waitPromptKey: 'checks.waitPrompt.gcloud.auth',
   },
 ];
 
@@ -183,6 +183,34 @@ async function runSingleCheck(check, options = {}) {
   }
 }
 
+/**
+ * Retry a check after the user installs/auths a missing tool. Used when the
+ * check definition has `waitPrompt` — we offer the user to run the install
+ * step, then re-check on Enter. Returns true if the recheck succeeded.
+ */
+async function retryCheckInteractively(check, t) {
+  ui.log.warn(`${check.name} ${t('checks.notFound.short') || 'not found'}`);
+  if (check.failHint) {
+    ui.log.message(`${t('checks.runHint') || 'Run'}: ${kleur.cyan(check.failHint)}`);
+  }
+  const proceed = await ui.confirm({
+    message: check.waitPrompt,
+    initialValue: true,
+  });
+  if (!proceed) return false;
+  try {
+    const { stdout } = await execAsync(check.command, { encoding: 'utf8', timeout: TOOL_CHECK_TIMEOUT });
+    const version = extractVersion(stdout, check.name);
+    ui.log.success(version
+      ? `${check.name} — ${version}`
+      : check.name);
+    return true;
+  } catch {
+    ui.log.error(`${check.name} ${t('checks.stillMissing') || 'still missing'}`);
+    return false;
+  }
+}
+
 async function runChecks(checks, title, options = {}) {
   const t = options.t || createTranslator(options.language || detectDefaultLanguage());
   const { showVersion = true } = options;
@@ -215,6 +243,17 @@ async function runChecks(checks, title, options = {}) {
   }
 
   for (const result of failures) {
+    // Interactive recovery for checks with a waitPrompt (e.g. gcloud install).
+    // Lets the user fix the env without restarting the command.
+    const waitPromptText = result.waitPromptKey ? t(result.waitPromptKey) : result.waitPrompt;
+    if (waitPromptText) {
+      const recovered = await retryCheckInteractively({ ...result, waitPrompt: waitPromptText }, t);
+      if (recovered) {
+        const idx = results.indexOf(result);
+        if (idx >= 0) results[idx] = { ...result, ok: true };
+      }
+      continue;
+    }
     const hint = result.failHint ? `\n${kleur.dim(`→ ${result.failHint}`)}` : '';
     if (result.required) {
       const detail = result.autoInstallFailed ? ` — ${t('checks.install.failed')}` : '';

package/lib/utils/debug.js

@@ -0,0 +1,75 @@
+/**
+ * Debug / verbose helpers.
+ *
+ * Enabled by either:
+ *   - `--verbose` flag (set globally in bin/kasy.js via process.argv parsing)
+ *   - `KASY_DEBUG=1` environment variable
+ *
+ * Use `debugLog(...)` for diagnostic output that should only show when the
+ * user opts in. Use `attachDebugToError(err, context)` before throwing/rejecting
+ * to attach extra info (stdout/stderr/command) that surfaces in --verbose mode.
+ */
+
+'use strict';
+
+const kleur = require('kleur');
+
+function isVerbose() {
+  if (process.env.KASY_DEBUG === '1' || process.env.KASY_DEBUG === 'true') return true;
+  return process.argv.includes('--verbose');
+}
+
+/**
+ * Strip --verbose from argv before commander parses it, since commander does
+ * not know about this flag. Returns a new argv with --verbose removed.
+ */
+function stripVerboseFlag(argv) {
+  return argv.filter((arg) => arg !== '--verbose');
+}
+
+function debugLog(...args) {
+  if (!isVerbose()) return;
+  console.error(kleur.dim(`[debug] ${args.map(String).join(' ')}`));
+}
+
+/**
+ * Attach raw command output to an error so --verbose mode can surface it.
+ * The original error message stays clean for end users.
+ */
+function attachDebugToError(err, { command, stdout, stderr, cwd } = {}) {
+  if (!err || typeof err !== 'object') return err;
+  err.kasyDebug = {
+    command: command || null,
+    stdout: stdout != null ? String(stdout) : null,
+    stderr: stderr != null ? String(stderr) : null,
+    cwd: cwd || null,
+  };
+  return err;
+}
+
+/**
+ * Print verbose context for an error if debug is on. Called from the global
+ * error handler in bin/kasy.js.
+ */
+function printVerboseError(err) {
+  if (!isVerbose() || !err) return;
+  console.error('');
+  console.error(kleur.dim('─── verbose error context ───'));
+  if (err.stack) console.error(kleur.dim(err.stack));
+  if (err.kasyDebug) {
+    const d = err.kasyDebug;
+    if (d.command) console.error(kleur.dim(`command: ${d.command}`));
+    if (d.cwd)     console.error(kleur.dim(`cwd:     ${d.cwd}`));
+    if (d.stdout)  console.error(kleur.dim('stdout:\n' + d.stdout));
+    if (d.stderr)  console.error(kleur.dim('stderr:\n' + d.stderr));
+  }
+  console.error(kleur.dim('─────────────────────────────'));
+}
+
+module.exports = {
+  isVerbose,
+  stripVerboseFlag,
+  debugLog,
+  attachDebugToError,
+  printVerboseError,
+};

package/lib/utils/friendly-error.js

@@ -0,0 +1,91 @@
+/**
+ * Map common errors to actionable hints for non-technical users.
+ *
+ * Pattern: takes an Error and the current translator (t), returns a string
+ * with both the original message and a one-line "→ try this" suggestion.
+ * Falls back to just the message when no pattern matches.
+ *
+ * Used by bin/kasy.js global error handler.
+ */
+
+'use strict';
+
+const kleur = require('kleur');
+
+// Each rule: { match: RegExp | (err) => boolean, hintKey: i18n key, hintFallback: english fallback }
+// Order matters — more specific rules first.
+const RULES = [
+  {
+    match: /pubspec\.yaml/i,
+    hintKey: 'error.hint.notFlutterProject',
+    hintFallback: 'You\'re not inside a Flutter project. Try `kasy new` to create one, or cd into an existing one.',
+  },
+  {
+    match: /flutter[^a-z]+not found|ENOENT.*flutter/i,
+    hintKey: 'error.hint.flutterMissing',
+    hintFallback: 'Flutter is not installed or not on your PATH. Run `kasy doctor` to diagnose.',
+  },
+  {
+    match: /EACCES|permission denied/i,
+    hintKey: 'error.hint.permission',
+    hintFallback: 'A file or folder is read-only. Check the parent directory permissions or try again from your home folder.',
+  },
+  {
+    match: /ENOSPC|No space left/i,
+    hintKey: 'error.hint.noSpace',
+    hintFallback: 'Disk is full. Free up space (Flutter/Xcode builds need 5-15 GB) and try again.',
+  },
+  {
+    match: /ECONNREFUSED|ENOTFOUND|getaddrinfo|network/i,
+    hintKey: 'error.hint.network',
+    hintFallback: 'Network problem — check your internet connection and try again.',
+  },
+  {
+    match: /firebase.*not.*log(ged|in)|firebase login/i,
+    hintKey: 'error.hint.firebaseLogin',
+    hintFallback: 'You are not logged into Firebase. Run: firebase login',
+  },
+  {
+    match: /supabase.*not.*log(ged|in)|supabase login/i,
+    hintKey: 'error.hint.supabaseLogin',
+    hintFallback: 'You are not logged into Supabase. Run: supabase login',
+  },
+  {
+    match: /gcloud.*not authenticated|gcloud auth/i,
+    hintKey: 'error.hint.gcloudAuth',
+    hintFallback: 'You need to authenticate with gcloud. Run: gcloud auth login',
+  },
+  {
+    match: /flutter run exited|flutter exited/i,
+    hintKey: 'error.hint.flutterRunFailed',
+    hintFallback: 'Flutter could not run the app. Run again with --verbose to see the full Flutter output.',
+  },
+];
+
+function findHint(message) {
+  const text = String(message || '');
+  for (const rule of RULES) {
+    const isMatch = typeof rule.match === 'function' ? rule.match({ message: text }) : rule.match.test(text);
+    if (isMatch) return rule;
+  }
+  return null;
+}
+
+/**
+ * Format an error for terminal output. Returns a string with the red ✗ line
+ * plus, when we recognize the pattern, a dim hint line beneath it.
+ */
+function formatError(err, t) {
+  const message = err && err.message ? err.message : String(err);
+  const lines = [kleur.red(`\n✗ ${message}`)];
+  const hint = findHint(message);
+  if (hint) {
+    const text = t ? t(hint.hintKey) : null;
+    // Translator returns the key itself when missing — fall back to English.
+    const hintText = (text && text !== hint.hintKey) ? text : hint.hintFallback;
+    lines.push(kleur.dim(`  → ${hintText}`));
+  }
+  return lines.join('\n');
+}
+
+module.exports = { formatError, findHint };