kasy-cli 1.16.0 → 1.18.0

package/lib/scaffold/generate.js

@@ -66,7 +66,7 @@ const {
   removeDevelopmentTeam,
   localizeReleaseDocs,
 } = require('./shared/generator-utils');
-const { pubGet, slangGenerate, buildRunner, flutterfireConfigure, writeGoogleAuthOptions, writeGoogleIosUrlScheme, patchFirebaseServiceWorker } = require('./shared/post-build');
+const { pubGet, slangGenerate, buildRunner, dartFix, flutterfireConfigure, writeGoogleAuthOptions, writeGoogleIosUrlScheme, patchFirebaseServiceWorker } = require('./shared/post-build');
 const { FIREBASE_SOURCE_DIR } = require('./shared/backend-config');
 
 /**
@@ -97,6 +97,7 @@ async function generateProject(targetDir, backend, options, hooks = {}) {
     onProgress = () => {},
     includeWeb = true,
     language = 'en',
+    deferGoogleAuthPatches = false,
   } = options;
 
   const { applyBackendSetup = null, postBuild = null } = hooks;
@@ -325,7 +326,12 @@ async function generateProject(targetDir, backend, options, hooks = {}) {
     // Android: populate kGoogleWebClientId in lib/google_auth_options.dart.
     // Skip for Supabase — it defines kGoogleIosClientId too, handled separately
     // in new.js after credentials are resolved (readSupabaseGoogleCredentials).
-    if (backend !== 'supabase') {
+    //
+    // When `deferGoogleAuthPatches` is set, the caller will re-run flutterfire
+    // and these patches AFTER enabling Google Sign-In (which creates the OAuth
+    // Web Client + REVERSED_CLIENT_ID). Running them here would fail because the
+    // IDs don't exist yet, surfacing scary red errors that look like real bugs.
+    if (backend !== 'supabase' && !deferGoogleAuthPatches) {
       const gaResult = await writeGoogleAuthOptions(targetDir);
       steps.push({
         name: 'google-auth-options',
@@ -335,12 +341,14 @@ async function generateProject(targetDir, backend, options, hooks = {}) {
     }
 
     // iOS: register REVERSED_CLIENT_ID as a URL scheme in ios/Runner/Info.plist
-    const iosSchemeResult = await writeGoogleIosUrlScheme(targetDir);
-    steps.push({
-      name: 'google-ios-url-scheme',
-      ok: iosSchemeResult.ok,
-      detail: iosSchemeResult.ok ? null : iosSchemeResult.error,
-    });
+    if (!deferGoogleAuthPatches) {
+      const iosSchemeResult = await writeGoogleIosUrlScheme(targetDir);
+      steps.push({
+        name: 'google-ios-url-scheme',
+        ok: iosSchemeResult.ok,
+        detail: iosSchemeResult.ok ? null : iosSchemeResult.error,
+      });
+    }
 
     // Web: patch firebase-messaging-sw.js with real config values (only when web module is selected)
     if (modules.includes('web')) {
@@ -364,6 +372,14 @@ async function generateProject(targetDir, backend, options, hooks = {}) {
     }
   }
 
+  // ── 4. Auto-fix lints (directives_ordering, unused_import, etc.) ───────────
+  // Runs last so generated code, patches and post-build edits are all covered.
+  // Non-fatal: if it fails we still ship a working project; the user can run
+  // `dart fix --apply` manually later.
+  onProgress('dart-fix');
+  const dartFixResult = await dartFix(targetDir);
+  steps.push({ name: 'dart-fix', ok: dartFixResult.ok, detail: dartFixResult.ok ? null : dartFixResult.error });
+
   return { steps, packageName, appName, bundleId, firebaseProjectId, ...returnExtra };
 }
 

package/lib/scaffold/shared/generator-utils.js

@@ -13,6 +13,36 @@ const pkg = require('../../../package.json');
 /** Backend IDs: firebase | supabase | api */
 const BACKENDS = Object.freeze(['firebase', 'supabase', 'api']);
 
