kasy-cli 1.13.0 → 1.15.0

package/lib/utils/debug.js

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

package/lib/utils/flutter-run.js

@@ -0,0 +1,173 @@
+/**
+ * Shared launcher for `flutter run` invocations.
+ *
+ * Both `kasy run` and `kasy reset` (reinstall step) call this so the spinner,
+ * 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.
+ */
+
+'use strict';
+
+const { spawn } = require('node:child_process');
+const kleur = require('kleur');
+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;
+
+/**
+ * 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.
+ */
+function detectStage(text, t) {
+  if (/Running Gradle task 'assembleDebug'/.test(text)) {
+    return t('run.stage.gradleFirstTime');
+  }
+  if (/Running Gradle task/.test(text)) {
+    return t('run.stage.gradle');
+  }
+  if (/Running Xcode build/.test(text)) {
+    return t('run.stage.xcode');
+  }
+  if (/Running pod install/i.test(text)) {
+    return t('run.stage.pods');
+  }
+  if (/Installing build\/.+\.(apk|ipa|app)/i.test(text)) {
+    return t('run.stage.installing');
+  }
+  if (/Syncing files to device/i.test(text)) {
+    return t('run.stage.syncing');
+  }
+  if (/BUILD SUCCESSFUL/.test(text)) {
+    return t('run.stage.buildSuccess');
+  }
+  return null;
+}
+
+function formatElapsed(startTime) {
+  const elapsed = Math.floor((Date.now() - startTime) / 1000);
+  if (elapsed < 60) return `${elapsed}s`;
+  const m = Math.floor(elapsed / 60);
+  const s = elapsed % 60;
+  return `${m}m ${s}s`;
+}
+
+function render(stageMessage, startTime) {
+  return `${stageMessage}  ${kleur.dim(`[${formatElapsed(startTime)}]`)}`;
+}
+
+/**
+ * Spawn `flutter` with the given args inside `projectDir`, surfacing progress
+ * through a Clack spinner. Resolves on success, rejects on non-zero exit.
+ */
+function spawnFlutterWithSpinner(args, projectDir, t) {
+  return new Promise((resolve, reject) => {
+    const proc = spawn('flutter', args, {
+      cwd: projectDir,
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+
+    const spinner = ui.spinner();
+    const startTime = Date.now();
+    let stageMessage = t('run.spinner.building');
+    let ready = false;
+    const buffer = [];
+
+    spinner.start(render(stageMessage, startTime));
+
+    // Tick the elapsed time every second while still building. Once ready,
+    // the spinner is gone and we stop ticking.
+    const tick = setInterval(() => {
+      if (!ready) spinner.message(render(stageMessage, startTime));
+    }, 1000);
+
+    const flushAndSwitch = () => {
+      if (ready) return;
+      ready = true;
+      clearInterval(tick);
+      const total = formatElapsed(startTime);
+      spinner.stop(`${t('run.spinner.ready')}  ${kleur.dim(`[${total}]`)}`);
+      for (const chunk of buffer) process.stdout.write(chunk);
+      buffer.length = 0;
+      // Pipe stdin so the user can type r / R / q to control Flutter.
+      if (process.stdin.isTTY) {
+        try { process.stdin.setRawMode(true); } catch (_) {}
+        process.stdin.resume();
+        process.stdin.pipe(proc.stdin);
+      }
+    };
+
+    const handleStdout = (chunk) => {
+      const text = chunk.toString();
+      if (!ready) {
+        buffer.push(chunk);
+        const nextStage = detectStage(text, t);
+        if (nextStage && nextStage !== stageMessage) {
+          stageMessage = nextStage;
+          spinner.message(render(stageMessage, startTime));
+        }
+        if (FLUTTER_READY_RE.test(text)) flushAndSwitch();
+      } else {
+        process.stdout.write(chunk);
+      }
+    };
+
+    const handleStderr = (chunk) => {
+      if (!ready) {
+        buffer.push(chunk);
+        if (FLUTTER_READY_RE.test(chunk.toString())) flushAndSwitch();
+      } else {
+        process.stderr.write(chunk);
+      }
+    };
+
+    proc.stdout.on('data', handleStdout);
+    proc.stderr.on('data', handleStderr);
+
+    const sigintHandler = () => { try { proc.kill('SIGINT'); } catch (_) {} };
+    process.on('SIGINT', sigintHandler);
+
+    const cleanup = () => {
+      clearInterval(tick);
+      process.off('SIGINT', sigintHandler);
+      if (process.stdin.isTTY) {
+        try { process.stdin.setRawMode(false); } catch (_) {}
+        process.stdin.unpipe(proc.stdin);
+        process.stdin.pause();
+      }
+    };
+
+    proc.on('close', (code) => {
+      cleanup();
+      if (!ready) {
+        spinner.stop(t('run.spinner.failed'), 2);
+        for (const chunk of buffer) process.stdout.write(chunk);
+      }
+      if (code === 0) resolve();
+      else reject(new Error(`flutter exited with code ${code}`));
+    });
+
+    proc.on('error', (err) => {
+      cleanup();
+      if (!ready) spinner.stop(t('run.spinner.failed'), 2);
+      reject(err);
+    });
+  });
+}
+
+module.exports = {
+  spawnFlutterWithSpinner,
+  // Exported for tests and reuse in non-flutter spawn helpers.
+  detectStage,
+  formatElapsed,
+  FLUTTER_READY_RE,
+};

package/lib/utils/friendly-error.js

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