kasy-cli 1.2.1

package/lib/commands/add.js

@@ -0,0 +1,777 @@
+const { exec } = require('node:child_process');
+const { promisify } = require('node:util');
+const path = require('node:path');
+const os = require('node:os');
+const fs = require('fs-extra');
+const pkg = require('../../package.json');
+const kleur = require('kleur');
+const prompts = require('prompts');
+const oraPackage = require('ora');
+const { createTranslator, detectDefaultLanguage } = require('../utils/i18n');
+const {
+  AVAILABLE_FEATURES,
+  FEATURES_PATCH_DIR,
+  normalizeFeature,
+  getVisibleFeatures,
+} = require('../scaffold/catalog');
+
+const KASY_AUDIENCE = process.env.KASY_INTERNAL === '1' ? 'internal' : 'public';
+const { applyPatch } = require('../scaffold/engine');
+const { writeRouter, writeNoOpAnalyticsApi, writeNoOpTrackingApi, writeNoOpAdminHomeWidgets, writeNoOpFeatureRequestRepository, writeMainDart, addPubspecDep, localizeReleaseDocs } = require('../scaffold/shared/generator-utils');
+const { toPackageName, buildTokens } = require('../scaffold/backends/firebase/tokens');
+
+const execAsync = promisify(exec);
+const ora = oraPackage.default || oraPackage;
+
+/** URL do endpoint LLM no app (espelha defineUpdates de llm_chat). */
+function resolveLlmChatEndpoint(answers, kitSetup) {
+  if (kitSetup?.backendProvider === 'api') {
+    return answers.llmEndpoint || 'YOUR_LLM_ENDPOINT';
+  }
+  if (kitSetup?.backendProvider === 'supabase') {
+    const ref = kitSetup.supabaseProjectId || 'YOUR_PROJECT_REF';
+    return `https://${ref}.supabase.co/functions/v1/llm-chat`;
+  }
+  const projectId = kitSetup?.firebaseProjectId || 'YOUR_PROJECT_ID';
+  const region = kitSetup?.functionsRegion || 'us-central1';
+  return `https://${region}-${projectId}.cloudfunctions.net/llmChat`;
+}
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+/**
+ * Reconstruct active modules from kit_setup.json + features.dart.
+ */
+async function getActiveModules(kitSetup, projectDir) {
+  const modules = [];
+  if (kitSetup.useSentry) modules.push('sentry');
+  if (kitSetup.analyticsProvider === 'mixpanel') modules.push('analytics');
+  if (kitSetup.withFacebookPixel) modules.push('facebook');
+  if (kitSetup.subscriptionModule) modules.push('revenuecat');
+  if (kitSetup.withOnboarding) modules.push('onboarding');
+  if (kitSetup.webCompat) modules.push('web');
+  if (kitSetup.feedbackModule) modules.push('feedback');
+
+  const featuresPath = path.join(projectDir, 'lib', 'core', 'config', 'features.dart');
+  if (await fs.pathExists(featuresPath)) {
+    const content = await fs.readFile(featuresPath, 'utf8');
+    if (/const bool withLlmChat\s*=\s*true/.test(content)) modules.push('llm_chat');
+  }
+
+  if (await fs.pathExists(path.join(projectDir, '.github', 'workflows'))) modules.push('ci');
+  if (await fs.pathExists(path.join(projectDir, 'lib', 'core', 'home_widgets', 'home_widget_service.dart'))) modules.push('widget');
+
+  return modules;
+}
+
+/**
+ * Toggle a single feature flag in features.dart (false → true).
+ * Only touches the specific flag — does not rewrite the whole file.
+ */
+async function enableFeatureFlag(projectDir, flag) {
+  const featuresPath = path.join(projectDir, 'lib', 'core', 'config', 'features.dart');
+  if (!(await fs.pathExists(featuresPath))) return;
+  let content = await fs.readFile(featuresPath, 'utf8');
+  content = content.replace(
+    new RegExp(`(const bool ${flag}\\s*=\\s*)false`, 'g'),
+    '$1true'
+  );
+  await fs.outputFile(featuresPath, content, 'utf8');
+}
+
+/**
+ * Add or update a dart-define in a launch.json args array.
+ * Preserves all other args. If the key already exists, replaces the value.
+ */
+function upsertDartDefine(args, key, value) {
+  const prefix = `--dart-define=${key}=`;
+  const filtered = args.filter((a) => !a.startsWith(prefix));
+  filtered.push(`${prefix}${value}`);
+  return filtered;
+}
+
+/**
+ * Add or update dart-define entries in the project Makefile.
+ * Only touches lines inside the DEFINES block; leaves everything else intact.
+ * If no DEFINES block exists (old project), appends one before .PHONY.
+ */
+async function ensureIosReleaseMakefile(projectDir) {
+  const makePath = path.join(projectDir, 'Makefile');
+  if (!(await fs.pathExists(makePath))) return;
+  let content = await fs.readFile(makePath, 'utf8');
+  if (content.includes('release-ios')) return;
+  content += `\n.PHONY: release-ios\nrelease-ios:\n\tbash scripts/release-ios.sh\n`;
+  await fs.outputFile(makePath, content, 'utf8');
+}
+
+async function ensureGitignoreKasyEnv(projectDir) {
+  const giPath = path.join(projectDir, '.gitignore');
+  if (!(await fs.pathExists(giPath))) return;
+  let content = await fs.readFile(giPath, 'utf8');
+  for (const line of ['.kasy/apple.env', '.kasy/codemagic.env']) {
+    if (!content.includes(line)) {
+      content += `\n${line}\n`;
+    }
+  }
+  await fs.outputFile(giPath, content, 'utf8');
+}
+
+async function updateMakefile(projectDir, defineUpdates) {
+  const makePath = path.join(projectDir, 'Makefile');
+  if (!(await fs.pathExists(makePath))) return;
+  let content = await fs.readFile(makePath, 'utf8');
+
+  for (const [key, value] of Object.entries(defineUpdates)) {
+    const flag = `--dart-define=${key}=`;
+    const lineRegex = new RegExp(`(  ${flag.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')})\\S*( \\\\)?`, 'g');
+    if (lineRegex.test(content)) {
+      // Replace existing value
+      content = content.replace(
+        new RegExp(`(  ${flag.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')})\\S*( \\\\)?`, 'g'),
+        (_, prefix, suffix) => `${prefix}${value}${suffix || ''}`
+      );
+    } else if (content.includes('DEFINES :=')) {
+      // Append inside existing DEFINES block — find last define line and add after
+      content = content.replace(
+        /(DEFINES :=[\s\S]*?)(\n\n\.PHONY)/,
+        (_, block, rest) => {
+          const trimmed = block.trimEnd().replace(/ \\$/, '');
+          return `${trimmed} \\\n  ${flag}${value}${rest}`;
+        }
+      );
+    } else {
+      // No DEFINES block yet — insert before .PHONY
+      content = content.replace(
+        /^(\.PHONY:)/m,
+        `DEFINES := \\\n  ${flag}${value}\n\n$1`
+      );
+    }
+  }
+
+  await fs.outputFile(makePath, content, 'utf8');
+}
+
+/**
+ * Update .vscode/launch.json by adding/updating dart-defines for a module.
+ * Applies the same change to both dev and prod configurations.
+ */
+async function updateLaunchJson(projectDir, defineUpdates) {
+  const launchPath = path.join(projectDir, '.vscode', 'launch.json');
+  if (!(await fs.pathExists(launchPath))) return;
+  const launch = await fs.readJson(launchPath);
+
+  for (const config of launch.configurations || []) {
+    if (!Array.isArray(config.args)) continue;
+    for (const [key, value] of Object.entries(defineUpdates)) {
+      config.args = upsertDartDefine(config.args, key, value);
+    }
+  }
+
+  await fs.outputFile(launchPath, JSON.stringify(launch, null, 2) + '\n', 'utf8');
+}
+
+/**
+ * Append module vars to .env.example (only if not already present).
+ */
+async function appendEnvExample(projectDir, lines) {
+  const envPath = path.join(projectDir, '.env.example');
+  if (!(await fs.pathExists(envPath))) return;
+  const existing = await fs.readFile(envPath, 'utf8');
+  const toAdd = lines.filter((l) => !existing.includes(l.split('=')[0]));
+  if (toAdd.length === 0) return;
+  await fs.appendFile(envPath, '\n' + toAdd.join('\n') + '\n', 'utf8');
+}
+
+/**
+ * Append module vars to .env (only if file exists and key is missing).
+ */
+async function appendEnvFile(projectDir, lines) {
+  const envPath = path.join(projectDir, '.env');
+  if (!(await fs.pathExists(envPath))) return;
+  const existing = await fs.readFile(envPath, 'utf8');
+  const toAdd = lines.filter((l) => !existing.includes(l.split('=')[0]));
+  if (toAdd.length === 0) return;
+  await fs.appendFile(envPath, '\n' + toAdd.join('\n') + '\n', 'utf8');
+}
+
+/**
+ * Update kit_setup.json flags for the newly added module.
+ */
+function applyKitSetupFlag(config, module, answers) {
+  switch (module) {
+    case 'sentry':
+      config.useSentry = true;
+      break;
+    case 'analytics':
+      config.analyticsProvider = 'mixpanel';
+      break;
+    case 'facebook':
+      config.withFacebookPixel = true;
+      break;
+    case 'revenuecat':
+      config.subscriptionModule = true;
+      if (answers.revenuecatWeb) config.revenuecatWeb = true;
+      break;
+    case 'onboarding':
+      config.withOnboarding = true;
+      break;
+    case 'web':
+      config.webCompat = true;
+      break;
+    case 'feedback':
+      config.feedbackModule = true;
+      break;
+    case 'llm_chat':
+    case 'widget':
+    case 'ci':
+      // controlled by features.dart / patch — no extra kit_setup flag needed
+      break;
+    default:
+      break;
+  }
+}
+
+// ── Module definitions ────────────────────────────────────────────────────────
+
+const MODULE_META = {
+  sentry: {
+    promptKeys: ['sentryDsn'],
+    defineUpdates: (a) => ({ SENTRY_DSN: a.sentryDsn || 'YOUR_SENTRY_DSN' }),
+    envLines: (a) => [`SENTRY_DSN=${a.sentryDsn || 'YOUR_SENTRY_DSN'}`],
+    featureFlag: null,
+    pubspecDeps: { 'sentry_flutter': '^9.14.0' },
+  },
+  analytics: {
+    promptKeys: ['mixpanelToken'],
+    defineUpdates: (a) => ({ MIXPANEL_TOKEN: a.mixpanelToken || 'YOUR_MIXPANEL_TOKEN' }),
+    envLines: (a) => [`MIXPANEL_TOKEN=${a.mixpanelToken || 'YOUR_MIXPANEL_TOKEN'}`],
+    featureFlag: null,
+    pubspecDeps: { 'mixpanel_flutter': '^2.5.0' },
+  },
+  facebook: {
+    promptKeys: [],
+    defineUpdates: () => ({}),
+    envLines: () => [],
+    featureFlag: null,
+    note: 'add.note.facebook',
+    pubspecDeps: { 'facebook_app_events': '^0.24.0', 'flutter_facebook_auth': '^7.1.5' },
+  },
+  revenuecat: {
+    promptKeys: ['rcAndroidKey', 'rcIosKey'],
+    defineUpdates: (a) => ({
+      RC_ANDROID_API_KEY: a.rcAndroidKey || 'YOUR_REVENUECAT_ANDROID_KEY',
+      RC_IOS_API_KEY: a.rcIosKey || 'YOUR_REVENUECAT_IOS_KEY',
+    }),
+    envLines: (a) => [
+      `RC_ANDROID_API_KEY=${a.rcAndroidKey || 'YOUR_REVENUECAT_ANDROID_KEY'}`,
+      `RC_IOS_API_KEY=${a.rcIosKey || 'YOUR_REVENUECAT_IOS_KEY'}`,
+    ],
+    featureFlag: null,
+    pubspecDeps: {},
+  },
+  onboarding: {
+    promptKeys: [],
+    defineUpdates: () => ({}),
+    envLines: () => [],
+    featureFlag: 'withOnboarding',
+    pubspecDeps: {},
+  },
+  web: {
+    promptKeys: [],
+    defineUpdates: () => ({}),
+    envLines: () => [],
+    featureFlag: 'withWeb',
+    pubspecDeps: {},
+  },
+  feedback: {
+    promptKeys: [],
+    defineUpdates: () => ({}),
+    envLines: () => [],
+    featureFlag: 'withFeedback',
+    pubspecDeps: {},
+  },
+  llm_chat: {
+    promptKeys: ['llmProvider', 'llmSystemPrompt', 'llmApiKey'],
+    defineUpdates: (a, kitSetup) => ({
+      LLM_CHAT_ENDPOINT: resolveLlmChatEndpoint(a, kitSetup),
+    }),
+    envLines: (a, kitSetup) => [
+      `LLM_CHAT_ENDPOINT=${resolveLlmChatEndpoint(a, kitSetup)}`,
+    ],
+    featureFlag: 'withLlmChat',
+    pubspecDeps: {},
+  },
+  widget: {
+    promptKeys: [],
+    defineUpdates: () => ({}),
+    envLines: () => [],
+    featureFlag: null,
+    pubspecDeps: { 'home_widget': '^0.9.0', 'background_fetch': '^1.5.0' },
+  },
+  ci: {
+    promptKeys: [],
+    defineUpdates: () => ({}),
+    envLines: () => [],
+    featureFlag: null,
+    pubspecDeps: {},
+  },
+};
+
+const PROMPT_QUESTIONS = {
+  sentryDsn: (t) => ({
+    type: 'text',
+    name: 'sentryDsn',
+    message: t('add.prompt.sentryDsn'),
+    initial: '',
+  }),
+  mixpanelToken: (t) => ({
+    type: 'text',
+    name: 'mixpanelToken',
+    message: t('add.prompt.mixpanelToken'),
+    initial: '',
+  }),
+  rcAndroidKey: (t) => ({
+    type: 'text',
+    name: 'rcAndroidKey',
+    message: t('add.prompt.rcAndroidKey'),
+    initial: '',
+  }),
+  rcIosKey: (t) => ({
+    type: 'text',
+    name: 'rcIosKey',
+    message: t('add.prompt.rcIosKey'),
+    initial: '',
+  }),
+  llmProvider: (t) => ({
+    type: 'select',
+    name: 'llmProvider',
+    message: t('add.prompt.llmProvider'),
+    choices: [
+      { title: 'OpenAI (gpt-4o-mini)', value: 'openai' },
+      { title: 'Google Gemini (gemini-1.5-flash)', value: 'gemini' },
+    ],
+    initial: 0,
+  }),
+  llmSystemPrompt: (t) => ({
+    type: 'text',
+    name: 'llmSystemPrompt',
+    message: t('add.prompt.llmSystemPrompt'),
+    initial: '',
+  }),
+  llmApiKey: (t) => ({
+    type: 'text',
+    name: 'llmApiKey',
+    message: t('add.prompt.llmApiKey'),
+    initial: '',
+  }),
+  llmEndpoint: (t) => ({
+    type: 'text',
+    name: 'llmEndpoint',
+    message: t('add.prompt.llmEndpoint'),
+    initial: '',
+  }),
+};
+
+// ── LLM Chat post-add: copy edge function, set secrets, write functions/.env ──
+
+const SUPABASE_EDGE_FUNCTIONS_SOURCE = path.join(
+  __dirname, '..', 'scaffold', 'backends', 'supabase', 'edge-functions'
+);
+
+async function postAddLlmChat(projectDir, kitSetup, answers, t) {
+  const backend = kitSetup?.backendProvider ?? 'firebase';
+  const apiKey = answers.llmApiKey?.trim() || '';
+  const provider = answers.llmProvider || 'openai';
+  const systemPrompt = answers.llmSystemPrompt?.trim() || '';
+  const projectRef = kitSetup?.supabaseProjectId || '';
+
+  // 1. Firebase: write functions/.env (non-secret vars read by Cloud Functions runtime)
+  if (backend === 'firebase') {
+    const envPath = path.join(projectDir, 'functions', '.env');
+    const lines = [`LLM_PROVIDER=${provider}`];
+    if (systemPrompt) lines.push(`LLM_SYSTEM_PROMPT=${systemPrompt}`);
+    const existing = (await fs.pathExists(envPath)) ? await fs.readFile(envPath, 'utf8') : '';
+    const toAdd = lines.filter((l) => !existing.includes(l.split('=')[0]));
+    if (toAdd.length > 0) {
+      await fs.appendFile(envPath, (existing ? '\n' : '') + toAdd.join('\n') + '\n', 'utf8');
+    }
+  }
+
+  // 1b. Supabase: copy Edge Function file + set ALL vars as Supabase Secrets
+  //    (Edge Functions deployed on Supabase read from Deno.env.get() = Supabase Secrets,
+  //     NOT from local .env files — so LLM_PROVIDER and LLM_SYSTEM_PROMPT must be secrets too)
+  if (backend === 'supabase') {
+    // Copy llm-chat edge function into the project if not already present
+    const edgeFnSrc = path.join(SUPABASE_EDGE_FUNCTIONS_SOURCE, 'llm-chat');
+    const edgeFnDest = path.join(projectDir, 'supabase', 'functions', 'llm-chat');
+    if (await fs.pathExists(edgeFnSrc) && !(await fs.pathExists(edgeFnDest))) {
+      await fs.copy(edgeFnSrc, edgeFnDest);
+    }
+  }
+
+  // 2. Set API key as secret (skip if blank)
+  if (!apiKey) {
+    console.log(kleur.yellow(`\n  ${t('add.llm_chat.skipSecret')}\n`));
+    return { deployOk: false, deployAttempted: false };
+  }
+
+  let secretsOk = false;
+  const refFlag = backend === 'supabase' && projectRef ? ` --project-ref ${projectRef}` : '';
+
+  if (backend === 'firebase') {
+    const spinner = ora(t('add.llm_chat.settingSecret')).start();
+    try {
+      // Write to temp file — avoids trailing newline (echo) and shell injection risks
+      const tmpFile = path.join(os.tmpdir(), `llm_api_key_${Date.now()}.tmp`);
+      await fs.outputFile(tmpFile, apiKey, 'utf8');
+      await execAsync(`firebase functions:secrets:set LLM_API_KEY --data-file="${tmpFile}"`, { cwd: projectDir });
+      await fs.remove(tmpFile);
+      spinner.succeed(t('add.llm_chat.secretSet'));
+      secretsOk = true;
+    } catch {
+      spinner.warn(t('add.llm_chat.secretFailed'));
+      console.log(kleur.dim(`  Run manually: firebase functions:secrets:set LLM_API_KEY`));
+    }
+  } else if (backend === 'supabase') {
+    const spinner = ora(t('add.llm_chat.settingSecret')).start();
+    // Set LLM_API_KEY, LLM_PROVIDER and LLM_SYSTEM_PROMPT all as Supabase Secrets.
+    // Deployed Edge Functions read from Deno.env.get() = Supabase Secrets, NOT from .env files.
+    const esc = (v) => String(v).replace(/"/g, '\\"');
+    const toSet = [
+      { name: 'LLM_API_KEY', value: apiKey },
+      { name: 'LLM_PROVIDER', value: provider },
+      ...(systemPrompt ? [{ name: 'LLM_SYSTEM_PROMPT', value: systemPrompt }] : []),
+    ];
+    let allOk = true;
+    for (const { name, value } of toSet) {
+      const r = await execAsync(
+        `supabase secrets set ${name}="${esc(value)}"${refFlag}`,
+        { cwd: projectDir }
+      ).catch((e) => ({ ok: false, error: e.message }));
+      if (r && r.ok === false) allOk = false;
+    }
+    if (allOk) {
+      spinner.succeed(t('add.llm_chat.secretSet'));
+      secretsOk = true;
+    } else {
+      spinner.warn(t('add.llm_chat.secretFailed'));
+      console.log(kleur.dim(`  Run manually: supabase secrets set LLM_API_KEY=YOUR_KEY LLM_PROVIDER=${provider}${refFlag}`));
+    }
+  }
+
+  // 3. Deploy the LLM function automatically
+  if (backend === 'api') return { deployOk: false, deployAttempted: false };
+
+  const deploySpinner = ora(t('add.llm_chat.deploying')).start();
+  try {
+    if (backend === 'firebase') {
+      await execAsync('firebase deploy --only functions:llmChat', { cwd: projectDir, timeout: 180_000 });
+    } else if (backend === 'supabase') {
+      await execAsync(`supabase functions deploy llm-chat --no-verify-jwt${refFlag}`, { cwd: projectDir, timeout: 180_000 });
+    }
+    deploySpinner.succeed(t('add.llm_chat.deployed'));
+    return { deployOk: true, deployAttempted: true };
+  } catch {
+    deploySpinner.warn(t('add.llm_chat.deployFailed'));
+    if (backend === 'firebase') {
+      console.log(kleur.dim(`  Run manually: firebase deploy --only functions:llmChat`));
+    } else {
+      console.log(kleur.dim(`  Run manually: supabase functions deploy llm-chat --no-verify-jwt${refFlag}`));
+    }
+    return { deployOk: false, deployAttempted: true };
+  }
+}
+
+// ── List command ──────────────────────────────────────────────────────────────
+
+async function listModules(projectDir, t) {
+  console.log(kleur.bold(`\n${t('add.list.title')}\n`));
+
+  let activeModules = [];
+  const kitSetupPath = path.join(projectDir, 'kit_setup.json');
+  if (await fs.pathExists(kitSetupPath)) {
+    try {
+      const config = await fs.readJson(kitSetupPath);
+      activeModules = await getActiveModules(config, projectDir);
+    } catch {
+      // ignore
+    }
+  }
+
+  for (const feature of getVisibleFeatures({ audience: KASY_AUDIENCE })) {
+    const active = activeModules.includes(feature.id);
+    const badge = feature.status === 'internal' ? kleur.yellow(' [beta]') : '';
+    const icon = active ? kleur.green('✓') : kleur.dim('○');
+    const label = active ? kleur.green(feature.id) : kleur.white(feature.id);
+    console.log(`  ${icon}  ${label}${badge}`);
+  }
+  console.log('');
+}
+
+// ── Main command ──────────────────────────────────────────────────────────────
+
+async function runAdd(module, options = {}) {
+  const t = createTranslator(options.language || detectDefaultLanguage());
+  const projectDir = path.resolve(options.directory || '.');
+
+  // --list flag
+  if (options.list) {
+    await listModules(projectDir, t);
+    return;
+  }
+
+  if (!module) {
+    console.log(kleur.yellow(t('add.error.noModule')));
+    await listModules(projectDir, t);
+    return;
+  }
+
+  // 1. Must be inside a kasy project
+  const kitSetupPath = path.join(projectDir, 'kit_setup.json');
+  if (!(await fs.pathExists(kitSetupPath))) {
+    throw new Error(t('add.error.notKasyProject'));
+  }
+
+  const kitSetup = await fs.readJson(kitSetupPath);
+  try {
+    const kasyConfig = await fs.readJson(path.join(projectDir, '.kasy', 'config.json'));
+    if (kasyConfig.functionsRegion) kitSetup.functionsRegion = kasyConfig.functionsRegion;
+  } catch (_) {}
+
+  const moduleLower = String(module).trim().toLowerCase();
+  if (moduleLower === 'ios-release' || moduleLower === 'ios_release' || moduleLower === 'iosrelease') {
+    const scriptPath = path.join(projectDir, 'scripts', 'release-ios.sh');
+    if (await fs.pathExists(scriptPath)) {
+      console.log(kleur.yellow(`\n${t('add.iosRelease.already')}\n`));
+      return;
+    }
+    const patchDir = path.join(FEATURES_PATCH_DIR, 'ios-release');
+    if (!(await fs.pathExists(patchDir))) {
+      throw new Error(t('add.error.unknownModule', { module, list: 'ios-release' }));
+    }
+    const { tokens, pathReplacements } = buildTokens({
+      appName: kitSetup.appName,
+      bundleId: kitSetup.bundleId,
+    });
+    await applyPatch(patchDir, projectDir, tokens, pathReplacements);
+    await localizeReleaseDocs(projectDir, options.language || detectDefaultLanguage());
+    await ensureIosReleaseMakefile(projectDir);
+    await ensureGitignoreKasyEnv(projectDir);
+    console.log(kleur.green(`\n✓ ${t('add.iosRelease.success')}\n`));
+    console.log(kleur.cyan(`  kasy ios configure\n`));
+    return;
+  }
+
+  // 2. Validate module name
+  const normalized = normalizeFeature(module);
+  if (!normalized) {
+    throw new Error(
+      t('add.error.unknownModule', {
+        module,
+        list: getVisibleFeatures({ audience: KASY_AUDIENCE }).map((f) => f.id).join(', '),
+      })
+    );
+  }
+
+  // 3. Check if already active
+  const activeModules = await getActiveModules(kitSetup, projectDir);
+  if (activeModules.includes(normalized)) {
+    // llm_chat can be re-run to reconfigure credentials even when already active
+    if (normalized !== 'llm_chat') {
+      console.log(kleur.yellow(`\n${t('add.alreadyActive', { module: normalized })}\n`));
+      return;
+    }
+    console.log(kleur.yellow(`\n${t('add.llm_chat.reconfigure')}\n`));
+    // Skip to credential-only flow: prompt → postAdd → done
+    const answers = {};
+    if (!options.yes) {
+      console.log('');
+      for (const key of ['llmProvider', 'llmSystemPrompt', 'llmApiKey']) {
+        const question = PROMPT_QUESTIONS[key]?.(t);
+        if (!question) continue;
+        const response = await prompts(question, { onCancel: () => { throw new Error(t('add.cancelled')); } });
+        answers[key] = response[key] ?? '';
+      }
+      if (kitSetup.backendProvider === 'api') {
+        const response = await prompts(PROMPT_QUESTIONS.llmEndpoint(t), { onCancel: () => { throw new Error(t('add.cancelled')); } });
+        answers.llmEndpoint = response.llmEndpoint || '';
+      }
+    }
+    const defines = MODULE_META.llm_chat.defineUpdates(answers, kitSetup);
+    if (Object.keys(defines).length > 0) {
+      await updateLaunchJson(projectDir, defines);
+      await updateMakefile(projectDir, defines);
+      const envLines = MODULE_META.llm_chat.envLines(answers, kitSetup);
+      if (envLines.length > 0) {
+        await appendEnvExample(projectDir, envLines);
+        await appendEnvFile(projectDir, envLines);
+      }
+    }
+    const { deployOk, deployAttempted } = await postAddLlmChat(projectDir, kitSetup, answers, t);
+    const backend = kitSetup?.backendProvider ?? 'firebase';
+    const needsManualDeploy = deployAttempted && !deployOk;
+    if (backend === 'firebase') {
+      console.log(kleur.cyan(t(needsManualDeploy ? 'add.llm_chat.nextSteps.firebase.deployFailed' : 'add.llm_chat.nextSteps.firebase')));
+    } else if (backend === 'supabase') {
+      console.log(kleur.cyan(t(needsManualDeploy ? 'add.llm_chat.nextSteps.supabase.deployFailed' : 'add.llm_chat.nextSteps.supabase')));
+    } else {
+      console.log(kleur.cyan(t('add.llm_chat.nextSteps.api')));
+    }
+    return;
+  }
+
+  const meta = MODULE_META[normalized] || { promptKeys: [], defineUpdates: () => ({}), envLines: () => [], featureFlag: null };
+
+  // 4. Prompt for API keys (skip if --yes)
+  const answers = {};
+  if (!options.yes && meta.promptKeys.length > 0) {
+    console.log('');
+    for (const key of meta.promptKeys) {
+      const question = PROMPT_QUESTIONS[key]?.(t);
+      if (!question) continue;
+      const response = await prompts(question, {
+        onCancel: () => { throw new Error(t('add.cancelled')); },
+      });
+      answers[key] = response[key] ?? '';
+    }
+    // Extra prompt for API backend (custom LLM endpoint)
+    if (normalized === 'llm_chat' && kitSetup.backendProvider === 'api') {
+      const response = await prompts(PROMPT_QUESTIONS.llmEndpoint(t), {
+        onCancel: () => { throw new Error(t('add.cancelled')); },
+      });
+      answers.llmEndpoint = response.llmEndpoint || '';
+    }
+  }
+
+  console.log(kleur.bold(`\n${t('add.applying', { module: normalized })}\n`));
+
+  // 5. Enable feature flag in features.dart
+  if (meta.featureFlag) {
+    await enableFeatureFlag(projectDir, meta.featureFlag);
+  }
+
+  // 6. Update .vscode/launch.json and Makefile dart-defines
+  const defines = meta.defineUpdates(answers, kitSetup);
+  if (Object.keys(defines).length > 0) {
+    await updateLaunchJson(projectDir, defines);
+    await updateMakefile(projectDir, defines);
+  }
+
+  // 7. Append to .env.example
+  const envLines = meta.envLines(answers, kitSetup);
+  if (envLines.length > 0) {
+    await appendEnvExample(projectDir, envLines);
+    await appendEnvFile(projectDir, envLines);
+  }
+
+  // 8. Apply patch if it exists under features/<module>/
+  const patchDir = path.join(FEATURES_PATCH_DIR, normalized);
+  if (await fs.pathExists(patchDir)) {
+    const spinner = ora(t('add.applyingPatch')).start();
+    try {
+      const { tokens: patchTokens, pathReplacements: patchPathReplacements } = buildTokens({
+        appName: kitSetup.appName,
+        bundleId: kitSetup.bundleId,
+      });
+      await applyPatch(patchDir, projectDir, patchTokens, patchPathReplacements);
+      spinner.succeed(t('add.patchApplied'));
+    } catch (err) {
+      spinner.fail(t('add.patchFailed'));
+      throw err;
+    }
+  }
+
+  // 8b. Add pubspec dependencies for this module
+  const pubspecDeps = meta.pubspecDeps || {};
+  if (Object.keys(pubspecDeps).length > 0) {
+    for (const [depName, depVersion] of Object.entries(pubspecDeps)) {
+      await addPubspecDep(projectDir, depName, depVersion);
+    }
+  }
+
+  // 9. Update kit_setup.json
+  applyKitSetupFlag(kitSetup, normalized, answers);
+  kitSetup.cliVersion = pkg.version;
+  await fs.outputFile(kitSetupPath, JSON.stringify(kitSetup, null, 2) + '\n', 'utf8');
+
+  // 9b. Regenerate router.dart with updated module list
+  try {
+    const updatedModules = await getActiveModules(kitSetup, projectDir);
+    const packageName = toPackageName(kitSetup.appName);
+    await writeRouter(projectDir, updatedModules, packageName);
+  } catch {
+    // Non-fatal: router regeneration failure does not block pub get
+  }
+
+  // 9c. Regenerate main.dart and no-op stubs with updated module list
+  try {
+    const updatedModules = await getActiveModules(kitSetup, projectDir);
+    const packageName = toPackageName(kitSetup.appName);
+    if (!updatedModules.includes('analytics')) {
+      await writeNoOpAnalyticsApi(projectDir, packageName);
+    }
+    if (!updatedModules.includes('facebook')) {
+      await writeNoOpTrackingApi(projectDir, packageName);
+    }
+    if (!updatedModules.includes('feedback')) {
+      await writeNoOpFeatureRequestRepository(projectDir, packageName);
+    }
+    if (!updatedModules.includes('widget')) {
+      await writeNoOpAdminHomeWidgets(projectDir);
+    }
+    await writeMainDart(projectDir, kitSetup.backendProvider, updatedModules, packageName, {});
+  } catch {
+    // Non-fatal: main.dart regeneration failure does not block pub get
+  }
+
+  // 10. flutter pub get
+  {
+    const spinner = ora(t('add.pubGet')).start();
+    try {
+      await execAsync('flutter pub get', { cwd: projectDir, timeout: 300_000 });
+      spinner.succeed(t('add.pubGetDone'));
+    } catch {
+      spinner.warn(t('add.pubGetFailed'));
+    }
+  }
+
+  // 11. build_runner (only when needed: features with codegen)
+  const needsBuildRunner = ['revenuecat', 'analytics', 'sentry', 'onboarding', 'llm_chat', 'feedback'].includes(normalized);
+  if (needsBuildRunner) {
+    const spinner = ora(t('add.buildRunner')).start();
+    try {
+      await execAsync('dart run build_runner build --delete-conflicting-outputs', { cwd: projectDir, timeout: 600_000 });
+      spinner.succeed(t('add.buildRunnerDone'));
+    } catch {
+      spinner.warn(t('add.buildRunnerFailed'));
+    }
+  }
+
+  // 12. LLM Chat: set secrets, write env vars, and deploy
+  let llmDeployResult = null;
+  if (normalized === 'llm_chat') {
+    llmDeployResult = await postAddLlmChat(projectDir, kitSetup, answers, t);
+  }
+
+  // Show note if any
+  if (meta.note) {
+    console.log(kleur.dim(`\n  ${t(meta.note)}\n`));
+  }
+
+  console.log(kleur.green(`\n✓ ${t('add.success', { module: normalized })}\n`));
+
+  // LLM Chat: show next steps (adjust based on whether deploy succeeded)
+  if (normalized === 'llm_chat') {
+    const backend = kitSetup?.backendProvider ?? 'firebase';
+    const needsManualDeploy = llmDeployResult?.deployAttempted && !llmDeployResult?.deployOk;
+    if (backend === 'firebase') {
+      console.log(kleur.cyan(t(needsManualDeploy ? 'add.llm_chat.nextSteps.firebase.deployFailed' : 'add.llm_chat.nextSteps.firebase')));
+    } else if (backend === 'supabase') {
+      console.log(kleur.cyan(t(needsManualDeploy ? 'add.llm_chat.nextSteps.supabase.deployFailed' : 'add.llm_chat.nextSteps.supabase')));
+    } else {
+      console.log(kleur.cyan(t('add.llm_chat.nextSteps.api')));
+    }
+  }
+}
+
+module.exports = { runAdd };