mixdog 0.7.8 → 0.7.11

package/setup/install.mjs

@@ -1,384 +1,574 @@
-#!/usr/bin/env node
-// install.mjs — one-shot bootstrapper that registers the mixdog plugin in the
-// user's Claude Code settings so it auto-loads on the next session start.
-//
-// Run via:  npx mixdog | mixdog install | mixdog-install   (after publish)
-//       or:  node setup/install.mjs             (from a checkout)
-//
-// It merges two keys into the user-scope settings file (preserving everything
-// else that is already there):
-//   extraKnownMarketplaces["trib-plugin"] -> the GitHub marketplace source
-//   enabledPlugins["mixdog@trib-plugin"]  -> true
-//
-// After it runs, the user restarts Claude Code (or runs /reload-plugins) and
-// mixdog is already present — there is no separate /plugin install step.
-
-import {
-  readFileSync,
-  writeFileSync,
-  existsSync,
-  mkdirSync,
-  copyFileSync,
-  mkdtempSync,
-  rmSync,
-} from 'node:fs';
-import { join, dirname } from 'node:path';
-import { homedir, tmpdir } from 'node:os';
-import { realpathSync } from 'node:fs';
-import { fileURLToPath } from 'node:url';
-import { createInterface } from 'node:readline';
-import { spawn, spawnSync } from 'node:child_process';
-import { DEFAULT_MARKETPLACE, DEFAULT_PLUGIN } from '../src/shared/plugin-paths.mjs';
-import { resolveClaudeExecutable } from './locate-claude.mjs';
-import { createSpinner } from './tui.mjs';
-
-const MARKETPLACE = DEFAULT_MARKETPLACE;
-const PLUGIN_REF = `${DEFAULT_PLUGIN}@${DEFAULT_MARKETPLACE}`;
-const REPO = 'trib-plugin/mixdog';        // github owner/repo
-const REPO_URL = 'https://github.com/trib-plugin/mixdog';
-
-/** Claude config root — matches Claude Code (settings + plugins tree). */
-export function claudeConfigBaseDir() {
-  return process.env.CLAUDE_CONFIG_DIR || join(homedir(), '.claude');
-}
-
-// Claude Code honours CLAUDE_CONFIG_DIR; otherwise the user scope is ~/.claude.
-function settingsDir() {
-  return claudeConfigBaseDir();
-}
-
-export function defaultPluginDataDir() {
-  return join(
-    claudeConfigBaseDir(),
-    'plugins',
-    'data',
-    `${DEFAULT_PLUGIN}-${MARKETPLACE}`,
-  );
-}
-
-function loadSettings(file) {
-  if (!existsSync(file)) return {};
-  const raw = readFileSync(file, 'utf8');
-  if (raw.trim() === '') return {};
-  // Invariant: never clobber a file we cannot parse — let the caller abort.
-  return JSON.parse(raw);
-}
-
-function isPlainObject(value) {
-  return value !== null && typeof value === 'object' && !Array.isArray(value);
-}
-
-function registerPluginInSettings(dryRun = false) {
-  const dir = settingsDir();
-  const file = join(dir, 'settings.json');
-
-  let settings;
-  try {
-    settings = loadSettings(file);
-  } catch (err) {
-    console.error(`\n✗ ${file} is not valid JSON — refusing to overwrite it.`);
-    console.error(`  Fix or remove the file, then re-run. (${err.message})`);
-    process.exit(1);
-  }
-  if (!isPlainObject(settings)) {
-    console.error(`\n✗ ${file} does not contain a JSON object — refusing to overwrite it.`);
-    process.exit(1);
-  }
-
-  // Merge marketplace + enable flag without touching any other keys.
-  if (!isPlainObject(settings.extraKnownMarketplaces)) settings.extraKnownMarketplaces = {};
-  settings.extraKnownMarketplaces[MARKETPLACE] = {
-    source: { source: 'github', repo: REPO },
-  };
-  if (!isPlainObject(settings.enabledPlugins)) settings.enabledPlugins = {};
-  const already = settings.enabledPlugins[PLUGIN_REF] === true;
-  settings.enabledPlugins[PLUGIN_REF] = true;
-
-  if (dryRun) {
-    console.log(`[dry-run] would register mixdog in ${file}`);
-    console.log(`[dry-run]   marketplace "${MARKETPLACE}" → github:${REPO}`);
-    console.log(
-      `[dry-run]   enabled plugin "${PLUGIN_REF}"${already ? ' (was already enabled)' : ''}`,
-    );
-    return;
-  }
-
-  // Back up an existing file before the first write; create the dir otherwise.
-  if (existsSync(file)) {
-    const stamp = new Date().toISOString().replace(/[:.]/g, '-');
-    const bak = `${file}.bak-${stamp}`;
-    copyFileSync(file, bak);
-    console.log(`• Backed up existing settings → ${bak}`);
-  } else {
-    mkdirSync(dir, { recursive: true });
-  }
-
-  writeFileSync(file, JSON.stringify(settings, null, 2) + '\n');
-  console.log(`✓ Registered mixdog in ${file}`);
-  console.log(`  - marketplace "${MARKETPLACE}" → github:${REPO}`);
-  console.log(`  - enabled plugin "${PLUGIN_REF}"${already ? ' (was already enabled)' : ''}`);
-  console.log(`\nNext: restart Claude Code (or run /reload-plugins). mixdog loads automatically.`);
-}
-
-const CLAUDE_SETUP_GUIDANCE =
-  'Install Claude Code first: https://code.claude.com/docs/en/setup';
-
-function officialClaudeInstallerCommandDescription() {
-  if (process.platform === 'win32') {
-    return 'powershell -NoProfile -Command "irm https://claude.ai/install.ps1 | iex"';
-  }
-  return 'bash -c "curl -fsSL https://claude.ai/install.sh | bash"';
-}
-
-function runOfficialClaudeInstaller() {
-  if (process.platform === 'win32') {
-    spawnSync(
-      'powershell.exe',
-      ['-NoProfile', '-Command', 'irm https://claude.ai/install.ps1 | iex'],
-      { stdio: 'inherit', windowsHide: true },
-    );
-  } else {
-    spawnSync('bash', ['-c', 'curl -fsSL https://claude.ai/install.sh | bash'], {
-      stdio: 'inherit',
-    });
-  }
-}
-
-function askInstallClaude() {
-  return new Promise((resolve) => {
-    const rl = createInterface({ input: process.stdin, output: process.stdout });
-    rl.question(
-      'Claude Code CLI not found. Install it now with the official installer? (y/N) ',
-      (answer) => {
-        rl.close();
-        const a = answer.trim().toLowerCase();
-        resolve(a === 'y' || a === 'yes');
-      },
-    );
-  });
-}
-
-async function ensureClaudeInstalled(dryRun = false) {
-  const claudePath = resolveClaudeExecutable();
-  if (claudePath) {
-    if (dryRun) console.log(`[dry-run] Claude Code detected at ${claudePath}`);
-    return;
-  }
-
-  if (dryRun) {
-    const cmd = officialClaudeInstallerCommandDescription();
-    console.log(
-      `[dry-run] Claude Code NOT found — would prompt to install via the official installer (${cmd})`,
-    );
-    return;
-  }
-
-  const interactive = process.stdin.isTTY && !process.env.CI;
-
-  if (!interactive) {
-    console.log(CLAUDE_SETUP_GUIDANCE);
-    return;
-  }
-
-  const yes = await askInstallClaude();
-  if (yes) {
-    runOfficialClaudeInstaller();
-    if (resolveClaudeExecutable()) {
-      console.log('✓ Claude Code detected.');
-      return;
-    }
-    console.log(
-      "✓ Claude Code installed — open a NEW terminal so 'claude' is on PATH, then start Claude Code (mixdog is being registered now).",
-    );
-    return;
-  }
-
-  console.log(CLAUDE_SETUP_GUIDANCE);
-}
-
-const WIZARD_STEP_LABELS = [
-  'Address form',
-  'Discord bot token',
-  'Voice transcription',
-  'Webhook receiver',
-  'Provider API keys',
-  'Model presets',
-  'Role → preset mapping',
-  'Search backend',
-  'Explorer maintenance preset',
-];
-
-function logDryRunWizard() {
-  console.log('[dry-run] would run the setup wizard (9 steps):');
-  for (let i = 0; i < WIZARD_STEP_LABELS.length; i += 1) {
-    console.log(`[dry-run]   ${i + 1}. ${WIZARD_STEP_LABELS[i]}`);
-  }
-}
-
-async function runInstallDemo() {
-  const tmpRoot = mkdtempSync(join(tmpdir(), 'mixdog-demo-'));
-  const configDir = join(tmpRoot, 'config');
-  const dataDir = join(tmpRoot, 'data');
-  process.env.CLAUDE_CONFIG_DIR = configDir;
-  process.env.CLAUDE_PLUGIN_DATA = dataDir;
-  mkdirSync(configDir, { recursive: true });
-  mkdirSync(dataDir, { recursive: true });
-
-  process.on('exit', () => {
-    try {
-      rmSync(tmpRoot, { recursive: true, force: true });
-    } catch {}
-  });
-
-  console.log('\n🎬 mixdog demo — real wizard UI, nothing saved (isolated temp, auto-cleaned).\n');
-
-  const claudePath = resolveClaudeExecutable();
-  if (claudePath) {
-    console.log(`[demo] Claude Code detected at ${claudePath}`);
-  } else {
-    console.log('[demo] Claude Code not detected');
-  }
-
-  console.log('[demo] skipping plugin registration');
-
-  const { runSetupWizard } = await import('./wizard.mjs');
-  await runSetupWizard();
-
-  console.log('[demo] skipping runtime dependency install');
-
-  console.log('\n✓ Demo complete — nothing was saved to your real config.');
-  try {
-    rmSync(tmpRoot, { recursive: true, force: true });
-  } catch {}
-}
-
-export async function runInstall() {
-  const demo =
-    process.argv.includes('--demo') || process.env.MIXDOG_SETUP_DEMO === '1';
-  if (demo) {
-    await runInstallDemo();
-    return;
-  }
-
-  const dryRun =
-    process.argv.includes('--dry-run') || process.env.MIXDOG_SETUP_DRY_RUN === '1';
-
-  if (dryRun) {
-    console.log('[dry-run] mixdog install preview — no files, prompts, or installs');
-  }
-
-  await ensureClaudeInstalled(dryRun);
-  registerPluginInSettings(dryRun);
-
-  // npx / node setup/install.mjs runs outside Claude Code — config.mjs needs a data dir.
-  const pluginData = process.env.CLAUDE_PLUGIN_DATA;
-  const dataDir =
-    pluginData && String(pluginData).trim() ? String(pluginData).trim() : defaultPluginDataDir();
-  if (!dryRun && (!pluginData || !String(pluginData).trim())) {
-    process.env.CLAUDE_PLUGIN_DATA = defaultPluginDataDir();
-  }
-
-  if (dryRun) {
-    logDryRunWizard();
-  } else {
-    const { runSetupWizard } = await import('./wizard.mjs');
-    await runSetupWizard();
-  }
-
-  await prewarmRuntimeDepsBestEffort(dryRun, dataDir);
-
-  if (!dryRun) maybeStarNudge();
-}
-
-async function prewarmRuntimeDepsBestEffort(dryRun = false, dataDirOverride = null) {
-  const dataDir = dataDirOverride || process.env.CLAUDE_PLUGIN_DATA || defaultPluginDataDir();
-  if (dryRun) {
-    console.log(
-      `[dry-run] would prewarm runtime deps (bun install into ${join(dataDir, '.deps')})`,
-    );
-    return;
-  }
-
-  const spinner = createSpinner('Installing runtime dependencies…');
-  try {
-    const pluginRoot = join(dirname(fileURLToPath(import.meta.url)), '..');
-    mkdirSync(dataDir, { recursive: true });
-
-    const { resolveBun, installBunViaNpm } = await import('../scripts/resolve-bun.mjs');
-    const { ensureRuntimeDeps, resolveNmWithRequiredDeps } = await import('../scripts/ensure-deps.mjs');
-
-    let bunPath = resolveBun(pluginRoot);
-    if (!bunPath) {
-      installBunViaNpm(pluginRoot, { fatal: false });
-      bunPath = resolveBun(pluginRoot);
-    }
-    if (!bunPath) {
-      spinner.stop('bun unavailable — will install on first launch', false);
-      return;
-    }
-    const seedNm = resolveNmWithRequiredDeps(pluginRoot) || undefined;
-
-    const result = ensureRuntimeDeps({
-      dataDir,
-      pluginRoot,
-      bunPath,
-      seedNm,
-      logPrefix: '[setup]',
-      installStdio: 'pipe',
-    });
-    if (result?.satisfied) {
-      spinner.stop('prewarmed (first launch should skip bun install)', true);
-    } else {
-      spinner.stop(`will install on first launch (${result?.reason || 'prewarm did not complete'})`, false);
-    }
-  } catch (err) {
-    spinner.stop(
-      `prewarm skipped — ${err?.message || 'first MCP launch may run bun install'}`,
-      false,
-    );
-  }
-}
-
-// Non-blocking, opt-in star nudge. Only on a real interactive terminal — never
-// in CI or piped/non-TTY installs, so it can never break an automated setup.
-function maybeStarNudge() {
-  if (!process.stdin.isTTY || process.env.CI) return;
-  const rl = createInterface({ input: process.stdin, output: process.stdout });
-  rl.question('\n⭐ Found this useful? Star the repo on GitHub? (y/N) ', (answer) => {
-    const a = answer.trim().toLowerCase();
-    if (a === 'y' || a === 'yes') openRepo();
-    else console.log(`No problem — you can star it anytime at ${REPO_URL}`);
-    rl.close();
-  });
-}
-
-function openRepo() {
-  const platform = process.platform;
-  const cmd = platform === 'win32' ? 'cmd' : platform === 'darwin' ? 'open' : 'xdg-open';
-  const args = platform === 'win32' ? ['/c', 'start', '', REPO_URL] : [REPO_URL];
-  try {
-    spawn(cmd, args, { stdio: 'ignore', detached: true }).unref();
-    console.log('Opening the repo in your browser — thank you! 🙏');
-  } catch {
-    console.log(`Please visit ${REPO_URL} to star. Thank you! 🙏`);
-  }
-}
-
-function isInstallerEntry() {
-  const entry = process.argv[1];
-  if (!entry) return false;
-  try {
-    const self = realpathSync(fileURLToPath(import.meta.url));
-    const invoked = realpathSync(entry);
-    return self === invoked;
-  } catch {
-    return false;
-  }
-}
-
-if (isInstallerEntry()) {
-  runInstall().catch((err) => {
-    console.error(err?.stack || err?.message || String(err));
-    process.exit(1);
-  });
-}
+#!/usr/bin/env node
+// install.mjs — one-shot bootstrapper that registers the mixdog plugin in the
+// user's Claude Code settings so it auto-loads on the next session start.
+//
+// Run via:  npx mixdog | mixdog install | mixdog-install   (after publish)
+//       or:  node setup/install.mjs             (from a checkout)
+//
+// It merges two keys into the user-scope settings file (preserving everything
+// else that is already there):
+//   extraKnownMarketplaces["trib-plugin"] -> the GitHub marketplace source
+//   enabledPlugins["mixdog@trib-plugin"]  -> true
+//
+// After it runs, the user restarts Claude Code (or runs /reload-plugins) and
+// mixdog is already present — there is no separate /plugin install step.
+
+import {
+  readFileSync,
+  writeFileSync,
+  existsSync,
+  mkdirSync,
+  copyFileSync,
+  mkdtempSync,
+  rmSync,
+} from 'node:fs';
+import { join, dirname } from 'node:path';
+import { homedir, tmpdir } from 'node:os';
+import { realpathSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { createInterface } from 'node:readline';
+import { spawn, spawnSync } from 'node:child_process';
+import { DEFAULT_MARKETPLACE, DEFAULT_PLUGIN } from '../src/shared/plugin-paths.mjs';
+import { resolveClaudeExecutable } from './locate-claude.mjs';
+import { confirm, createSpinner, outro } from './tui.mjs';
+import { openInBrowser } from '../src/shared/open-url.mjs';
+
+const MARKETPLACE = DEFAULT_MARKETPLACE;
+const PLUGIN_REF = `${DEFAULT_PLUGIN}@${DEFAULT_MARKETPLACE}`;
+const REPO = 'trib-plugin/mixdog';        // github owner/repo
+const REPO_URL = 'https://github.com/trib-plugin/mixdog';
+
+/** Claude config root — matches Claude Code (settings + plugins tree). */
+export function claudeConfigBaseDir() {
+  return process.env.CLAUDE_CONFIG_DIR || join(homedir(), '.claude');
+}
+
+// Claude Code honours CLAUDE_CONFIG_DIR; otherwise the user scope is ~/.claude.
+function settingsDir() {
+  return claudeConfigBaseDir();
+}
+
+export function defaultPluginDataDir() {
+  return join(
+    claudeConfigBaseDir(),
+    'plugins',
+    'data',
+    `${DEFAULT_PLUGIN}-${MARKETPLACE}`,
+  );
+}
+
+function loadSettings(file) {
+  if (!existsSync(file)) return {};
+  const raw = readFileSync(file, 'utf8');
+  if (raw.trim() === '') return {};
+  // Invariant: never clobber a file we cannot parse — let the caller abort.
+  return JSON.parse(raw);
+}
+
+/** True when user settings already enable the published plugin ref (deterministic read). */
+export function isPluginRegistered() {
+  const file = join(claudeConfigBaseDir(), 'settings.json');
+  if (!existsSync(file)) return false;
+  try {
+    const raw = readFileSync(file, 'utf8');
+    if (raw.trim() === '') return false;
+    const settings = JSON.parse(raw);
+    if (!isPlainObject(settings)) return false;
+    return settings?.enabledPlugins?.[PLUGIN_REF] === true;
+  } catch {
+    return false;
+  }
+}
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function registerPluginInSettings(dryRun = false) {
+  const dir = settingsDir();
+  const file = join(dir, 'settings.json');
+
+  let settings;
+  try {
+    settings = loadSettings(file);
+  } catch (err) {
+    console.error(`\n✗ ${file} is not valid JSON — refusing to overwrite it.`);
+    console.error(`  Fix or remove the file, then re-run. (${err.message})`);
+    process.exit(1);
+  }
+  if (!isPlainObject(settings)) {
+    console.error(`\n✗ ${file} does not contain a JSON object — refusing to overwrite it.`);
+    process.exit(1);
+  }
+
+  // Merge marketplace + enable flag without touching any other keys.
+  if (!isPlainObject(settings.extraKnownMarketplaces)) settings.extraKnownMarketplaces = {};
+  settings.extraKnownMarketplaces[MARKETPLACE] = {
+    source: { source: 'github', repo: REPO },
+  };
+  if (!isPlainObject(settings.enabledPlugins)) settings.enabledPlugins = {};
+  const already = settings.enabledPlugins[PLUGIN_REF] === true;
+  settings.enabledPlugins[PLUGIN_REF] = true;
+
+  if (dryRun) {
+    console.log(`[dry-run] would register mixdog in ${file}`);
+    console.log(`[dry-run]   marketplace "${MARKETPLACE}" → github:${REPO}`);
+    console.log(
+      `[dry-run]   enabled plugin "${PLUGIN_REF}"${already ? ' (was already enabled)' : ''}`,
+    );
+    return;
+  }
+
+  // Back up an existing file before the first write; create the dir otherwise.
+  if (existsSync(file)) {
+    const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+    const bak = `${file}.bak-${stamp}`;
+    copyFileSync(file, bak);
+    console.log(`• Backed up existing settings → ${bak}`);
+  } else {
+    mkdirSync(dir, { recursive: true });
+  }
+
+  writeFileSync(file, JSON.stringify(settings, null, 2) + '\n');
+  console.log(`✓ Registered mixdog in ${file}`);
+  console.log(`  - marketplace "${MARKETPLACE}" → github:${REPO}`);
+  console.log(`  - enabled plugin "${PLUGIN_REF}"${already ? ' (was already enabled)' : ''}`);
+  console.log(`\nNext: restart Claude Code (or run /reload-plugins). mixdog loads automatically.`);
+}
+
+const CLAUDE_SETUP_GUIDANCE =
+  'Install Claude Code first: https://code.claude.com/docs/en/setup';
+
+function officialClaudeInstallerCommandDescription() {
+  if (process.platform === 'win32') {
+    return 'powershell -NoProfile -Command "irm https://claude.ai/install.ps1 | iex"';
+  }
+  return 'bash -c "curl -fsSL https://claude.ai/install.sh | bash"';
+}
+
+function runOfficialClaudeInstaller() {
+  if (process.platform === 'win32') {
+    spawnSync(
+      'powershell.exe',
+      ['-NoProfile', '-Command', 'irm https://claude.ai/install.ps1 | iex'],
+      { stdio: 'inherit', windowsHide: true },
+    );
+  } else {
+    spawnSync('bash', ['-c', 'curl -fsSL https://claude.ai/install.sh | bash'], {
+      stdio: 'inherit',
+    });
+  }
+}
+
+function askInstallClaude() {
+  return new Promise((resolve) => {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    rl.question(
+      'Claude Code CLI not found. Install it now with the official installer? (y/N) ',
+      (answer) => {
+        rl.close();
+        const a = answer.trim().toLowerCase();
+        resolve(a === 'y' || a === 'yes');
+      },
+    );
+  });
+}
+
+async function ensureClaudeInstalled(dryRun = false) {
+  const claudePath = resolveClaudeExecutable();
+  if (claudePath) {
+    if (dryRun) console.log(`[dry-run] Claude Code detected at ${claudePath}`);
+    return;
+  }
+
+  if (dryRun) {
+    const cmd = officialClaudeInstallerCommandDescription();
+    console.log(
+      `[dry-run] Claude Code NOT found — would prompt to install via the official installer (${cmd})`,
+    );
+    return;
+  }
+
+  const interactive = process.stdin.isTTY && !process.env.CI;
+
+  if (!interactive) {
+    console.log(CLAUDE_SETUP_GUIDANCE);
+    return;
+  }
+
+  const yes = await askInstallClaude();
+  if (yes) {
+    runOfficialClaudeInstaller();
+    if (resolveClaudeExecutable()) {
+      console.log('✓ Claude Code detected.');
+      return;
+    }
+    console.log(
+      "✓ Claude Code installed — open a NEW terminal so 'claude' is on PATH, then start Claude Code (mixdog is being registered now).",
+    );
+    return;
+  }
+
+  console.log(CLAUDE_SETUP_GUIDANCE);
+}
+
+// OAuth logins for the agent runtime. Claude (anthropic-oauth) powers every
+// default preset so it is recommended; Codex (openai-oauth) is an optional
+// extra. Both complete a browser-PKCE login via a localhost callback, so an
+// inline login works (`offerLogin: true`).
+//
+// Grok Build (grok-oauth) is DETECT-ONLY (`offerLogin: false`): xAI's consent
+// page shows a code to copy instead of redirecting to our localhost callback,
+// so an inline login here would dead-end (the user gets a key with nowhere to
+// put it). Its real login is the official `grok` CLI, which handles that paste
+// and writes ~/.grok/auth.json — mixdog reads that file (and its own store),
+// so we only DETECT Grok and point at the CLI when it is missing.
+//
+// Each provider module exposes the same shape — a `has…Credentials` detector
+// and (for offerLogin providers) a browser-PKCE `loginOAuth` resolving a truthy
+// token object on success or null on failure. Already authenticated →
+// auto-skip. All branches are invariant-gated (creds present? · offerLogin? ·
+// TTY? · login result?) — no heuristic fallback.
+const OAUTH_PROVIDERS = [
+  {
+    label: 'Claude',
+    module: '../src/agent/orchestrator/providers/anthropic-oauth.mjs',
+    has: 'hasAnthropicOAuthCredentials',
+    offerLogin: true,
+    recommended: true,
+  },
+  {
+    label: 'Codex (ChatGPT)',
+    module: '../src/agent/orchestrator/providers/openai-oauth.mjs',
+    has: 'hasOpenAIOAuthCredentials',
+    offerLogin: true,
+    recommended: false,
+  },
+  {
+    label: 'Grok Build',
+    module: '../src/agent/orchestrator/providers/grok-oauth.mjs',
+    has: 'hasGrokOAuthCredentials',
+    offerLogin: false,
+    hint: 'log in with the `grok` CLI — mixdog reads ~/.grok/auth.json automatically',
+  },
+];
+
+async function ensureOAuthLogins(dryRun = false) {
+  const interactive = process.stdin.isTTY && !process.env.CI;
+  for (const p of OAUTH_PROVIDERS) {
+    const mod = await import(p.module);
+    if (mod[p.has]()) {
+      console.log(dryRun ? `[dry-run] ${p.label} login detected` : `✓ ${p.label} login detected.`);
+      continue;
+    }
+    // Detect-only providers (Grok): never open an inline login — point at the
+    // provider's own CLI, which mixdog auto-detects via its credential file.
+    if (!p.offerLogin) {
+      console.log(
+        dryRun
+          ? `[dry-run] no ${p.label} login — would point to: ${p.hint}`
+          : `${p.label}: not logged in — ${p.hint}.`,
+      );
+      continue;
+    }
+    if (dryRun) {
+      console.log(`[dry-run] no ${p.label} login — would offer to log in via the browser`);
+      continue;
+    }
+    if (!interactive) {
+      console.log(`${p.label}: not logged in — log in anytime via /setup.`);
+      continue;
+    }
+    const yes = await confirm(`Log in to ${p.label} now? (opens your browser)`, {
+      initial: p.recommended,
+    });
+    if (!yes) {
+      console.log(`Skipped ${p.label} — log in anytime via /setup.`);
+      continue;
+    }
+    const result = await mod.loginOAuth();
+    console.log(
+      result
+        ? `✓ ${p.label} login complete.`
+        : `${p.label} login did not complete — retry anytime via /setup.`,
+    );
+  }
+}
+
+async function runInstallDemo() {
+  process.env.MIXDOG_SETUP_QUIET = '1';
+  const tmpRoot = mkdtempSync(join(tmpdir(), 'mixdog-demo-'));
+  const configDir = join(tmpRoot, 'config');
+  const dataDir = join(tmpRoot, 'data');
+  process.env.CLAUDE_CONFIG_DIR = configDir;
+  process.env.CLAUDE_PLUGIN_DATA = dataDir;
+  mkdirSync(configDir, { recursive: true });
+  mkdirSync(dataDir, { recursive: true });
+
+  process.on('exit', () => {
+    try {
+      rmSync(tmpRoot, { recursive: true, force: true });
+    } catch {}
+  });
+
+  console.log('\n🎬 mixdog demo — install preview, nothing saved (isolated temp, auto-cleaned).\n');
+
+  const claudePath = resolveClaudeExecutable();
+  if (claudePath) {
+    console.log(`[demo] Claude Code detected at ${claudePath}`);
+  } else {
+    console.log('[demo] Claude Code not detected');
+  }
+
+  console.log('[demo] skipping plugin registration');
+
+  for (const p of OAUTH_PROVIDERS) {
+    const mod = await import(p.module);
+    console.log(
+      mod[p.has]()
+        ? `[demo] ${p.label} login detected`
+        : `[demo] no ${p.label} login — ${p.offerLogin ? 'would offer a browser login' : `would point to: ${p.hint}`}`,
+    );
+  }
+
+  console.log('[demo] skipping runtime dependency install');
+
+  await runFinale({ demo: true });
+
+  console.log('\n✓ Demo complete — nothing was saved to your real config.');
+  console.log('Run `mixdog install` to set up for real.');
+  try {
+    rmSync(tmpRoot, { recursive: true, force: true });
+  } catch {}
+}
+
+export async function runInstall({ launchAfter = false } = {}) {
+  const demo =
+    process.argv.includes('--demo') || process.env.MIXDOG_SETUP_DEMO === '1';
+  if (demo) {
+    await runInstallDemo();
+    return;
+  }
+
+  process.env.MIXDOG_SETUP_QUIET = '1';
+
+  const dryRun =
+    process.argv.includes('--dry-run') || process.env.MIXDOG_SETUP_DRY_RUN === '1';
+
+  if (dryRun) {
+    console.log('[dry-run] mixdog install preview — no files, prompts, or installs');
+  }
+
+  await ensureClaudeInstalled(dryRun);
+  registerPluginInSettings(dryRun);
+
+  // npx / node setup/install.mjs runs outside Claude Code. The provider modules
+  // imported by ensureOAuthLogins (below) pull in config.mjs, which resolves
+  // plugin-data AT IMPORT TIME and throws if neither CLAUDE_PLUGIN_DATA nor
+  // CLAUDE_PLUGIN_ROOT is set. Export it before any provider import — in
+  // --dry-run too: this only sets a process env var, no files are written.
+  const pluginData = process.env.CLAUDE_PLUGIN_DATA;
+  const dataDir =
+    pluginData && String(pluginData).trim() ? String(pluginData).trim() : defaultPluginDataDir();
+  if (!pluginData || !String(pluginData).trim()) {
+    process.env.CLAUDE_PLUGIN_DATA = dataDir;
+  }
+
+  // No interactive wizard. The full default config (presets, role→preset
+  // mapping, search backend, maintenance) is seeded on first launch by the
+  // agent boot + setup server; per-feature config (Discord, voice, webhooks,
+  // address, provider keys) lives in the /setup UI. Install only secures the
+  // OAuth logins (Claude / Codex / Grok Build) so agents work the moment
+  // mixdog launches.
+  await ensureOAuthLogins(dryRun);
+
+  await prewarmRuntimeDepsBestEffort(dryRun, dataDir);
+
+  if (!dryRun) await runFinale({ launchAfter });
+}
+
+async function prewarmRuntimeDepsBestEffort(dryRun = false, dataDirOverride = null) {
+  const dataDir = dataDirOverride || process.env.CLAUDE_PLUGIN_DATA || defaultPluginDataDir();
+  if (dryRun) {
+    console.log(
+      `[dry-run] would prewarm runtime deps (bun install into ${join(dataDir, '.deps')})`,
+    );
+    return;
+  }
+
+  const spinner = createSpinner('Installing runtime dependencies…');
+  try {
+    const pluginRoot = join(dirname(fileURLToPath(import.meta.url)), '..');
+    mkdirSync(dataDir, { recursive: true });
+
+    const { resolveBun, installBunViaNpm } = await import('../scripts/resolve-bun.mjs');
+    const { ensureRuntimeDeps, resolveNmWithRequiredDeps } = await import('../scripts/ensure-deps.mjs');
+
+    let bunPath = resolveBun(pluginRoot);
+    if (!bunPath) {
+      installBunViaNpm(pluginRoot, { fatal: false });
+      bunPath = resolveBun(pluginRoot);
+    }
+    if (!bunPath) {
+      spinner.stop('bun unavailable — will install on first launch', false);
+      return;
+    }
+    const seedNm = resolveNmWithRequiredDeps(pluginRoot) || undefined;
+
+    const result = ensureRuntimeDeps({
+      dataDir,
+      pluginRoot,
+      bunPath,
+      seedNm,
+      logPrefix: '[setup]',
+      installStdio: 'pipe',
+    });
+    if (result?.satisfied) {
+      spinner.stop('prewarmed (first launch should skip bun install)', true);
+    } else {
+      spinner.stop(`will install on first launch (${result?.reason || 'prewarm did not complete'})`, false);
+    }
+  } catch (err) {
+    spinner.stop(
+      `prewarm skipped — ${err?.message || 'first MCP launch may run bun install'}`,
+      false,
+    );
+  }
+}
+
+async function runFinale({ demo = false, launchAfter = false } = {}) {
+  console.log('\n── All set ──');
+  console.log('🎉  mixdog is configured.');
+
+  const interactive = process.stdin.isTTY && !process.env.CI;
+  if (interactive) {
+    const star = await confirm('Star mixdog on GitHub?', { initial: true });
+    if (star) {
+      if (demo) {
+        console.log(`[demo] would star ${REPO} via GH_TOKEN/gh (or open ${REPO_URL} as a fallback)`);
+      } else if (await starRepo()) {
+        console.log(`⭐  Starred ${REPO} — thank you! 🙏`);
+      } else {
+        // No usable local GitHub credential (env token / gh) — hand off to the
+        // browser, where the user is already signed in to github.com.
+        openRepo();
+      }
+    } else {
+      console.log(`No problem — you can star it anytime at ${REPO_URL}`);
+    }
+  }
+
+  if (demo) {
+    outro('Demo finished — no changes were saved.');
+    releaseInstallerStdin();
+    return;
+  }
+  outro(
+    launchAfter
+      ? 'Setup complete — launching Claude Code with mixdog…'
+      : 'Setup complete — run `mixdog` to launch Claude Code with mixdog (or restart it if already open).',
+  );
+  releaseInstallerStdin();
+}
+
+/** Belt-and-suspenders after TUI prompts so direct `node setup/install.mjs` can exit. */
+function releaseInstallerStdin() {
+  const stdin = process.stdin;
+  try {
+    if (stdin.isTTY) stdin.setRawMode(false);
+  } catch {
+    /* ignore */
+  }
+  stdin.removeAllListeners('keypress');
+  stdin.removeAllListeners('data');
+  stdin.pause();
+}
+
+/**
+ * Star the repo without a browser when a local GitHub credential is available,
+ * following the standard CLI pattern (gh primary, GITHUB_TOKEN secondary —
+ * confirmed against GitHub docs / gh manual). Order: an explicitly-set env
+ * token first (deliberate, e.g. CI), then the authenticated `gh` CLI. Returns
+ * true once one succeeds; false when none is usable, so the caller opens the
+ * browser. Starring needs the user's GitHub identity — there is no
+ * unauthenticated path.
+ */
+async function starRepo() {
+  const envToken = process.env.GH_TOKEN || process.env.GITHUB_TOKEN;
+  if (envToken && (await starViaToken(envToken))) return true;
+  return starRepoViaGh();
+}
+
+/**
+ * Star via the REST API with a bearer token (PUT /user/starred/:owner/:repo →
+ * HTTP 204). `public_repo` scope suffices for a public repo, `repo` for a
+ * private one. Returns true on 204, false on any non-204 / network error.
+ */
+async function starViaToken(token) {
+  try {
+    const res = await fetch(`https://api.github.com/user/starred/${REPO}`, {
+      method: 'PUT',
+      headers: {
+        Authorization: `Bearer ${token}`,
+        Accept: 'application/vnd.github+json',
+        'X-GitHub-Api-Version': '2022-11-28',
+        'Content-Length': '0',
+        'User-Agent': 'mixdog-installer',
+      },
+    });
+    return res.status === 204;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Star the repo directly via the authenticated `gh` CLI
+ * (PUT /user/starred/:owner/:repo → HTTP 204). Returns true on success.
+ * Returns false when gh is absent / not logged in / the call fails, so the
+ * caller falls back to opening the browser — starring requires the user's
+ * GitHub identity, which only gh provides here. Path has no leading slash so
+ * a shell never rewrites it; shell:true lets Windows resolve gh.exe on PATH.
+ */
+function starRepoViaGh() {
+  try {
+    const r = spawnSync(
+      'gh',
+      ['api', '--method', 'PUT', `user/starred/${REPO}`, '--silent'],
+      { stdio: 'ignore', timeout: 15000, shell: true },
+    );
+    return r.status === 0;
+  } catch {
+    return false;
+  }
+}
+
+function openRepo() {
+  // Shared opener: rundll32 on Windows (the old `cmd start "" url` worked only
+  // because REPO_URL has no query string; the helper is correct regardless).
+  openInBrowser(REPO_URL);
+  console.log(`Opening the repo in your browser — thank you! 🙏 (if it didn't open: ${REPO_URL})`);
+}
+
+function isInstallerEntry() {
+  const entry = process.argv[1];
+  if (!entry) return false;
+  try {
+    const self = realpathSync(fileURLToPath(import.meta.url));
+    const invoked = realpathSync(entry);
+    return self === invoked;
+  } catch {
+    return false;
+  }
+}
+
+if (isInstallerEntry()) {
+  runInstall()
+    .then(() => {
+      process.stdout.write('', () => process.exit(0));
+    })
+    .catch((err) => {
+      console.error(err?.stack || err?.message || String(err));
+      process.exit(1);
+    });
+}