+/**
+ * Resolve the default RC keys to bake into launch.json / Makefile.
+ *
+ * `kasy run` overrides these at runtime based on the device picked (test_ for
+ * simulator/emulator, appl_/goog_ for physical). The values here are only used
+ * when the user runs Flutter directly (e.g. F5 in VS Code, `make run`) without
+ * going through `kasy run`. We default to test_ since that's what works in the
+ * iOS Simulator and Android Emulator — the common dev case.
+ *
+ * Legacy support: projects generated before this refactor only ask for a single
+ * Android/iOS key (`rcAndroidKey` / `rcIosKey`). When those are passed we honor
+ * them as-is.
+ */
+function resolveDefaultRcKeys(answers) {
+  // Legacy single-key format (pre-test/prod split): keep behavior unchanged.
+  if ((answers.rcAndroidKey || answers.rcIosKey) && !answers.rcTestKey && !answers.rcIosProdKey && !answers.rcAndroidProdKey) {
+    return {
+      android: answers.rcAndroidKey || 'YOUR_REVENUECAT_ANDROID_KEY',
+      ios: answers.rcIosKey || 'YOUR_REVENUECAT_IOS_KEY',
+    };
+  }
+  const test = (answers.rcTestKey || '').trim();
+  const iosProd = (answers.rcIosProdKey || '').trim();
+  const androidProd = (answers.rcAndroidProdKey || '').trim();
+  return {
+    android: test || androidProd || 'YOUR_REVENUECAT_ANDROID_KEY',
+    ios: test || iosProd || 'YOUR_REVENUECAT_IOS_KEY',
+  };
+}
+
 /**
  * Build dart-define args for dev and prod environments.
  * Backend-specific vars: Firebase (none extra), Supabase (BACKEND_URL, SUPABASE_TOKEN), API (BACKEND_URL).
@@ -40,12 +70,11 @@ function buildDartDefines(backend, modules, answers) {
   }
 
   if (modules.includes('revenuecat')) {
-    const androidKey = answers.rcAndroidKey || 'YOUR_REVENUECAT_ANDROID_KEY';
-    const iosKey = answers.rcIosKey || 'YOUR_REVENUECAT_IOS_KEY';
-    dev.push(`--dart-define=RC_ANDROID_API_KEY=${androidKey}`);
-    dev.push(`--dart-define=RC_IOS_API_KEY=${iosKey}`);
-    prod.push(`--dart-define=RC_ANDROID_API_KEY=${androidKey}`);
-    prod.push(`--dart-define=RC_IOS_API_KEY=${iosKey}`);
+    const { android: androidDefault, ios: iosDefault } = resolveDefaultRcKeys(answers);
+    dev.push(`--dart-define=RC_ANDROID_API_KEY=${androidDefault}`);
+    dev.push(`--dart-define=RC_IOS_API_KEY=${iosDefault}`);
+    prod.push(`--dart-define=RC_ANDROID_API_KEY=${androidDefault}`);
+    prod.push(`--dart-define=RC_IOS_API_KEY=${iosDefault}`);
     if (answers.revenuecatWeb) {
       const webKey = answers.rcWebKey || 'YOUR_REVENUECAT_WEB_KEY';
       dev.push(`--dart-define=RC_WEB_API_KEY=${webKey}`);
@@ -144,8 +173,11 @@ async function writeEnvExample(projectDir, modules, answers, language = 'en') {
   if (modules.includes('revenuecat')) {
     lines.push('');
     lines.push(t.revenuecat);
-    lines.push(`RC_ANDROID_API_KEY=${answers.rcAndroidKey || 'YOUR_REVENUECAT_ANDROID_KEY'}`);
-    lines.push(`RC_IOS_API_KEY=${answers.rcIosKey || 'YOUR_REVENUECAT_IOS_KEY'}`);
+    if (t.revenuecatTest) lines.push(t.revenuecatTest);
+    lines.push(`RC_TEST_KEY=${(answers.rcTestKey || '').trim()}`);
+    if (t.revenuecatProd) lines.push(t.revenuecatProd);
+    lines.push(`RC_IOS_PROD_KEY=${(answers.rcIosProdKey || '').trim()}`);
+    lines.push(`RC_ANDROID_PROD_KEY=${(answers.rcAndroidProdKey || '').trim()}`);
     if (answers.revenuecatWeb) {
       lines.push(`RC_WEB_API_KEY=${answers.rcWebKey || 'YOUR_REVENUECAT_WEB_KEY'}`);
     }
@@ -468,6 +500,16 @@ const bool revenuecatWeb = ${revenuecatWeb};
 async function writeKitSetup(projectDir, options) {
   const { appName, bundleId, backend, modules = [], firebaseProjectId, supabaseUrl, supabaseAnonKey, moduleAnswers = {} } = options;
   const revenuecatWeb = !!(modules.includes('revenuecat') && modules.includes('web') && moduleAnswers.revenuecatWeb);
+  // Booleans tracking which RC keys the user configured. We never persist key
+  // values to kit_setup.json — those live in .env (gitignored). These flags
+  // let `kasy doctor` warn about release readiness without re-reading .env.
+  const revenuecatKeys = modules.includes('revenuecat')
+    ? {
+        test: !!(moduleAnswers.rcTestKey && moduleAnswers.rcTestKey.trim()),
+        iosProd: !!(moduleAnswers.rcIosProdKey && moduleAnswers.rcIosProdKey.trim()),
+        androidProd: !!(moduleAnswers.rcAndroidProdKey && moduleAnswers.rcAndroidProdKey.trim()),
+      }
+    : undefined;
   const config = {
     appName: appName || 'App',
     bundleId: bundleId || 'com.example.app',
@@ -480,6 +522,7 @@ async function writeKitSetup(projectDir, options) {
     storageProvider: backend === 'firebase' ? 'firebase' : backend === 'supabase' ? 'supabase' : 'api',
     webCompat: modules.includes('web'),
     revenuecatWeb,
+    ...(revenuecatKeys ? { revenuecatKeys } : {}),
     internationalization: true,
     useSentry: modules.includes('sentry'),
     withOnboarding: modules.includes('onboarding'),
@@ -1638,6 +1681,7 @@ async function localizeReleaseDocs(projectDir, language = 'en') {
 module.exports = {
   BACKENDS,
   buildDartDefines,
+  resolveDefaultRcKeys,
   writeRouter,
   writeVsCodeLaunch,
   writeEnvExample,

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

@@ -45,6 +45,13 @@ async function buildRunner(projectDir) {
   return run('dart run build_runner build --delete-conflicting-outputs', projectDir, 600_000); // 10 min
 }
 
+// Auto-applies fixable lints (directives_ordering, unused_import, etc.) so the
+// generated project opens in the user's IDE with zero warnings. Runs after
+// build_runner so generated files are reordered too where applicable.
+async function dartFix(projectDir) {
+  return run('dart fix --apply', projectDir, 180_000); // 3 min
+}
+
 async function flutterfireConfigure(projectDir, firebaseProjectId, options = {}) {
   const { includeWeb = true } = options;
   const platforms = includeWeb ? 'android,ios,web' : 'android,ios';
@@ -665,49 +672,123 @@ async function validateFacebookAndroidStrings(projectDir) {
 }
 
 /**
- * Validate RevenueCat API keys (RC_IOS_API_KEY, RC_ANDROID_API_KEY) from the project Makefile
- * and return the webhook URL derived from kit_setup.json backend config.
+ * Read a project `.env` file into a plain object. Returns `{}` if the file is
+ * missing. Supports KEY=VALUE lines; ignores comments and blank lines.
  */
