kasy-cli 1.14.0 → 1.16.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/icon.js

@@ -7,11 +7,17 @@ const ui = require('../utils/ui');
 const { printCompactHeader } = require('../utils/brand');
 const { createTranslator, detectDefaultLanguage } = require('../utils/i18n');
 const { inspectPng } = require('./splash');
+const {
+  writeAndroidAdaptiveBackground,
+  writeTransparentSquare,
+} = require('../utils/png-padding');
 
 const execAsync = promisify(exec);
 
 const ASSETS_DIR = path.join('assets', 'images');
 const ICON_NAME = 'icon.png';
+const ANDROID_BG_NAME = 'icon_android.png';
+const ANDROID_FG_EMPTY_NAME = 'icon_foreground_empty.png';
 
 async function assertKasyProject(projectDir, t) {
   const kitSetupPath = path.join(projectDir, 'kit_setup.json');
@@ -85,13 +91,35 @@ async function runIcon(projectDir, options = {}) {
     ui.note(warnings.map((w) => `${kleur.yellow('⚠')} ${w}`).join('\n'), t('icon.warn.title'));
   }
 
-  const dest = path.join(projectDir, ASSETS_DIR, ICON_NAME);
+  const assetsDir = path.join(projectDir, ASSETS_DIR);
+  const dest = path.join(assetsDir, ICON_NAME);
+  const androidBgDest = path.join(assetsDir, ANDROID_BG_NAME);
+  const androidFgEmptyDest = path.join(assetsDir, ANDROID_FG_EMPTY_NAME);
 
   const copySpinner = ui.spinner();
   copySpinner.start(t('icon.copying'));
   await fs.copy(imagePath, dest, { overwrite: true });
   copySpinner.stop(t('icon.copied'));
 
+  const adaptiveSpinner = ui.spinner();
+  adaptiveSpinner.start(t('icon.adaptive.generating'));
+  let adaptiveInfo;
+  try {
+    adaptiveInfo = await writeAndroidAdaptiveBackground(dest, androidBgDest);
+    if (!(await fs.pathExists(androidFgEmptyDest))) {
+      await writeTransparentSquare(androidFgEmptyDest);
+    }
+    adaptiveSpinner.stop(t('icon.adaptive.generated'));
+  } catch (err) {
+    adaptiveSpinner.stop(`⚠ ${t('icon.adaptive.failed')}`);
+    ui.log.message(kleur.dim(err.message || String(err)));
+    process.exit(1);
+  }
+
+  if (!adaptiveInfo.color.sampled) {
+    ui.note(t('icon.adaptive.fallbackColor'), t('icon.adaptive.fallbackTitle'));
+  }
+
   if (options.skipGenerate) {
     ui.note(t('icon.skipGenerate.hint'), t('icon.skipGenerate.title'));
     ui.outro(t('icon.done'));

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/run.js

@@ -1,10 +1,52 @@
 const path = require('node:path');
+const { spawnSync } = require('node:child_process');
 const fs = require('fs-extra');
 const kleur = require('kleur');
+const ui = require('../utils/ui');
 const { createTranslator, detectDefaultLanguage } = require('../utils/i18n');
 const { printCompactHeader } = require('../utils/brand');
 const { spawnFlutterWithSpinner } = require('../utils/flutter-run');
 
+function listFlutterDevices(projectDir) {
+  const res = spawnSync('flutter', ['devices', '--machine'], {
+    cwd: projectDir,
+    encoding: 'utf8',
+  });
+  if (res.status !== 0) return [];
+  try {
+    const parsed = JSON.parse(res.stdout);
+    return Array.isArray(parsed) ? parsed : [];
+  } catch {
+    return [];
+  }
+}
+
+function classifyDevice(device) {
+  const platform = (device.targetPlatform || '').toLowerCase();
+  if (platform === 'ios') return device.emulator ? 'ios-simulator' : 'ios-device';
+  if (platform.startsWith('android')) {
+    return device.emulator ? 'android-emulator' : 'android-device';
+  }
+  if (platform.startsWith('web')) return 'web';
+  if (platform.startsWith('darwin')) return 'macos';
+  if (platform.startsWith('linux')) return 'linux';
+  if (platform.startsWith('windows')) return 'windows';
+  return 'unknown';
+}
+
+async function pickDevice(devices, t) {
+  if (devices.length === 0) return null;
+  if (devices.length === 1) return devices[0];
+  const choice = await ui.select({
+    message: t('run.prompt.pickDevice'),
+    options: devices.map((d) => ({
+      value: d.id,
+      label: `${d.name} ${kleur.dim(`(${classifyDevice(d)})`)}`,
+    })),
+  });
+  return devices.find((d) => d.id === choice) || null;
+}
+
 /**
  * Read dart-define args from .vscode/launch.json.
  * Returns the args array from the matching config (dev or prod).
@@ -35,8 +77,11 @@ async function runRun(directory, options = {}) {
     throw new Error(t('run.error.notFlutterProject'));
   }
 
-  // Resolve device flag
+  // Resolve device flag. If none of the platform shortcuts or -d is set,
+  // ask the user when more than one device is available — `flutter run`
+  // bails out with "More than one device connected" otherwise.
   const deviceArgs = [];
+  let resolvedDeviceLabel = null;
   if (options.web) {
     deviceArgs.push('-d', 'chrome');
   } else if (options.ios) {
@@ -45,6 +90,20 @@ async function runRun(directory, options = {}) {
     deviceArgs.push('-d', 'android');
   } else if (options.device) {
     deviceArgs.push('-d', options.device);
+  } else {
+    const devices = listFlutterDevices(projectDir);
+    if (devices.length > 1) {
+      printCompactHeader(t);
+      const picked = await pickDevice(devices, t);
+      if (!picked) {
+        console.log(kleur.yellow(`  ⚠  ${t('run.warn.nothingSelected')}`));
+        return;
+      }
+      deviceArgs.push('-d', picked.id);
+      resolvedDeviceLabel = `${picked.name} (${picked.id})`;
+    }
+    // 0 or 1 device → let flutter handle it; it picks the only one or
+    // prints its own "no devices" message.
   }
 
   // Read dart-defines from .vscode/launch.json (skip if --no-defines)
@@ -62,7 +121,7 @@ async function runRun(directory, options = {}) {
     ? 'ios'
     : options.android
     ? 'android'
-    : options.device || null;
+    : options.device || resolvedDeviceLabel || null;
   const summaryParts = [];
   if (envValue) summaryParts.push(`ENV=${envValue}`);
   if (deviceLabel) summaryParts.push(`device: ${deviceLabel}`);

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

@@ -98,6 +98,8 @@ flutter_launcher_icons:
   android: ic_launcher
   ios: true
   remove_alpha_ios: true
+  adaptive_icon_background: assets/images/icon_android.png
+  adaptive_icon_foreground: assets/images/icon_foreground_empty.png
   web:
     generate: true
     image_path: assets/images/favicon.png
@@ -114,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/scaffold/backends/supabase/pubspec.yaml.tpl

@@ -100,6 +100,8 @@ flutter_launcher_icons:
   android: ic_launcher
   ios: true
   remove_alpha_ios: true
+  adaptive_icon_background: assets/images/icon_android.png
+  adaptive_icon_foreground: assets/images/icon_foreground_empty.png
   web:
     generate: true
     image_path: assets/images/favicon.png
@@ -116,5 +118,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,
+};