kasy-cli 1.20.1 → 1.21.0-beta.0

package/lib/commands/docs.js

@@ -1,5 +1,4 @@
 const path = require('node:path');
-const { exec } = require('node:child_process');
 const fs = require('fs-extra');
 const kleur = require('kleur');
 const ui = require('../utils/ui');
@@ -8,15 +7,6 @@ const { createTranslator, detectDefaultLanguage } = require('../utils/i18n');
 
 const DOCS_FILE = path.join(__dirname, '..', '..', 'docs', 'cli-reference.md');
 
-function openInBrowser(url) {
-  const cmd = process.platform === 'darwin'
-    ? `open "${url}"`
-    : process.platform === 'win32'
-      ? `start "" "${url}"`
-      : `xdg-open "${url}"`;
-  exec(cmd);
-}
-
 async function runDocs(options = {}) {
   const t = createTranslator(options.language || detectDefaultLanguage());
 

package/lib/commands/ios.js

@@ -6,6 +6,7 @@ const kleur = require('kleur');
 const ui = require('../utils/ui');
 const { printCompactHeader } = require('../utils/brand');
 const { createTranslator, detectDefaultLanguage } = require('../utils/i18n');
+const { homeDir } = require('../utils/env-tools');
 const {
   isKasyFlutterProject,
   readBundleId,
@@ -73,7 +74,7 @@ async function runConfigure(directory, options = {}) {
     message: t('ios.configure.q.p8Path'),
     validate: async (v) => {
       if (!v || !v.trim()) return t('ios.configure.q.required');
-      const resolved = path.resolve(v.trim().replace(/^~/, process.env.HOME || ''));
+      const resolved = path.resolve(v.trim().replace(/^~/, homeDir()));
       if (!(await fs.pathExists(resolved))) return t('ios.configure.q.p8NotFound');
       return undefined;
     },
@@ -87,7 +88,7 @@ async function runConfigure(directory, options = {}) {
 
   const apiKey = apiKeyRaw.trim();
   const issuerId = issuerIdRaw.trim();
-  const p8Source = path.resolve(p8PathRaw.trim().replace(/^~/, process.env.HOME || ''));
+  const p8Source = path.resolve(p8PathRaw.trim().replace(/^~/, homeDir()));
 
   const destPath = await installPrivateKey(p8Source, apiKey);
   await writeAppleEnv(projectDir, {

package/lib/commands/new.js

@@ -19,16 +19,8 @@ function generateWebhookKey() {
   return 'rc_wh_' + crypto.randomBytes(16).toString('hex');
 }
 
-function openUrl(url) {
-  try {
-    const { exec } = require('node:child_process');
-    const cmd = process.platform === 'darwin' ? `open "${url}"`
-      : process.platform === 'win32' ? `start "" "${url}"`
-      : `xdg-open "${url}"`;
-    exec(cmd, { shell: true });
-  } catch (_) {}
-}
 const ui = require('../utils/ui');
+const { openUrl, promptOpenBrowser } = require('../utils/browser');
 const { printBanner, successBox, paintLime } = require('../utils/brand');
 const fs = require('fs-extra');
 const { createTranslator } = require('../utils/i18n');
@@ -594,8 +586,7 @@ async function runNew(directory, { language: langHint = null, backend: backendHi
       if (billing.ok && billing.accounts?.length > 0) return true;
       const billingUrl = 'https://console.cloud.google.com/billing/create';
       ui.log.warn(tr('new.firebase.billing.required'));
-      ui.note(`${tr('new.firebase.billing.create.steps')}\n${kleur.cyan(billingUrl)}`);
-      openUrl(billingUrl);
+      await promptOpenBrowser({ url: billingUrl, label: tr('new.firebase.billing.create.steps'), t: tr });
       const ready = await ui.confirm({
         message: tr('new.firebase.billing.created.ready'),
         initialValue: true,
@@ -815,11 +806,22 @@ async function runNew(directory, { language: langHint = null, backend: backendHi
           process.exit(0);
         }
       };
-      const showBeforeContinue = (step1Key, authUrl) => {
-        ui.note(
-          `${tr(step1Key)}\n${kleur.cyan(authUrl)}`,
-          tr('new.firebase.create.beforeContinue.title')
-        );
+      const showBeforeContinue = async (step1Key, authUrl) => {
+        // Quick mode keeps prompts to a minimum: show the link and open it
+        // automatically. Step-by-step mode uses the Enter-to-open pattern.
+        if (isQuick) {
+          ui.note(
+            `${tr(step1Key)}\n${kleur.cyan(authUrl)}`,
+            tr('new.firebase.create.beforeContinue.title')
+          );
+          openUrl(authUrl);
+          return;
+        }
+        await promptOpenBrowser({
+          url: authUrl,
+          label: `${tr('new.firebase.create.beforeContinue.title')}\n${tr(step1Key)}`,
+          t: tr,
+        });
       };
       if (setupResult.ok) {
         ps1.succeed(tr('new.firebase.create.success'));
@@ -831,8 +833,7 @@ async function runNew(directory, { language: langHint = null, backend: backendHi
         // retry will activate it once the OAuth Web Client exists. We only warn
         // here when Email/Anonymous themselves failed (which is the rare path).
         if (!setupResult.authEnabled) {
-          showBeforeContinue('new.firebase.create.beforeContinue.step1.noAuth', authUrl);
-          openUrl(authUrl);
+          await showBeforeContinue('new.firebase.create.beforeContinue.step1.noAuth', authUrl);
           if (!isQuick) {
             await askReady('new.firebase.create.beforeContinue.ready.noAuth');
           }
@@ -888,8 +889,7 @@ async function runNew(directory, { language: langHint = null, backend: backendHi
             printCreateFromScratchStatus(lastResult, tr);
             const authUrl = `https://console.firebase.google.com/project/${core.firebaseProjectId}/authentication/providers`;
             if (!lastResult.authEnabled) {
-              showBeforeContinue('new.firebase.create.beforeContinue.step1.noAuth', authUrl);
-              openUrl(authUrl);
+              await showBeforeContinue('new.firebase.create.beforeContinue.step1.noAuth', authUrl);
               if (!isQuick) {
                 await askReady('new.firebase.create.beforeContinue.ready.noAuth');
               }
@@ -1791,7 +1791,6 @@ async function runNew(directory, { language: langHint = null, backend: backendHi
         ui.log.warn(
           `${tr('new.sha1.failed', { error: (sha1Result.sha1Error || '').slice(0, 120) })}\n${tr('new.sha1.manual')}\n${kleur.cyan(sha1ManualUrl)}`
         );
-        openUrl(sha1ManualUrl);
       }
     }
   }

package/lib/scaffold/CHANGELOG.json

@@ -1,4 +1,18 @@
 {
+  "1.21.0": {
+    "modules": {
+      "components": {
+        "pt": "KasySidebarPro com renderização mais leve: removidos cálculos de borda redundantes, deixando a sidebar mais simples e performática.",
+        "en": "Lighter KasySidebarPro rendering: removed redundant border-radius calculations, making the sidebar simpler and more performant.",
+        "es": "Renderizado más ligero de KasySidebarPro: se quitaron cálculos de borde redundantes, dejando la barra lateral más simple y eficiente."
+      },
+      "core": {
+        "pt": "KasyHover agora aceita hoverEnabled: permite desligar o realce ao passar o mouse em listas simples (como a tela de Configurações), mantendo o cursor de clique e o feedback de toque.",
+        "en": "KasyHover now accepts hoverEnabled: lets you turn off the hover highlight on plain list rows (like the Settings screen) while keeping the click cursor and press feedback.",
+        "es": "KasyHover ahora acepta hoverEnabled: permite desactivar el resaltado al pasar el cursor en listas simples (como la pantalla de Ajustes), manteniendo el cursor de clic y el feedback al pulsar."
+      }
+    }
+  },
   "1.18.0": {
     "modules": {
       "components": {

package/lib/scaffold/backends/firebase/setup-from-scratch.js

@@ -18,6 +18,7 @@ const { promisify } = require('node:util');
 const path = require('node:path');
 const fs = require('fs-extra');
 const os = require('node:os');
+const { getInstallGuide } = require('../../../utils/checks');
 
 const execAsync = promisify(exec);
 
@@ -104,14 +105,15 @@ async function checkGcloudAuth() {
  * Get platform-specific install instructions for gcloud CLI.
  */
 function getGcloudInstallInstructions() {
-  const platform = process.platform;
-  if (platform === 'darwin') {
-    return { install: 'brew install --cask google-cloud-sdk', after: 'gcloud auth login', url: 'https://cloud.google.com/sdk/docs/install' };
-  }
-  if (platform === 'win32') {
-    return { install: null, hint: 'Download and run the installer from the link below, then restart the terminal.', after: 'gcloud auth login', url: 'https://cloud.google.com/sdk/docs/install#windows' };
-  }
-  return { install: 'curl https://sdk.cloud.google.com | bash', after: 'gcloud auth login', url: 'https://cloud.google.com/sdk/docs/install' };
+  // Delegates to the single source of truth in utils/checks so the install
+  // command shown here can never drift from the one the env checks suggest.
+  const guide = getInstallGuide('gcloud');
+  return {
+    install: guide.cmd,
+    hint: guide.cmd ? null : 'Download and run the installer from the link below, then restart the terminal.',
+    after: guide.after,
+    url: guide.url,
+  };
 }
 
 /**

package/lib/scaffold/shared/post-build.js

@@ -13,13 +13,17 @@ const { exec } = require('node:child_process');
 const { promisify } = require('node:util');
 const path = require('node:path');
 const fs = require('fs-extra');
+const { augmentedEnv, pubCacheBin } = require('../../utils/env-tools');
 
 const execAsync = promisify(exec);
 const MAX_BUFFER = 100 * 1024 * 1024; // 100 MB — build_runner can be verbose
 
 async function run(cmd, cwd, timeout) {
   try {
-    const opts = { cwd, maxBuffer: MAX_BUFFER };
+    // Run with the augmented PATH so tools installed earlier in this same
+    // session (flutterfire via pub global, etc.) are found without the user
+    // having to reopen the terminal — see utils/env-tools.
+    const opts = { cwd, maxBuffer: MAX_BUFFER, env: augmentedEnv() };
     if (timeout) opts.timeout = timeout;
     const { stdout, stderr } = await execAsync(cmd, opts);
     return { ok: true, stdout, stderr };
@@ -62,12 +66,13 @@ async function flutterfireConfigure(projectDir, firebaseProjectId, options = {})
     '--yes',
   ].join(' ');
 
-  // Prefer the binary on PATH; fall back to the pub-cache absolute path for
-  // environments where ~/.pub-cache/bin isn't exported to child processes.
+  // Prefer the binary on PATH (the augmented PATH in run() already exposes the
+  // pub-cache bin dir); fall back to the absolute pub-cache path for shells
+  // that still don't see it. pubCacheBin() is cross-platform — it resolves the
+  // right place on Windows (%LOCALAPPDATA%\Pub\Cache\bin) vs ~/.pub-cache/bin.
   const result = await run(`flutterfire configure ${args}`, projectDir, 300_000);
-  if (!result.ok && (result.error?.includes('ENOENT') || result.error?.includes('not found'))) {
-    const pubCacheBin = `${process.env.HOME}/.pub-cache/bin/flutterfire`;
-    return run(`${pubCacheBin} configure ${args}`, projectDir, 300_000);
+  if (!result.ok && (result.error?.includes('ENOENT') || result.error?.includes('not found') || result.error?.includes('not recognized'))) {
+    return run(`${pubCacheBin('flutterfire')} configure ${args}`, projectDir, 300_000);
   }
   return result;
 }

package/lib/utils/apple-release.js

@@ -5,6 +5,7 @@ const fs = require('fs-extra');
 const os = require('node:os');
 const kleur = require('kleur');
 const ui = require('./ui');
+const { openUrl } = require('./browser');
 const { exec, spawn } = require('node:child_process');
 const { promisify } = require('node:util');
 
@@ -144,16 +145,6 @@ async function installPrivateKey(sourcePath, keyId) {
   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';

package/lib/utils/browser.js

@@ -0,0 +1,61 @@
+/**
+ * Browser helpers. Centralizes the platform-specific "open a URL" command that
+ * was duplicated across new.js / docs.js / apple-release.js, and adds the
+ * standard interaction the CLI uses for any external link:
+ *
+ *   1. always PRINT the URL (so it works over SSH / headless / no GUI), then
+ *   2. let the user press Enter to OPEN it in the default browser.
+ *
+ * This beats auto-opening (intrusive, fires at the wrong moment) and beats
+ * printing a bare URL (the user has to copy-paste). Press Enter and it opens.
+ *
+ * @module utils/browser
+ */
+
+const { exec } = require('node:child_process');
+const kleur = require('kleur');
+const ui = require('./ui');
+
+/**
+ * Open a URL in the default browser. Best-effort: never throws, and async
+ * failures are swallowed because the URL is always printed alongside.
+ *
+ * @returns {boolean} true if the open command was dispatched
+ */
+function openUrl(url) {
+  try {
+    const cmd = process.platform === 'darwin'
+      ? `open "${url}"`
+      : process.platform === 'win32'
+        ? `start "" "${url}"`
+        : `xdg-open "${url}"`;
+    exec(cmd, () => {}); // swallow async errors — opening a browser is best-effort
+    return true;
+  } catch (_) {
+    return false;
+  }
+}
+
+/**
+ * Print a link and offer to open it in the browser on Enter.
+ *
+ * @param {object}   opts
+ * @param {string}   opts.url             the link to show/open
+ * @param {string}  [opts.label]          line shown above the URL
+ * @param {string}  [opts.confirmMessage] the yes/no prompt (Enter = yes)
+ * @param {Function}[opts.t]              translator; falls back to English-ish keys
+ * @returns {Promise<boolean>} whether the user chose to open it
+ */
+async function promptOpenBrowser({ url, label, confirmMessage, t }) {
+  const tr = typeof t === 'function' ? t : null;
+  const intro = label || (tr ? tr('browser.open.intro') : 'Open this link in your browser:');
+  ui.log.message(`${intro}\n${kleur.cyan(url)}`);
+  const open = await ui.confirm({
+    message: confirmMessage || (tr ? tr('browser.open.confirm') : 'Open it in the browser now?'),
+    initialValue: true,
+  });
+  if (open) openUrl(url);
+  return open;
+}
+
+module.exports = { openUrl, promptOpenBrowser };

package/lib/utils/checks.js

@@ -3,6 +3,8 @@ const { promisify } = require('node:util');
 const kleur = require('kleur');
 const ui = require('./ui');
 const { createTranslator, detectDefaultLanguage } = require('./i18n');
+const { augmentedEnv, pubCacheBin } = require('./env-tools');
+const { promptOpenBrowser } = require('./browser');
 
 const execAsync = promisify(exec);
 
@@ -10,12 +12,41 @@ const execAsync = promisify(exec);
 const TOOL_CHECK_TIMEOUT = 15_000;
 // Timeout para instalação automática de ferramentas (5 min)
 const INSTALL_TIMEOUT = 300_000;
+const MAX_BUFFER = 50 * 1024 * 1024;
 
 // 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';
 
+/**
+ * Single source of truth for "how do I install tool X on this OS". Returns the
+ * package-manager command we can run (with the user's consent) plus a docs URL
+ * and any follow-up command. Used both for the auto-install offer and for the
+ * manual guidance fallback, so the two can never drift apart again.
+ *
+ * @param {'gcloud'|'flutter'} tool
+ * @returns {{ cmd: string|null, after: string|null, url: string }}
+ */
+function getInstallGuide(tool) {
+  const guides = {
+    gcloud: {
+      darwin: { cmd: 'brew install --cask google-cloud-sdk', after: 'gcloud auth login', url: 'https://cloud.google.com/sdk/docs/install' },
+      win32: { cmd: 'winget install --id Google.CloudSDK -e', after: 'gcloud auth login', url: 'https://cloud.google.com/sdk/docs/install-sdk#windows' },
+      linux: { cmd: 'curl https://sdk.cloud.google.com | bash', after: 'gcloud auth login', url: 'https://cloud.google.com/sdk/docs/install' },
+    },
+    flutter: {
+      // Flutter installs via brew cask on macOS; on Windows/Linux the supported
+      // path is the SDK archive, so we guide to the docs instead of guessing.
+      darwin: { cmd: 'brew install --cask flutter', after: 'flutter doctor', url: 'https://docs.flutter.dev/get-started/install/macos' },
+      win32: { cmd: null, after: 'flutter doctor', url: 'https://docs.flutter.dev/get-started/install/windows' },
+      linux: { cmd: null, after: 'flutter doctor', url: 'https://docs.flutter.dev/get-started/install/linux' },
+    },
+  };
+  const byTool = guides[tool] || {};
+  return byTool[process.platform] || byTool.linux || { cmd: null, after: null, url: '' };
+}
+
 const BASE_CHECKS = [
   {
     name: 'Node.js',
@@ -29,6 +60,8 @@ const BASE_CHECKS = [
     required: false,
     warnMessageKey: 'checks.flutter.warn',
     minVersion: MIN_FLUTTER_VERSION,
+    installGuide: () => getInstallGuide('flutter'),
+    confirmInstall: true,
   },
   {
     name: 'Dart SDK',
@@ -55,19 +88,6 @@ const PLATFORM_CHECKS = {
   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 = [
   {
@@ -82,14 +102,19 @@ const FIREBASE_CHECKS = [
     command: 'flutterfire --version',
     required: true,
     tryInstall: 'dart pub global activate flutterfire_cli',
-    retryCommand: `${process.env.HOME}/.pub-cache/bin/flutterfire --version`,
+    // After activation the binary lives in the pub-cache bin dir, which is NOT
+    // on the current process PATH (and is in a different place on Windows). We
+    // re-check via the augmented PATH first and the absolute pub-cache path as
+    // a fallback — see env-tools.pubCacheBin.
+    pubGlobalBin: 'flutterfire',
     tryInstallMessageKey: 'setup.flutterfire.installing',
   },
   {
     name: 'gcloud CLI (create-from-scratch)',
     command: 'gcloud --version',
     required: false,
-    failHint: getGcloudInstallHint(),
+    installGuide: () => getInstallGuide('gcloud'),
+    confirmInstall: true,
     waitPromptKey: 'checks.waitPrompt.gcloud.install',
   },
   {
@@ -159,61 +184,171 @@ function extractVersion(stdout, checkName) {
   return m ? m[0] : raw.slice(0, 20);
 }
 
+/** execAsync that never throws and always runs with the augmented PATH. */
+async function execTool(cmd, timeout = TOOL_CHECK_TIMEOUT) {
+  try {
+    const { stdout, stderr } = await execAsync(cmd, {
+      encoding: 'utf8',
+      timeout,
+      env: augmentedEnv(),
+      maxBuffer: MAX_BUFFER,
+    });
+    return { ok: true, stdout, stderr };
+  } catch (err) {
+    return { ok: false, error: err.message, stderr: err.stderr || '', stdout: err.stdout || '' };
+  }
+}
+
+/**
+ * Verify a tool responds after an install. Tries the plain command first (now
+ * that PATH is augmented) and, for pub-global tools, the absolute pub-cache
+ * path as a fallback for shells that don't pick up the new PATH.
+ */
+async function verifyTool(check) {
+  const attempts = [check.command];
+  if (check.pubGlobalBin) attempts.push(`${pubCacheBin(check.pubGlobalBin)} --version`);
+  else if (check.retryCommand) attempts.push(check.retryCommand);
+
+  for (const cmd of attempts) {
+    const res = await execTool(cmd);
+    if (res.ok) return { ok: true, stdout: res.stdout };
+  }
+  return { ok: false };
+}
+
 async function runSingleCheck(check, options = {}) {
   const showVersion = check.showVersion !== undefined ? check.showVersion : (options.showVersion !== undefined ? options.showVersion : true);
   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 first = await execTool(check.command);
+  if (first.ok) {
+    const version = showVersion ? extractVersion(first.stdout, check.name) : null;
     return { ...check, ok: true, version: version || null };
-  } catch (err) {
-    const diagnosis = diagnoseFailure(err);
-    if (check.tryInstall) {
-      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 diagnosis = diagnoseFailure({ message: first.error, stderr: first.stderr, stdout: first.stdout });
+
+  // Lightweight auto-install (npm / pub global). Heavy tools (gcloud, flutter)
+  // use confirmInstall and are handled interactively after the spinner.
+  if (check.tryInstall) {
+    const installed = await execTool(check.tryInstall, INSTALL_TIMEOUT);
+    if (installed.ok) {
+      const verified = await verifyTool(check);
+      if (verified.ok) {
+        const version = showVersion ? extractVersion(verified.stdout, check.name) : null;
         return { ...check, ok: true, version: version || null };
-      } catch {
-        autoInstallFailed = true;
       }
     }
-    return { ...check, ok: false, autoInstallFailed, diagnosis };
+    autoInstallFailed = true;
+  }
+
+  return { ...check, ok: false, autoInstallFailed, diagnosis };
+}
+
+/** Re-run a check's command (with augmented PATH) and report the result inline. */
+async function revalidate(check, t) {
+  const verified = await verifyTool(check);
+  if (verified.ok) {
+    const version = check.showVersion === false ? null : extractVersion(verified.stdout, check.name);
+    ui.log.success(version ? `${check.name} — ${version}` : check.name);
+    return true;
   }
+  ui.log.error(`${check.name} ${t('checks.stillMissing') || 'still missing'}`);
+  return false;
 }
 
 /**
- * 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.
+ * Interactive recovery for a failed check. The flow, in order:
+ *   1. Heavy tools with a package-manager command (gcloud, flutter): offer to
+ *      install it now via brew/winget after a yes/no confirm.
+ *   2. Manual guidance: print the exact command for this OS, offer to open the
+ *      docs in the browser on Enter.
+ *   3. Wait for the user to fix it, then re-check on Enter (never a dead end).
+ * Returns true if the tool is present by the end.
  */
-async function retryCheckInteractively(check, t) {
+async function recoverCheckInteractively(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 guide = typeof check.installGuide === 'function' ? check.installGuide() : null;
+
+  // 1) Offer auto-install for heavy tools that have a package-manager command.
+  if (guide && guide.cmd && check.confirmInstall) {
+    const doInstall = await ui.confirm({
+      message: t('checks.install.confirm', { name: check.name, cmd: guide.cmd }),
+      initialValue: true,
+    });
+    if (doInstall) {
+      const spinner = ui.spinner();
+      spinner.start(t('checks.install.running', { name: check.name }));
+      const installed = await execTool(guide.cmd, INSTALL_TIMEOUT);
+      spinner.stop(t('checks.install.running', { name: check.name }));
+      if (installed.ok && (await revalidate(check, t))) return true;
+      ui.log.warn(t('checks.install.failedManual', { name: check.name }));
+    }
+  }
+
+  // 2) Manual guidance — the exact command for this OS + an Enter-to-open link.
+  // Fall back to the auto-install command (e.g. the `dart pub global activate`
+  // that just failed) so the user always sees *how* to install it by hand,
+  // running it in their own shell where the env may differ.
+  const manualCmd = (guide && guide.cmd) || check.tryInstall || check.failHint;
+  if (manualCmd) {
+    ui.log.message(`${t('checks.runHint') || 'Run'}: ${kleur.cyan(manualCmd)}`);
+  }
+  if (guide && guide.after) {
+    ui.log.message(`${t('checks.thenRun') || 'Then run'}: ${kleur.cyan(guide.after)}`);
   }
-  const proceed = await ui.confirm({
-    message: check.waitPrompt,
-    initialValue: true,
-  });
+  if (guide && guide.url) {
+    await promptOpenBrowser({
+      url: guide.url,
+      t,
+      label: t('checks.install.openDocs', { name: check.name }),
+    });
+  }
+
+  // 3) Wait + re-check on Enter.
+  const waitMessage = check.waitPromptKey
+    ? t(check.waitPromptKey)
+    : (check.waitPrompt || t('checks.recheck', { name: check.name }));
+  const proceed = await ui.confirm({ message: waitMessage, 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;
+  return revalidate(check, t);
+}
+
+/** Non-interactive failure reporting (CI, doctor without a TTY, or user opt-out). */
+function printCheckFailure(result, t) {
+  const guide = typeof result.installGuide === 'function' ? result.installGuide() : null;
+  const cmdHint = (guide && guide.cmd) || result.tryInstall || result.failHint;
+  const hint = cmdHint ? `\n${kleur.dim(`→ ${cmdHint}`)}` : '';
+  const urlHint = guide && guide.url ? `\n${kleur.dim(`→ ${guide.url}`)}` : '';
+
+  if (result.required) {
+    const detail = result.autoInstallFailed ? ` — ${t('checks.install.failed')}` : '';
+    const diagSuffix = result.diagnosis ? `\n${kleur.dim(`→ ${t(`checks.diagnostic.${result.diagnosis}`, { name: result.name })}`)}` : '';
+    ui.log.error(`${t('checks.missing', { name: result.name })}${detail}${diagSuffix}${hint}${urlHint}`);
+  } else if (result.diagnosis) {
+    ui.log.warn(t(`checks.diagnostic.${result.diagnosis}`, { name: result.name }));
+  } else if (result.warnMessage) {
+    ui.log.warn(`${result.warnMessage}${hint}`);
+  } else if (result.warnMessageKey) {
+    ui.log.warn(`${t(result.warnMessageKey)}${hint}`);
+  } else {
+    ui.log.warn(`${t('checks.notFound', { name: result.name })}${hint}${urlHint}`);
   }
 }
 
+function canRecover(result) {
+  return Boolean(
+    result.installGuide || result.tryInstall || result.waitPromptKey || result.waitPrompt
+  );
+}
+
 async function runChecks(checks, title, options = {}) {
   const t = options.t || createTranslator(options.language || detectDefaultLanguage());
   const { showVersion = true } = options;
+  // Interactive recovery needs a real terminal; disable it in CI/pipes so the
+  // command never blocks waiting for input that will never come.
+  const interactive = options.interactive !== false && Boolean(process.stdout.isTTY);
 
   // Single spinner over all checks, show failures afterwards. The visual
   // sits inside the clack rail (│) opened by the caller's ui.intro().
@@ -243,31 +378,15 @@ 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 (interactive && canRecover(result)) {
+      const recovered = await recoverCheckInteractively({ ...result, t }, t);
       if (recovered) {
         const idx = results.indexOf(result);
-        if (idx >= 0) results[idx] = { ...result, ok: true };
+        if (idx >= 0) results[idx] = { ...result, ok: true, autoInstallFailed: false };
+        continue;
       }
-      continue;
-    }
-    const hint = result.failHint ? `\n${kleur.dim(`→ ${result.failHint}`)}` : '';
-    if (result.required) {
-      const detail = result.autoInstallFailed ? ` — ${t('checks.install.failed')}` : '';
-      const diagSuffix = result.diagnosis ? `\n${kleur.dim(`→ ${t(`checks.diagnostic.${result.diagnosis}`, { name: result.name })}`)}` : '';
-      ui.log.error(`${t('checks.missing', { name: result.name })}${detail}${diagSuffix}${hint}`);
-    } else if (result.diagnosis) {
-      ui.log.warn(t(`checks.diagnostic.${result.diagnosis}`, { name: result.name }));
-    } else if (result.warnMessage) {
-      ui.log.warn(`${result.warnMessage}${hint}`);
-    } else if (result.warnMessageKey) {
-      ui.log.warn(`${t(result.warnMessageKey)}${hint}`);
-    } else {
-      ui.log.warn(`${t('checks.notFound', { name: result.name })}${hint}`);
     }
+    printCheckFailure(result, t);
   }
 
   return results;
@@ -281,6 +400,7 @@ module.exports = {
   getBaseChecks,
   getPlatformChecks,
   getBackendChecks,
+  getInstallGuide,
   runChecks,
   hasRequiredFailures,
 };

package/lib/utils/env-tools.js

@@ -0,0 +1,101 @@
+/**
+ * Cross-platform resolution of tool install locations and an "augmented" PATH.
+ *
+ * Why this exists: several places in the CLI used `process.env.HOME` to build
+ * the pub-cache path (e.g. `${HOME}/.pub-cache/bin/flutterfire`). On Windows
+ * `HOME` is undefined (it's `USERPROFILE`) AND the pub-cache lives somewhere
+ * else entirely (`%LOCALAPPDATA%\Pub\Cache\bin`), so the fallback never worked
+ * there — which is why FlutterFire "never installed" on Windows.
+ *
+ * It also exposes `augmentedEnv()`: a copy of the environment with the dirs of
+ * freshly-installed CLIs prepended to PATH. A running process inherits the PATH
+ * of the shell that launched it and never sees changes made afterwards, so a
+ * tool installed mid-`kasy new` (flutterfire, firebase…) is invisible to child
+ * processes until the user opens a new terminal — unless we inject the dir here.
+ *
+ * @module utils/env-tools
+ */
+
+const os = require('node:os');
+const path = require('node:path');
+const fs = require('node:fs');
+
+const isWindows = process.platform === 'win32';
+const PATH_SEP = isWindows ? ';' : ':';
+
+/** Cross-platform home directory (never trust process.env.HOME on Windows). */
+function homeDir() {
+  return os.homedir();
+}
+
+/**
+ * Directory where `dart pub global activate` drops executables.
+ *   - Honors $PUB_CACHE when the user customized it (works on every OS).
+ *   - Windows: %LOCALAPPDATA%\Pub\Cache\bin (modern Dart) with %APPDATA% as a
+ *     legacy fallback. We prefer whichever already exists on disk.
+ *   - macOS/Linux: ~/.pub-cache/bin
+ */
+function pubCacheBinDir() {
+  // Use the platform-specific path flavor explicitly (path.win32 / path.posix)
+  // so separators are correct even when this logic is unit-tested from another
+  // OS — in production isWindows already matches the running platform.
+  const p = isWindows ? path.win32 : path.posix;
+  if (process.env.PUB_CACHE) {
+    return p.join(process.env.PUB_CACHE, 'bin');
+  }
+  if (isWindows) {
+    const candidates = [
+      process.env.LOCALAPPDATA && p.join(process.env.LOCALAPPDATA, 'Pub', 'Cache', 'bin'),
+      process.env.APPDATA && p.join(process.env.APPDATA, 'Pub', 'Cache', 'bin'),
+    ].filter(Boolean);
+    for (const candidate of candidates) {
+      if (fs.existsSync(candidate)) return candidate;
+    }
+    return candidates[0] || p.join(homeDir(), 'AppData', 'Local', 'Pub', 'Cache', 'bin');
+  }
+  return p.join(homeDir(), '.pub-cache', 'bin');
+}
+
+/**
+ * Absolute path to a pub-global executable, quoted and ready to drop into a
+ * shell command. On Windows the activated binary is a `.bat` shim.
+ *
+ * @param {string} name e.g. 'flutterfire'
+ * @returns {string} quoted absolute path, or '' if it can't be located
+ */
+function pubCacheBin(name) {
+  const dir = pubCacheBinDir();
+  const file = isWindows ? path.win32.join(dir, `${name}.bat`) : path.posix.join(dir, name);
+  return `"${file}"`;
+}
+
+/**
+ * A copy of process.env with `extraDirs` (plus the pub-cache bin) prepended to
+ * PATH, so child processes can find tools installed earlier in this same run.
+ * On Windows we set both `PATH` and `Path` because Node reads the original key.
+ *
+ * @param {string[]} [extraDirs] additional directories to expose
+ */
+function augmentedEnv(extraDirs = []) {
+  const dirs = [pubCacheBinDir(), ...extraDirs].filter(Boolean);
+  const env = { ...process.env };
+  // Windows env keys are case-insensitive; find whichever key holds PATH.
+  const pathKey = Object.keys(env).find((k) => k.toLowerCase() === 'path') || 'PATH';
+  const current = env[pathKey] || '';
+  const existing = current.split(PATH_SEP);
+  const additions = dirs.filter((dir) => !existing.includes(dir));
+  if (additions.length > 0) {
+    const next = current ? `${additions.join(PATH_SEP)}${PATH_SEP}${current}` : additions.join(PATH_SEP);
+    env[pathKey] = next;
+    if (isWindows) env.Path = next; // belt-and-suspenders for case-sensitive reads
+  }
+  return env;
+}
+
+module.exports = {
+  isWindows,
+  homeDir,
+  pubCacheBinDir,
+  pubCacheBin,
+  augmentedEnv,
+};

package/lib/utils/i18n/messages-en.js

@@ -122,6 +122,14 @@ module.exports = {
     'checks.install.failed': 'auto-install failed — run the command manually',
     'checks.waitPrompt.gcloud.install': 'After installing gcloud, press Enter to check again',
     'checks.waitPrompt.gcloud.auth': 'After running gcloud auth login, press Enter to check again',
+    'checks.thenRun': 'Then run',
+    'checks.recheck': 'After installing {name}, press Enter to check again',
+    'checks.install.confirm': 'Install {name} now? ({cmd})',
+    'checks.install.running': 'Installing {name}…',
+    'checks.install.failedManual': 'Could not install {name} automatically. Do it manually:',
+    'checks.install.openDocs': 'Open the install page in the browser?',
+    'browser.open.intro': 'Open this link in your browser:',
+    'browser.open.confirm': 'Open it in the browser now?',
     'error.hint.notFlutterProject': 'You\'re not inside a Flutter project. Try `kasy new` to create one, or cd into an existing one.',
     'error.hint.flutterMissing': 'Flutter is not installed or not on your PATH. Run `kasy doctor` to diagnose.',
     'error.hint.permission': 'A file or folder is read-only. Check the parent directory permissions or try again from your home folder.',

package/lib/utils/i18n/messages-es.js

@@ -122,6 +122,14 @@ module.exports = {
     'checks.install.failed': 'instalación automática falló — ejecuta el comando manualmente',
     'checks.waitPrompt.gcloud.install': 'Tras instalar gcloud, presiona Enter para verificar de nuevo',
     'checks.waitPrompt.gcloud.auth': 'Tras ejecutar gcloud auth login, presiona Enter para verificar de nuevo',
+    'checks.thenRun': 'Luego ejecuta',
+    'checks.recheck': 'Tras instalar {name}, presiona Enter para verificar de nuevo',
+    'checks.install.confirm': '¿Instalar {name} ahora? ({cmd})',
+    'checks.install.running': 'Instalando {name}…',
+    'checks.install.failedManual': 'No pude instalar {name} automáticamente. Hazlo manualmente:',
+    'checks.install.openDocs': '¿Abrir la página de instalación en el navegador?',
+    'browser.open.intro': 'Abre este enlace en el navegador:',
+    'browser.open.confirm': '¿Abrir en el navegador ahora?',
     'error.hint.notFlutterProject': 'No estás dentro de un proyecto Flutter. Usa `kasy new` para crear uno, o entra en la carpeta de un proyecto existente.',
     'error.hint.flutterMissing': 'Flutter no está instalado o no está en el PATH. Ejecuta `kasy doctor` para diagnosticar.',
     'error.hint.permission': 'Un archivo/carpeta es de solo lectura. Verifica los permisos de la carpeta padre o intenta desde tu carpeta home.',

package/lib/utils/i18n/messages-pt.js

@@ -122,6 +122,14 @@ module.exports = {
     'checks.install.failed': 'instalação automática falhou — execute o comando manualmente',
     'checks.waitPrompt.gcloud.install': 'Após instalar o gcloud, pressione Enter para verificar novamente',
     'checks.waitPrompt.gcloud.auth': 'Após rodar gcloud auth login, pressione Enter para verificar novamente',
+    'checks.thenRun': 'Depois rode',
+    'checks.recheck': 'Após instalar {name}, pressione Enter para verificar novamente',
+    'checks.install.confirm': 'Instalar {name} agora? ({cmd})',
+    'checks.install.running': 'Instalando {name}…',
+    'checks.install.failedManual': 'Não consegui instalar {name} automaticamente. Faça manualmente:',
+    'checks.install.openDocs': 'Abrir a página de instalação no navegador?',
+    'browser.open.intro': 'Abra este link no navegador:',
+    'browser.open.confirm': 'Abrir no navegador agora?',
     'error.hint.notFlutterProject': 'Você não está dentro de um projeto Flutter. Use `kasy new` para criar um, ou entre na pasta de um projeto existente.',
     'error.hint.flutterMissing': 'Flutter não está instalado ou não está no PATH. Rode `kasy doctor` para diagnosticar.',
     'error.hint.permission': 'Algum arquivo/pasta está somente leitura. Verifique as permissões da pasta pai ou tente de novo a partir da sua pasta home.',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kasy-cli",
-  "version": "1.20.1",
+  "version": "1.21.0-beta.0",
   "description": "CLI for scaffolding production-ready Flutter SaaS apps with Firebase, Supabase, or API REST backends.",
   "bin": {
     "kasy": "./bin/kasy.js"

package/templates/firebase/lib/components/kasy_sidebar_pro.dart

@@ -244,10 +244,6 @@ class _KasySidebarProState extends State<KasySidebarPro> {
     final c = _colors;
 
     final bool anchoredLeft = widget.side == KasySidebarProSide.left;
-    const Radius r = Radius.circular(12);
-    final BorderRadius borderRadius = anchoredLeft
-        ? const BorderRadius.only(topRight: r, bottomRight: r)
-        : const BorderRadius.only(topLeft: r, bottomLeft: r);
     final Border border = anchoredLeft
         ? Border(right: BorderSide(color: c.border))
         : Border(left: BorderSide(color: c.border));
@@ -282,16 +278,12 @@ class _KasySidebarProState extends State<KasySidebarPro> {
               right: anchoredLeft ? halfBtn : 0,
               top: 0,
               bottom: 0,
-              child: ClipRRect(
-                borderRadius: borderRadius,
-                child: DecoratedBox(
-                  decoration: BoxDecoration(
-                    color: c.bg,
-                    border: border,
-                    borderRadius: borderRadius,
-                  ),
-                  child: _buildScrollableContent(context, c),
+              child: DecoratedBox(
+                decoration: BoxDecoration(
+                  color: c.bg,
+                  border: border,
                 ),
+                child: _buildScrollableContent(context, c),
               ),
             ),
             // Collapse button — centered on the sidebar edge, fully within

package/templates/firebase/lib/core/widgets/kasy_hover.dart

@@ -44,6 +44,7 @@ class KasyHover extends ConsumerStatefulWidget {
     this.margin,
     this.semanticLabel,
     this.hapticEnabled = true,
+    this.hoverEnabled = true,
     this.hoverColor,
     this.pressColor,
   });
@@ -67,6 +68,13 @@ class KasyHover extends ConsumerStatefulWidget {
   /// Haptic on tap (automatically ignored on web).
   final bool hapticEnabled;
 
+  /// Whether the pointer-hover overlay is shown on pointer-capable devices.
+  ///
+  /// When false, the resting/press feedback and click cursor are kept, but no
+  /// background fill appears while hovering. Use on plain list rows (e.g.
+  /// settings) where a hover highlight is visually unwanted.
+  final bool hoverEnabled;
+
   /// Exact background colour used while the pointer hovers over the widget.
   ///
   /// When non-null, this solid colour replaces the default semi-transparent
@@ -110,7 +118,7 @@ class _KasyHoverState extends ConsumerState<KasyHover> {
     final bool isDark = Theme.of(context).brightness == Brightness.dark;
     final Color base = widget.pressColor ?? context.colors.onSurface;
     if (_pressed) return base.withValues(alpha: isDark ? 0.04 : 0.10);
-    if (_hovered) {
+    if (_hovered && widget.hoverEnabled) {
       // Solid hover colour — used for nav items where hover must exactly
       // match the selected background.
       if (widget.hoverColor != null) return widget.hoverColor!;

package/templates/firebase/lib/features/settings/ui/widgets/settings_tile.dart

@@ -155,6 +155,7 @@ class SettingsTile extends StatelessWidget {
   Widget build(BuildContext context) {
     return KasyHover(
       onTap: onTap,
+      hoverEnabled: false,
       semanticLabel: title,
       padding: const EdgeInsets.symmetric(vertical: KasySpacing.sm),
       child: Row(