-async function validateRevenueCat(projectDir, config = {}) {
-  const makefilePath = path.join(projectDir, 'Makefile');
-  if (!(await fs.pathExists(makefilePath))) {
-    return { ok: true, skipped: true, reason: 'no_makefile' };
-  }
-
+async function readDotenv(projectDir) {
+  const envPath = path.join(projectDir, '.env');
+  if (!(await fs.pathExists(envPath))) return {};
   let content;
   try {
-    content = await fs.readFile(makefilePath, 'utf8');
-  } catch (err) {
-    return { ok: false, error: `Failed to read Makefile: ${err.message}` };
+    content = await fs.readFile(envPath, 'utf8');
+  } catch {
+    return {};
+  }
+  const env = {};
+  for (const rawLine of content.split('\n')) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith('#')) continue;
+    const eq = line.indexOf('=');
+    if (eq === -1) continue;
+    const key = line.slice(0, eq).trim();
+    let value = line.slice(eq + 1).trim();
+    if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+      value = value.slice(1, -1);
+    }
+    if (key) env[key] = value;
   }
+  return env;
+}
 
-  // Only consider non-commented lines
-  const activeLines = content.split('\n').filter((l) => !/^\s*#/.test(l)).join('\n');
-
-  const iosMatch = activeLines.match(/RC_IOS_API_KEY=([^\s\\]+)/);
-  const androidMatch = activeLines.match(/RC_ANDROID_API_KEY=([^\s\\]+)/);
-
-  const iosKey = iosMatch ? iosMatch[1].trim() : '';
-  const androidKey = androidMatch ? androidMatch[1].trim() : '';
-
-  const iosEmpty = !iosKey || iosKey === 'xxx';
-  const androidEmpty = !androidKey || androidKey === 'xxx';
-
-  const iosTest = iosKey.startsWith('test_');
-  const androidTest = androidKey.startsWith('test_');
+/**
+ * Validate RevenueCat keys. The new `.env` is the source of truth:
+ *   RC_TEST_KEY (test_xxx — simulator/emulator)
+ *   RC_IOS_PROD_KEY (appl_xxx — physical iOS)
+ *   RC_ANDROID_PROD_KEY (goog_xxx — physical Android)
+ *
+ * Legacy fallback: if none of the new vars are set we read the old
+ * RC_ANDROID_API_KEY/RC_IOS_API_KEY from `.env`, and finally the Makefile
+ * (oldest projects). Returns flags `doctor.js` uses to render granular hints.
+ */
+async function validateRevenueCat(projectDir, config = {}) {
+  const env = await readDotenv(projectDir);
 
+  // Webhook URL (only Supabase exposes it directly; Firebase points to Console).
   let webhookUrl = null;
   if (config.backendProvider === 'supabase' && config.supabaseProjectId) {
     webhookUrl = `https://${config.supabaseProjectId}.supabase.co/functions/v1/revenuecat-webhook`;
   }
 
+  const testKey = (env.RC_TEST_KEY || '').trim();
+  const iosProdKey = (env.RC_IOS_PROD_KEY || '').trim();
+  const androidProdKey = (env.RC_ANDROID_PROD_KEY || '').trim();
+  const hasNewKeys = !!(testKey || iosProdKey || androidProdKey);
+
+  // Legacy single-key path (for projects generated before the test/prod split).
+  if (!hasNewKeys) {
+    let iosKey = (env.RC_IOS_API_KEY || '').trim();
+    let androidKey = (env.RC_ANDROID_API_KEY || '').trim();
+
+    // Last resort: read from Makefile (oldest projects).
+    if (!iosKey && !androidKey) {
+      const makefilePath = path.join(projectDir, 'Makefile');
+      if (await fs.pathExists(makefilePath)) {
+        try {
+          const content = await fs.readFile(makefilePath, 'utf8');
+          const activeLines = content.split('\n').filter((l) => !/^\s*#/.test(l)).join('\n');
+          const iosMatch = activeLines.match(/RC_IOS_API_KEY=([^\s\\]+)/);
+          const androidMatch = activeLines.match(/RC_ANDROID_API_KEY=([^\s\\]+)/);
+          iosKey = iosMatch ? iosMatch[1].trim() : '';
+          androidKey = androidMatch ? androidMatch[1].trim() : '';
+        } catch { /* ignore */ }
+      }
+    }
+
+    const iosEmpty = !iosKey || iosKey === 'xxx';
+    const androidEmpty = !androidKey || androidKey === 'xxx';
+    const iosTest = iosKey.startsWith('test_');
+    const androidTest = androidKey.startsWith('test_');
+
+    return {
+      ok: !iosEmpty && !androidEmpty,
+      legacy: true,
+      iosKey,
+      androidKey,
+      iosEmpty,
+      androidEmpty,
+      bothTest: iosTest && androidTest,
+      webhookUrl,
+    };
+  }
+
+  // New 3-key scheme.
+  const testOk = !!testKey && /^test_/.test(testKey);
+  const testBadPrefix = !!testKey && !/^test_/.test(testKey);
+  const iosProdOk = !!iosProdKey && /^appl_/.test(iosProdKey);
+  const iosProdBadPrefix = !!iosProdKey && !/^appl_/.test(iosProdKey);
+  const androidProdOk = !!androidProdKey && /^goog_/.test(androidProdKey);
+  const androidProdBadPrefix = !!androidProdKey && !/^goog_/.test(androidProdKey);
+
+  // OK if user can run at least one device flow end-to-end. Test alone is fine
+  // for development; prod-only configurations also work but skip the simulator.
+  const anyOk = testOk || iosProdOk || androidProdOk;
+
   return {
-    ok: !iosEmpty && !androidEmpty,
-    iosKey,
-    androidKey,
-    iosEmpty,
-    androidEmpty,
-    bothTest: iosTest && androidTest,
+    ok: anyOk,
+    legacy: false,
+    testKey,
+    iosProdKey,
+    androidProdKey,
+    testOk,
+    testBadPrefix,
+    iosProdOk,
+    iosProdBadPrefix,
+    androidProdOk,
+    androidProdBadPrefix,
+    testMissing: !testKey,
+    iosProdMissing: !iosProdKey,
+    androidProdMissing: !androidProdKey,
+    onlyTest: testOk && !iosProdOk && !androidProdOk,
     webhookUrl,
   };
 }
@@ -787,6 +868,7 @@ module.exports = {
   pubGet,
   slangGenerate,
   buildRunner,
+  dartFix,
   flutterfireConfigure,
   writeGoogleAuthOptions,
   writeGoogleIosUrlScheme,

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

@@ -33,6 +33,8 @@ const TEMPLATE_STRINGS = {
       supabase: '# Supabase',
       apiRest: '# API REST',
       revenuecat: '# RevenueCat',
+      revenuecatTest: '# Test Store key (test_xxx) — auto-used on simulator/emulator',
+      revenuecatProd: '# Production keys — auto-used on physical devices',
       sentry: '# Sentry (prod only)',
       mixpanel: '# Mixpanel',
       llmChat: '# LLM Chat — Cloud/Edge Function endpoint (API key stays on the server, not here)',
@@ -65,6 +67,8 @@ const TEMPLATE_STRINGS = {
       supabase: '# Supabase',
       apiRest: '# API REST',
       revenuecat: '# RevenueCat',
+      revenuecatTest: '# Chave Test Store (test_xxx) — usada automaticamente em simulador/emulador',
+      revenuecatProd: '# Chaves de produção — usadas automaticamente em dispositivo físico',
       sentry: '# Sentry (apenas prod)',
       mixpanel: '# Mixpanel',
       llmChat: '# LLM Chat — endpoint da Cloud/Edge Function (a chave de API fica no servidor, não aqui)',
@@ -97,6 +101,8 @@ const TEMPLATE_STRINGS = {
       supabase: '# Supabase',
       apiRest: '# API REST',
       revenuecat: '# RevenueCat',
+      revenuecatTest: '# Clave Test Store (test_xxx) — se usa automáticamente en simulador/emulador',
+      revenuecatProd: '# Claves de producción — se usan automáticamente en dispositivo físico',
       sentry: '# Sentry (solo prod)',
       mixpanel: '# Mixpanel',
       llmChat: '# LLM Chat — endpoint de Cloud/Edge Function (la clave de API queda en el servidor, no aquí)',

package/lib/utils/brand.js

@@ -10,22 +10,26 @@
  */
 
 const kleur = require('kleur');
-const gradient = require('gradient-string');
 const boxenPackage = require('boxen');
 const boxen = boxenPackage.default || boxenPackage;
 
-// Kept around for accents and boxes; the wordmark itself is now plain white.
-const BRAND_GRADIENT = ['#a78bfa', '#60a5fa'];
-const brandGradient = gradient(BRAND_GRADIENT);
-
+// Brand palette (memory/kasy_brand_colors.md). Single source of truth for the
+// CLI's only brand color: change BRAND_RGB and every spinner, header, logo and
+// success card across all commands updates automatically.
+//
+// kleur 4 in this repo doesn't ship `.hex()`, so we emit 24-bit ANSI directly.
+// Truecolor is supported by every macOS/Linux terminal we care about.
+const BRAND_RGB = { r: 210, g: 245, b: 30 }; // #D2F51E lime
+const paintLime = (text) => `\x1b[38;2;${BRAND_RGB.r};${BRAND_RGB.g};${BRAND_RGB.b}m${text}\x1b[0m`;
+const wordmark = paintLime;
 const DOMAIN_SUFFIX = kleur.gray('.dev');
 
 function printBanner(_tr) {
   const bar = kleur.gray('─────────────────────────────────────────────────');
   const logo = [
-    kleur.white('  ╦╔═ ╔═╗ ╔═╗ ╦ ╦'),
-    kleur.white('  ╠╩╗ ╠═╣ ╚═╗ ╚╦╝'),
-    `${kleur.white('  ╩ ╩ ╩ ╩ ╚═╝  ╩ ')} ${DOMAIN_SUFFIX}`,
+    wordmark('  ╦╔═ ╔═╗ ╔═╗ ╦ ╦'),
+    wordmark('  ╠╩╗ ╠═╣ ╚═╗ ╚╦╝'),
+    `${wordmark('  ╩ ╩ ╩ ╩ ╚═╝  ╩ ')} ${DOMAIN_SUFFIX}`,
   ].join('\n');
 
   console.log(`\n${bar}\n`);
@@ -35,18 +39,18 @@ function printBanner(_tr) {
 
 function printCompactHeader(_tr) {
   console.log('');
-  console.log(`  ${kleur.white('✦ KASY')}${DOMAIN_SUFFIX}`);
+  console.log(`  ${wordmark('✦ KASY')}${DOMAIN_SUFFIX}`);
   console.log('');
 }
 
 function successBox(title, body, { padding = 1, marginTop = 1, marginBottom = 1 } = {}) {
   return boxen(
-    `${brandGradient(`✦ ${title}`)}\n\n${body}`,
+    `${paintLime(`✦ ${title}`)}\n\n${body}`,
     {
       padding,
       margin: { top: marginTop, bottom: marginBottom, left: 1, right: 1 },
       borderStyle: 'round',
-      borderColor: 'cyan',
+      borderColor: 'gray',
     }
   );
 }
@@ -64,7 +68,7 @@ function infoBox(title, body, { padding = 1, marginTop = 1, marginBottom = 1 } =
 }
 
 module.exports = {
-  brandGradient,
+  paintLime,
   printBanner,
   printCompactHeader,
   successBox,

package/lib/utils/flutter-run.js

@@ -5,18 +5,29 @@
  * stage detection, elapsed timer, hot-reload stdin pass-through and SIGINT
  * forwarding stay consistent in one place.
  *
- * Flow:
- *  - Spawn flutter with piped stdio.
- *  - Show a Clack spinner with elapsed time, ticking every second.
- *  - As Flutter logs scroll, update the spinner message when we see a known
- *    stage marker (Gradle, Xcode, install, sync, etc.).
- *  - When Flutter signals "ready" (DAP key commands), flush buffered output,
- *    drop into stdio pass-through and pipe stdin so hot reload works.
- *  - On early exit, replay the buffer so the user can see the error.
+ * Two modes:
+ *
+ *  - spinner mode (default, TTY only): Spawn flutter with piped stdio. Show a
+ *    Clack spinner with elapsed time. Update the spinner message when we see a
+ *    known stage marker (Gradle, Xcode, install, sync, etc.). When Flutter
+ *    signals "ready" (DAP key commands), flush buffered output, drop into stdio
+ *    pass-through, and pipe stdin so hot reload works. On early exit, replay
+ *    the buffer so the user can see the error.
+ *
+ *  - raw mode (auto when stdout is not a TTY, or forced via `--raw`):
+ *    No spinner, no buffer. Flutter output is piped straight through so devs
+ *    and AI agents see the unmodified stream.
+ *
+ * In both modes we always tee the raw (ANSI-stripped) flutter output to
+ * `<project>/.kasy/run.log`. This gives AI assistants a stable, single-file
+ * source of truth for the last run, even when the spinner cosmetically rewrites
+ * the human terminal.
  */
 
 'use strict';
 
+const path = require('node:path');
+const fs = require('node:fs');
 const { spawn } = require('node:child_process');
 const kleur = require('kleur');
 const ui = require('./ui');
@@ -24,6 +35,35 @@ const ui = require('./ui');
 // Markers that tell us the initial build is done and the app is running.
 const FLUTTER_READY_RE = /Flutter run key commands\.|is listening on|VM Service|Dart VM service|To hot reload|Hot restart/i;
 
+// Strip ANSI escape sequences before persisting to the log file so the file
+// is grep-friendly for tooling (CI logs, agents, editors).
+const ANSI_RE = /\x1B(?:[@-Z\\-_]|\[[0-?]*[ -/]*[@-~])/g;
+
+function stripAnsi(text) {
+  return String(text).replace(ANSI_RE, '');
+}
+
+/**
+ * Open (and create the parent dir of) the persistent run log. Overwrites any
+ * previous run — we want "the last run", not an ever-growing history.
+ *
+ * Returns a write stream, or null when the file can't be created (read-only
+ * project, permissions, etc.) — failure here must never break `kasy run`.
+ */
+function openRunLog(projectDir) {
+  const logPath = path.join(projectDir, '.kasy', 'run.log');
+  try {
+    fs.mkdirSync(path.dirname(logPath), { recursive: true });
+    const stream = fs.createWriteStream(logPath, { flags: 'w' });
+    stream.on('error', () => {});
+    const header = `# kasy run — ${new Date().toISOString()}\n`;
+    stream.write(header);
+    return { stream, logPath };
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Map a chunk of Flutter output to a user-friendly stage label, or null
  * if the chunk doesn't carry any of the known markers.
@@ -66,10 +106,82 @@ function render(stageMessage, startTime) {
 }
 
 /**
- * Spawn `flutter` with the given args inside `projectDir`, surfacing progress
- * through a Clack spinner. Resolves on success, rejects on non-zero exit.
+ * Pretty-print the path used for the run log. Falls back to the absolute path
+ * when the log lives outside cwd (unusual, but keeps the message accurate).
  */
-function spawnFlutterWithSpinner(args, projectDir, t) {
+function relLogPath(logPath) {
+  const rel = path.relative(process.cwd(), logPath);
+  return rel.startsWith('..') ? logPath : rel;
+}
+
+/**
+ * Spawn `flutter` with the given args inside `projectDir`. When `options.raw`
+ * is true or stdout is not a TTY, runs in raw pass-through mode. Otherwise,
+ * shows a Clack spinner that buffers output until Flutter is ready.
+ *
+ * Resolves on success, rejects on non-zero exit. The log file path is always
+ * announced at the end so callers (and AI agents) can find the full output.
+ */
+function spawnFlutterWithSpinner(args, projectDir, t, options = {}) {
+  const raw = Boolean(options.raw) || !process.stdout.isTTY;
+  const log = openRunLog(projectDir);
+
+  if (raw) return spawnRaw(args, projectDir, t, log);
+  return spawnWithSpinner(args, projectDir, t, log);
+}
+
+/**
+ * Raw mode: no spinner, no buffer. Flutter stdout/stderr are piped straight
+ * through to the parent process, and tee'd (ANSI-stripped) into the log file.
+ *
+ * Stdin is forwarded directly so hot-reload keys (r/R/q) work without any
+ * raw-mode toggling — the user is already on a "dumb" terminal here.
+ */
+function spawnRaw(args, projectDir, t, log) {
+  return new Promise((resolve, reject) => {
+    const proc = spawn('flutter', args, {
+      cwd: projectDir,
+      stdio: ['inherit', 'pipe', 'pipe'],
+    });
+
+    const tee = (chunk, sink) => {
+      sink.write(chunk);
+      if (log) log.stream.write(stripAnsi(chunk.toString()));
+    };
+
+    proc.stdout.on('data', (c) => tee(c, process.stdout));
+    proc.stderr.on('data', (c) => tee(c, process.stderr));
+
+    const sigintHandler = () => { try { proc.kill('SIGINT'); } catch (_) {} };
+    process.on('SIGINT', sigintHandler);
+
+    const cleanup = () => {
+      process.off('SIGINT', sigintHandler);
+      if (log) log.stream.end();
+    };
+
+    proc.on('close', (code) => {
+      cleanup();
+      announceLog(log, t);
+      if (code === 0) resolve();
+      else reject(new Error(`flutter exited with code ${code}`));
+    });
+
+    proc.on('error', (err) => {
+      cleanup();
+      announceLog(log, t);
+      reject(err);
+    });
+  });
+}
+
+/**
+ * Spinner mode: buffer flutter output during the build phase, surface progress
+ * as friendly stage labels, then flush + pass-through once Flutter signals
+ * ready. On early exit, the buffer is replayed so the user sees the real
+ * Flutter error.
+ */
+function spawnWithSpinner(args, projectDir, t, log) {
   return new Promise((resolve, reject) => {
     const proc = spawn('flutter', args, {
       cwd: projectDir,
@@ -106,7 +218,12 @@ function spawnFlutterWithSpinner(args, projectDir, t) {
       }
     };
 
+    const teeLog = (chunk) => {
+      if (log) log.stream.write(stripAnsi(chunk.toString()));
+    };
+
     const handleStdout = (chunk) => {
+      teeLog(chunk);
       const text = chunk.toString();
       if (!ready) {
         buffer.push(chunk);
@@ -122,6 +239,7 @@ function spawnFlutterWithSpinner(args, projectDir, t) {
     };
 
     const handleStderr = (chunk) => {
+      teeLog(chunk);
       if (!ready) {
         buffer.push(chunk);
         if (FLUTTER_READY_RE.test(chunk.toString())) flushAndSwitch();
@@ -144,6 +262,7 @@ function spawnFlutterWithSpinner(args, projectDir, t) {
         process.stdin.unpipe(proc.stdin);
         process.stdin.pause();
       }
+      if (log) log.stream.end();
     };
 
     proc.on('close', (code) => {
@@ -152,6 +271,7 @@ function spawnFlutterWithSpinner(args, projectDir, t) {
         spinner.stop(t('run.spinner.failed'), 2);
         for (const chunk of buffer) process.stdout.write(chunk);
       }
+      announceLog(log, t);
       if (code === 0) resolve();
       else reject(new Error(`flutter exited with code ${code}`));
     });
@@ -159,15 +279,23 @@ function spawnFlutterWithSpinner(args, projectDir, t) {
     proc.on('error', (err) => {
       cleanup();
       if (!ready) spinner.stop(t('run.spinner.failed'), 2);
+      announceLog(log, t);
       reject(err);
     });
   });
 }
 
+function announceLog(log, t) {
+  if (!log) return;
+  const msg = t('run.log.savedTo', { path: relLogPath(log.logPath) });
+  console.log(kleur.dim(`\n  ${msg}`));
+}
+
 module.exports = {
   spawnFlutterWithSpinner,
   // Exported for tests and reuse in non-flutter spawn helpers.
   detectStage,
   formatElapsed,
   FLUTTER_READY_RE,
+  stripAnsi,
 };