@stackframe/init-stack 2.8.44 → 2.8.46

package/dist/index.js

@@ -1,20 +1,20 @@
 #!/usr/bin/env node
 
 // src/index.ts
-import * as child_process from "child_process";
+import * as child_process2 from "child_process";
 import { Command } from "commander";
 import * as crypto from "crypto";
-import * as fs from "fs";
+import * as fs3 from "fs";
 import inquirer from "inquirer";
 import open from "open";
-import * as os from "os";
-import * as path from "path";
+import * as os2 from "os";
+import * as path3 from "path";
 import { PostHog } from "posthog-node";
 
 // package.json
 var package_default = {
   name: "@stackframe/init-stack",
-  version: "2.8.44",
+  version: "2.8.46",
   description: "The setup wizard for Stack. https://stack-auth.com",
   main: "dist/index.js",
   type: "module",
@@ -32,16 +32,16 @@ var package_default = {
     "ensure-neon": `grep -q '"@neondatabase/serverless"' ./test-run-output/package.json && echo 'Initialized Neon successfully!'`,
     "test-run-neon": "pnpm run test-run-node --neon && pnpm run ensure-neon",
     "test-run-neon:manual": "pnpm run test-run-node:manual --neon && pnpm run ensure-neon",
-    "test-run-no-browser": "rimraf test-run-output && mkdir test-run-output && cd test-run-output && npm init --init-author-name example-author --init-license UNLICENSED --init-author-url http://example.com --init-module test-run-output --init-version 1.0.0 -y && cd .. && pnpm run init-stack:local test-run-output --on-question error --js --server --npm --no-browser",
+    "test-run-no-browser": "rimraf test-run-output && mkdir test-run-output && cd test-run-output && npm init --init-author-name example-author --init-license UNLICENSED --init-author-url http://example.com --init-module test-run-output --init-version 1.0.0 -y && cd .. && pnpm run init-stack:local test-run-output --on-question error --no-warn-uncommitted-changes --js --server --npm --no-browser",
     "test-run-node:manual": "rimraf test-run-output && mkdir test-run-output && cd test-run-output && npm init && cd .. && pnpm run init-stack:local test-run-output",
-    "test-run-node": "rimraf test-run-output && mkdir test-run-output && cd test-run-output && npm init --init-author-name example-author --init-license UNLICENSED --init-author-url http://example.com --init-module test-run-output --init-version 1.0.0 -y && cd .. && pnpm run init-stack:local test-run-output --on-question error --js --server --npm --no-browser",
+    "test-run-node": "rimraf test-run-output && mkdir test-run-output && cd test-run-output && npm init --init-author-name example-author --init-license UNLICENSED --init-author-url http://example.com --init-module test-run-output --init-version 1.0.0 -y && cd .. && pnpm run init-stack:local test-run-output --on-question error --no-warn-uncommitted-changes --js --server --npm --no-browser",
     "test-run-js:manual": "rimraf test-run-output && npx -y sv create test-run-output --no-install && pnpm run init-stack:local test-run-output",
-    "test-run-js": "rimraf test-run-output && npx -y sv create test-run-output --template minimal --types ts --no-add-ons --no-install && pnpm run init-stack:local test-run-output --on-question error --js --client --npm --no-browser",
+    "test-run-js": "rimraf test-run-output && npx -y sv create test-run-output --template minimal --types ts --no-add-ons --no-install && pnpm run init-stack:local test-run-output --on-question error --no-warn-uncommitted-changes --js --client --npm --no-browser",
     "test-run-next:manual": "rimraf test-run-output && npx -y create-next-app@latest test-run-output && pnpm run init-stack:local test-run-output",
-    "test-run-next": "rimraf test-run-output && npx -y create-next-app@latest test-run-output --app --ts --no-src-dir --tailwind --use-npm --eslint --import-alias '##@#/*' --turbopack && pnpm run init-stack:local test-run-output --on-question error --no-browser",
-    "test-run-keys-next": "rimraf test-run-output && npx -y create-next-app@latest test-run-output --app --ts --no-src-dir --tailwind --use-npm --eslint --import-alias '##@#/*' --turbopack && pnpm run init-stack:local test-run-output --on-question error --project-id my-project-id --publishable-client-key my-publishable-client-key",
-    "test-run-keys-js": "rimraf test-run-output && npx -y sv create test-run-output --template minimal --types ts --no-add-ons --no-install && pnpm run init-stack:local test-run-output --on-question error --js --client --npm --project-id my-project-id --publishable-client-key my-publishable-client-key",
-    "test-run-react": "rimraf test-run-output && npx -y create-vite@latest test-run-output --template react-ts && pnpm run init-stack:local test-run-output --on-question error --no-browser --npm",
+    "test-run-next": "rimraf test-run-output && npx -y create-next-app@latest test-run-output --app --ts --no-src-dir --tailwind --use-npm --eslint --import-alias '##@#/*' --turbopack && pnpm run init-stack:local test-run-output --on-question error --no-warn-uncommitted-changes --no-browser",
+    "test-run-keys-next": "rimraf test-run-output && npx -y create-next-app@latest test-run-output --app --ts --no-src-dir --tailwind --use-npm --eslint --import-alias '##@#/*' --turbopack && pnpm run init-stack:local test-run-output --on-question error --no-warn-uncommitted-changes --project-id my-project-id --publishable-client-key my-publishable-client-key",
+    "test-run-keys-js": "rimraf test-run-output && npx -y sv create test-run-output --template minimal --types ts --no-add-ons --no-install && pnpm run init-stack:local test-run-output --on-question error --no-warn-uncommitted-changes --js --client --npm --project-id my-project-id --publishable-client-key my-publishable-client-key",
+    "test-run-react": "rimraf test-run-output && npx -y create-vite@latest test-run-output --template react-ts && pnpm run init-stack:local test-run-output --on-question error --no-warn-uncommitted-changes --no-browser --npm",
     "test-run-react:manual": "rimraf test-run-output && npx -y create-vite@latest test-run-output --template react-ts && pnpm run init-stack:local test-run-output --react"
   },
   files: [
@@ -70,6 +70,367 @@ var package_default = {
   }
 };
 
+// src/mcp.ts
+import * as fs2 from "fs";
+import * as os from "os";
+import * as path2 from "path";
+
+// src/util.ts
+import * as child_process from "child_process";
+import * as fs from "fs";
+import * as path from "path";
+var verboseLevelState = 0;
+var verboseFormatterState = null;
+function configureVerboseLogging(options2) {
+  verboseLevelState = Math.max(0, options2.level ?? 0);
+  verboseFormatterState = options2.formatter ?? null;
+}
+function logVerbose(message, details) {
+  if (verboseLevelState <= 0) return;
+  const formattedMessage = verboseFormatterState ? verboseFormatterState(message) : `[verbose] ${message}`;
+  console.log(formattedMessage);
+  if (typeof details !== "undefined" && verboseLevelState >= 2) {
+    console.dir(details, { depth: null });
+  }
+}
+function templateIdentity(strings, ...values) {
+  if (strings.length === 0) return "";
+  if (values.length !== strings.length - 1) {
+    throw new Error("Invalid number of values; must be one less than strings");
+  }
+  return strings.slice(1).reduce(
+    (result, string, i) => `${result}${String(values[i])}${string}`,
+    strings[0]
+  );
+}
+function getCommandPath(command) {
+  if (!command) return null;
+  const checker = process.platform === "win32" ? "where" : "which";
+  const commands = [
+    [process.env.SHELL ?? "bash", ["-ic", `${checker} ${command}`]],
+    [checker, [command]]
+  ];
+  for (const spawnArgs of commands) {
+    const result = child_process.spawnSync(spawnArgs[0], spawnArgs[1], { stdio: "pipe" });
+    if (result.status === 0) {
+      return result.stdout.toString().trim().split("\n")[0];
+    }
+  }
+  return null;
+}
+function shouldWriteConfigFile(fullPath, options2 = {}) {
+  if (!fullPath) return false;
+  if (fs.existsSync(fullPath)) return true;
+  const dir = path.dirname(fullPath);
+  if (!options2.allowCreate) {
+    return fs.existsSync(dir);
+  }
+  return true;
+}
+
+// src/mcp.ts
+var MCP_SERVER_NAME = "stack-auth";
+var MCP_SERVER_URL = "https://mcp.stack-auth.com/";
+var MCP_ACCEPT_HEADER = "application/json, text/event-stream";
+var VS_CODE_PAYLOAD = JSON.stringify({ type: "http", name: MCP_SERVER_NAME, url: MCP_SERVER_URL });
+var CLAUDE_BASE_ARGS = ["mcp", "add", "--transport", "http", MCP_SERVER_NAME, MCP_SERVER_URL];
+function scheduleMcpConfiguration(ctx) {
+  const workspaceRoot = path2.resolve(ctx.projectPath);
+  const homeDir = os.homedir();
+  logMcpVerbose("scheduleMcpConfiguration invoked", { workspaceRoot, homeDir });
+  scheduleCursorConfigs(ctx, homeDir, workspaceRoot);
+  scheduleVsCodeConfigs(ctx, homeDir, workspaceRoot);
+  scheduleClaudeConfigs(ctx, workspaceRoot);
+  scheduleWindsurfConfigs(ctx, homeDir);
+  scheduleGeminiConfig(ctx, homeDir);
+}
+function scheduleCursorConfigs(ctx, homeDir, workspaceRoot) {
+  const updater = createServerUpdater("mcpServers", { url: MCP_SERVER_URL });
+  logMcpVerbose("Scheduling Cursor MCP configs", { homeDir, workspaceRoot });
+  const targets = [
+    { path: path2.join(homeDir, ".cursor", "mcp.json"), allowCreate: false, scope: "home" },
+    { path: path2.join(workspaceRoot, ".cursor", "mcp.json"), allowCreate: true, scope: "workspace" }
+  ];
+  for (const target of targets) {
+    logInvestigationStatus("Cursor", target.path, target.scope);
+  }
+  scheduleJsonTargets(
+    ctx,
+    targets.map(({ path: targetPath, allowCreate }) => ({ path: targetPath, allowCreate })),
+    updater
+  );
+}
+function scheduleVsCodeConfigs(ctx, homeDir, workspaceRoot) {
+  const updater = createServerUpdater("servers", { type: "http", url: MCP_SERVER_URL });
+  const paths = getVsCodeUserConfigPaths(homeDir);
+  logMcpVerbose("Scheduling VS Code MCP configs", { homeDir, paths });
+  paths.stable.forEach((configPath) => logInvestigationStatus("VS Code (stable)", configPath));
+  paths.insiders.forEach((configPath) => logInvestigationStatus("VS Code (insiders)", configPath));
+  const workspaceTarget = path2.join(workspaceRoot, ".vscode", "mcp.json");
+  logInvestigationStatus("VS Code (workspace)", workspaceTarget);
+  const stableChanged = scheduleJsonTargets(
+    ctx,
+    paths.stable.map((configPath) => ({ path: configPath })),
+    updater
+  );
+  const insidersChanged = scheduleJsonTargets(
+    ctx,
+    paths.insiders.map((configPath) => ({ path: configPath })),
+    updater
+  );
+  const workspaceChanged = scheduleJsonTargets(
+    ctx,
+    [{ path: path2.join(workspaceRoot, ".vscode", "mcp.json"), allowCreate: true }],
+    updater
+  );
+  scheduleCliIfAvailable(ctx, "code", ["--add-mcp", VS_CODE_PAYLOAD], true);
+  scheduleCliIfAvailable(ctx, "code-insiders", ["--add-mcp", VS_CODE_PAYLOAD], true);
+}
+function findClaudeExecutable() {
+  const homeDir = os.homedir();
+  const localBinPath = path2.join(homeDir, ".local", "bin", "claude");
+  const claudeLocalPath = path2.join(homeDir, ".claude", "local", "claude");
+  if (fs2.existsSync(localBinPath)) {
+    return localBinPath;
+  }
+  if (fs2.existsSync(claudeLocalPath)) {
+    return claudeLocalPath;
+  }
+  return "claude";
+}
+function scheduleClaudeConfigs(ctx, workspaceRoot) {
+  const updater = createServerUpdater("mcpServers", { type: "http", url: MCP_SERVER_URL });
+  logMcpVerbose("Scheduling Claude MCP configs", { workspaceRoot });
+  const targetPath = path2.join(workspaceRoot, ".mcp.json");
+  logInvestigationStatus("Claude (project)", targetPath);
+  const projectConfigChanged = scheduleJsonTargets(
+    ctx,
+    [{ path: targetPath, allowCreate: true }],
+    updater
+  );
+  const claudeExecutable = findClaudeExecutable();
+  scheduleCliIfAvailable(ctx, claudeExecutable, [...CLAUDE_BASE_ARGS, "--scope", "user"], projectConfigChanged);
+  scheduleCliIfAvailable(
+    ctx,
+    claudeExecutable,
+    [...CLAUDE_BASE_ARGS, "--scope", "project"],
+    projectConfigChanged,
+    { cwd: workspaceRoot }
+  );
+}
+function scheduleWindsurfConfigs(ctx, homeDir) {
+  const updater = createServerUpdater("mcpServers", { serverUrl: MCP_SERVER_URL });
+  logMcpVerbose("Scheduling Windsurf MCP configs", { homeDir });
+  const paths = getWindsurfConfigPaths(homeDir);
+  paths.forEach((configPath) => logInvestigationStatus("Windsurf", configPath));
+  scheduleJsonTargets(ctx, paths.map((configPath) => ({ path: configPath })), updater);
+}
+function scheduleGeminiConfig(ctx, homeDir) {
+  const updater = createServerUpdater("mcpServers", {
+    httpUrl: MCP_SERVER_URL,
+    headers: { Accept: MCP_ACCEPT_HEADER }
+  });
+  logMcpVerbose("Scheduling Gemini MCP configs", { homeDir });
+  const targetPath = path2.join(homeDir, ".gemini", "settings.json");
+  logInvestigationStatus("Gemini", targetPath);
+  scheduleJsonTargets(
+    ctx,
+    [{ path: targetPath }],
+    updater
+  );
+}
+function scheduleJsonFileUpdate(ctx, fullPath, update, options2 = {}) {
+  logMcpVerbose("scheduleJsonFileUpdate invoked", { fullPath, allowCreate: options2.allowCreate });
+  if (!fullPath) {
+    logMcpVerbose("scheduleJsonFileUpdate skipped: no path provided");
+    return false;
+  }
+  const allowCreate = options2.allowCreate ?? false;
+  if (!shouldWriteConfigFile(fullPath, { allowCreate })) {
+    logMcpVerbose("scheduleJsonFileUpdate skipped: shouldWriteConfigFile returned false", { fullPath, allowCreate });
+    return false;
+  }
+  const absolutePath = path2.resolve(fullPath);
+  const info = readJsonOrEmpty(absolutePath);
+  logMcpVerbose("scheduleJsonFileUpdate current file info", { absolutePath, existed: info.existed, parseError: info.parseError?.message });
+  const draft = cloneJsonRecord(info.data);
+  const updated = update(draft);
+  if (!updated) {
+    logMcpVerbose("scheduleJsonFileUpdate skipped: updater returned nullish", { absolutePath });
+    return false;
+  }
+  const nextContent = JSON.stringify(updated, null, 2) + "\n";
+  const currentContent = info.existed && !info.parseError ? JSON.stringify(info.data, null, 2) + "\n" : null;
+  if (!info.parseError && currentContent === nextContent) {
+    logMcpVerbose("scheduleJsonFileUpdate skipped: content unchanged", { absolutePath });
+    return false;
+  }
+  ctx.registerWriteHandler(async () => {
+    await writeJsonFile(ctx, absolutePath, update, { allowCreate });
+  });
+  logMcpVerbose("scheduleJsonFileUpdate scheduled write", { absolutePath });
+  return true;
+}
+async function writeJsonFile(ctx, absolutePath, update, options2) {
+  logMcpVerbose("writeJsonFile invoked", { absolutePath, allowCreate: options2.allowCreate });
+  const allowCreate = options2.allowCreate ?? false;
+  const info = readJsonOrEmpty(absolutePath);
+  if (!info.existed && !allowCreate) {
+    logMcpVerbose("writeJsonFile skipped: file missing and allowCreate false", { absolutePath });
+    return;
+  }
+  let current = info.data;
+  if (info.parseError) {
+    console.warn(
+      ctx.colorize.yellow`Warning: Unable to parse MCP config at ${absolutePath}. It will be replaced with a fresh configuration.`
+    );
+    current = {};
+    logMcpVerbose("writeJsonFile parse error encountered; falling back to empty object", { absolutePath, error: info.parseError.message });
+  }
+  const draft = cloneJsonRecord(current);
+  const updated = update(draft);
+  if (!updated) {
+    logMcpVerbose("writeJsonFile skipped: updater returned nullish", { absolutePath });
+    return;
+  }
+  const nextContent = JSON.stringify(updated, null, 2) + "\n";
+  const currentContent = info.existed && !info.parseError ? JSON.stringify(current, null, 2) + "\n" : null;
+  if (currentContent === nextContent && !info.parseError) {
+    logMcpVerbose("writeJsonFile skipped: current content matches desired content", { absolutePath });
+    return;
+  }
+  if (ctx.isDryRun) {
+    console.log(`[DRY-RUN] Would write ${absolutePath}`);
+    logMcpVerbose("writeJsonFile dry-run; write skipped", { absolutePath });
+    return;
+  }
+  fs2.mkdirSync(path2.dirname(absolutePath), { recursive: true });
+  if (info.existed) {
+    try {
+      fs2.copyFileSync(absolutePath, `${absolutePath}.bak`);
+    } catch {
+    }
+  }
+  fs2.writeFileSync(absolutePath, nextContent, "utf-8");
+  await ctx.recordFileChange(absolutePath, info.existed);
+  logMcpVerbose("writeJsonFile completed write", { absolutePath, existed: info.existed });
+}
+function scheduleJsonTargets(ctx, targets, update) {
+  let changed = false;
+  logMcpVerbose("scheduleJsonTargets invoked", { targetCount: targets.length });
+  for (const target of targets) {
+    if (!target.path) continue;
+    if (scheduleJsonFileUpdate(ctx, target.path, update, { allowCreate: target.allowCreate })) {
+      changed = true;
+    }
+  }
+  logMcpVerbose("scheduleJsonTargets completed", { changed });
+  return changed;
+}
+function scheduleCliIfAvailable(ctx, command, args, shouldRun, options2) {
+  logMcpVerbose("scheduleCliIfAvailable invoked", { command, args, shouldRun });
+  if (!shouldRun) {
+    logMcpVerbose("scheduleCliIfAvailable skipped: shouldRun false", { command });
+    return;
+  }
+  const commandPath = getCommandPath(command);
+  if (!commandPath) {
+    logMcpVerbose("scheduleCliIfAvailable skipped: command not available", { command });
+    return;
+  }
+  logMcpVerbose("scheduleCliIfAvailable scheduling CLI registration", { command });
+  scheduleCliRegistration(ctx, commandPath, args, options2);
+}
+function createServerUpdater(containerKey, entry) {
+  logMcpVerbose("createServerUpdater invoked", { containerKey });
+  return (current) => {
+    const next = { ...current };
+    const servers = { ...next[containerKey] ?? {} };
+    servers[MCP_SERVER_NAME] = cloneJsonRecord(entry);
+    next[containerKey] = servers;
+    return next;
+  };
+}
+function getVsCodeUserConfigPaths(homeDir) {
+  const stable = /* @__PURE__ */ new Set();
+  const insiders = /* @__PURE__ */ new Set();
+  const platform2 = process.platform;
+  logMcpVerbose("getVsCodeUserConfigPaths invoked", { homeDir, platform: platform2 });
+  if (platform2 === "darwin") {
+    stable.add(path2.join(homeDir, "Library", "Application Support", "Code", "User", "mcp.json"));
+    insiders.add(path2.join(homeDir, "Library", "Application Support", "Code - Insiders", "User", "mcp.json"));
+  } else if (platform2 === "win32") {
+    const appData = process.env.APPDATA;
+    if (appData) {
+      stable.add(path2.join(appData, "Code", "User", "mcp.json"));
+      insiders.add(path2.join(appData, "Code - Insiders", "User", "mcp.json"));
+    }
+  } else {
+    stable.add(path2.join(homeDir, ".config", "Code", "User", "mcp.json"));
+    insiders.add(path2.join(homeDir, ".config", "Code - Insiders", "User", "mcp.json"));
+  }
+  return {
+    stable: Array.from(stable),
+    insiders: Array.from(insiders)
+  };
+}
+function getWindsurfConfigPaths(homeDir) {
+  const paths = /* @__PURE__ */ new Set();
+  logMcpVerbose("getWindsurfConfigPaths invoked", { homeDir, platform: process.platform });
+  if (process.platform === "darwin") {
+    paths.add(path2.join(homeDir, ".codeium", "windsurf", "mcp_config.json"));
+  } else if (process.platform === "win32") {
+    const appData = process.env.APPDATA;
+    if (appData) {
+      paths.add(path2.join(appData, "Codeium", "Windsurf", "mcp_config.json"));
+    }
+  } else {
+    paths.add(path2.join(homeDir, ".config", "Codeium", "Windsurf", "mcp_config.json"));
+    paths.add(path2.join(homeDir, ".codeium", "windsurf", "mcp_config.json"));
+    paths.add(path2.join(homeDir, ".var", "app", "com.codeium.windsurf", "config", "Codeium", "Windsurf", "mcp_config.json"));
+  }
+  return Array.from(paths);
+}
+function readJsonOrEmpty(fullPath) {
+  logMcpVerbose("readJsonOrEmpty invoked", { fullPath });
+  if (!fs2.existsSync(fullPath)) {
+    logMcpVerbose("readJsonOrEmpty no file found", { fullPath });
+    return { existed: false, data: {}, parseError: null };
+  }
+  try {
+    const raw = fs2.readFileSync(fullPath, "utf-8");
+    const data = raw.trim() ? JSON.parse(raw) : {};
+    logMcpVerbose("readJsonOrEmpty parsed file", { fullPath, hasContent: Boolean(raw.trim()) });
+    return { existed: true, data, parseError: null };
+  } catch (error) {
+    const parseError = error instanceof Error ? error : new Error(String(error));
+    logMcpVerbose("readJsonOrEmpty parse error", { fullPath, error: parseError.message });
+    return { existed: true, data: {}, parseError };
+  }
+}
+function cloneJsonRecord(value) {
+  return JSON.parse(JSON.stringify(value));
+}
+function scheduleCliRegistration(ctx, command, args, options2 = {}) {
+  logMcpVerbose("scheduleCliRegistration invoked", { command, args, options: options2 });
+  ctx.registerCommandHandler(async () => {
+    try {
+      await ctx.runScheduledCommand(command, args, options2, {
+        recordInCommandsExecuted: false
+      });
+    } catch (error) {
+      logMcpVerbose("scheduleCliRegistration encountered error. Ignoring.", { command, args, options: options2, error: error instanceof Error ? { message: error.message, stack: error.stack } : error });
+    }
+  });
+}
+function logMcpVerbose(message, details) {
+  logVerbose(`[mcp] ${message}`, details);
+}
+function logInvestigationStatus(editorLabel, configPath, scope) {
+  const exists = fs2.existsSync(configPath);
+  logMcpVerbose(`Investigating ${editorLabel} config${scope ? ` (${scope})` : ""}`, { path: configPath, exists });
+}
+
 // src/index.ts
 var jsLikeFileExtensions = [
   "mtsx",
@@ -124,12 +485,16 @@ function resolveOnQuestionMode(opt) {
   throw new UserError(`Invalid argument for --on-question: "${opt}". Valid modes are: "ask", "guess", "error", "default".`);
 }
 var program = new Command();
-program.name(package_default.name).description("Stack Auth Initialization Tool").version(package_default.version).argument("[project-path]", "Path to your project").usage(`[project-path] [options]`).option("--dry-run", "Run without making any changes").option("--neon", "Use Neon database").option("--js", "Initialize for JavaScript project").option("--next", "Initialize for Next.js project").option("--react", "Initialize for React project").option("--npm", "Use npm as package manager").option("--yarn", "Use yarn as package manager").option("--pnpm", "Use pnpm as package manager").option("--bun", "Use bun as package manager").option("--client", "Initialize client-side only").option("--server", "Initialize server-side only").option("--project-id <project-id>", "Project ID to use in setup").option("--publishable-client-key <publishable-client-key>", "Publishable client key to use in setup").option("--no-browser", "Don't open browser for environment variable setup").option("--on-question <mode>", "How to handle interactive questions: ask | guess | error | default", "default").addHelpText("after", `
+program.name(package_default.name).description("Stack Auth Initialization Tool").version(package_default.version).argument("[project-path]", "Path to your project").usage(`[project-path] [options]`).option("--dry-run", "Run without making any changes").option("--neon", "Use Neon database").option("--js", "Initialize for JavaScript project").option("--next", "Initialize for Next.js project").option("--react", "Initialize for React project").option("--npm", "Use npm as package manager").option("--yarn", "Use yarn as package manager").option("--pnpm", "Use pnpm as package manager").option("--bun", "Use bun as package manager").option("--client", "Initialize client-side only").option("--server", "Initialize server-side only").option("--project-id <project-id>", "Project ID to use in setup").option("--publishable-client-key <publishable-client-key>", "Publishable client key to use in setup").option("--no-browser", "Don't open browser for environment variable setup").option("--on-question <mode>", "How to handle interactive questions: ask | guess | error | default", "default").option("--no-warn-uncommitted-changes", "Don't warn about uncommitted changes in the Git repository").addHelpText("after", `
 For more information, please visit https://docs.stack-auth.com/getting-started/setup`);
 program.parse();
 var options = program.opts();
 var savedProjectPath = program.args[0] || void 0;
-var isDryRun = options.dryRun || false;
+var verboseEnvRaw = process.env.STACK_VERBOSE;
+var parsedVerboseLevel = typeof verboseEnvRaw === "string" && verboseEnvRaw.trim().length > 0 ? Number.parseInt(verboseEnvRaw.trim(), 10) : 0;
+var verboseLevel = Number.isFinite(parsedVerboseLevel) ? Math.max(0, parsedVerboseLevel) : 0;
+var isVerbose = verboseLevel > 0;
+var isDryRun = options.dryRun || isTruthyEnv("STACK_DRY_RUN") || false;
 var isNeon = options.neon || false;
 var typeFromArgs = options.js ? "js" : options.next ? "next" : options.react ? "react" : void 0;
 var packageManagerFromArgs = options.npm ? "npm" : options.yarn ? "yarn" : options.pnpm ? "pnpm" : options.bun ? "bun" : void 0;
@@ -138,6 +503,7 @@ var isServer = options.server || false;
 var projectIdFromArgs = options.projectId;
 var publishableClientKeyFromArgs = options.publishableClientKey;
 var onQuestionMode = resolveOnQuestionMode(options.onQuestion);
+var warnUncommittedChanges = options.warnUncommittedChanges ?? true;
 var noBrowser = !options.browser;
 var ansis = {
   red: "\x1B[31m",
@@ -154,11 +520,16 @@ var colorize = {
   yellow: (strings, ...values) => ansis.yellow + templateIdentity(strings, ...values) + ansis.clear,
   bold: (strings, ...values) => ansis.bold + templateIdentity(strings, ...values) + ansis.clear
 };
+configureVerboseLogging({
+  level: verboseLevel,
+  formatter: (message) => colorize.blue`[verbose] ${message}`
+});
 var filesCreated = [];
 var filesModified = [];
 var commandsExecuted = [];
 var packagesToInstall = [];
 var writeFileHandlers = [];
+var deferredCommandHandlers = [];
 var nextSteps = [
   `Create an account and Stack Auth API key for your project on https://app.stack-auth.com`
 ];
@@ -171,6 +542,7 @@ var ph_client = new PostHog(STACK_AUTH_PUBLIC_HOG_KEY, {
 });
 var distinctId = crypto.randomUUID();
 async function capture(event, properties) {
+  logVerbose("capture event", { event, properties });
   ph_client.capture({
     event: `${EVENT_PREFIX}${event}`,
     distinctId,
@@ -194,6 +566,25 @@ async function main() {
        \u2588\u2588\u2588\u2588\u2588\u2588
   `);
   console.log();
+  logVerbose("Initialization run metadata", {
+    version: package_default.version,
+    cwd: process.cwd(),
+    args: program.args,
+    options: {
+      isDryRun,
+      isVerbose,
+      isNeon,
+      typeFromArgs,
+      packageManagerFromArgs,
+      isClient,
+      isServer,
+      projectIdFromArgs: Boolean(projectIdFromArgs),
+      publishableClientKeyFromArgs: Boolean(publishableClientKeyFromArgs),
+      noBrowser,
+      onQuestionMode,
+      verboseLevel
+    }
+  });
   await capture("start", {
     version: package_default.version,
     isDryRun,
@@ -203,15 +594,38 @@ async function main() {
     isClient,
     isServer,
     noBrowser,
-    platform: os.platform(),
-    arch: os.arch(),
+    platform: os2.platform(),
+    arch: os2.arch(),
     nodeVersion: process.version
   });
-  await new Promise((resolve) => resolve());
+  await new Promise((resolve3) => resolve3());
   await clearStdin();
   const projectPath = await getProjectPath();
+  await ensureGitWorkspaceIsReady(projectPath);
+  logVerbose("Project path prepared", { projectPath, isDryRun, isVerbose });
+  scheduleMcpConfiguration({
+    projectPath,
+    isDryRun,
+    colorize,
+    registerWriteHandler: (handler) => writeFileHandlers.push(handler),
+    registerCommandHandler: (handler) => deferredCommandHandlers.push(handler),
+    recordFileChange,
+    runScheduledCommand
+  });
+  nextSteps.push("Restart your MCP-enabled editors so they pick up the Stack Auth MCP.");
+  logVerbose("MCP configuration scheduled", {
+    writeHandlers: writeFileHandlers.length,
+    deferredCommands: deferredCommandHandlers.length
+  });
   const { packageJson: projectPackageJson } = await Steps.getProject();
   const type = await Steps.getProjectType({ packageJson: projectPackageJson });
+  logVerbose("Project inspection complete", {
+    detectedType: type,
+    dependencies: {
+      hasReact: Boolean(projectPackageJson.dependencies?.["react"]),
+      hasNext: Boolean(projectPackageJson.dependencies?.["next"])
+    }
+  });
   await capture("project-type-selected", {
     type,
     wasSpecifiedInArgs: !!typeFromArgs
@@ -222,6 +636,7 @@ async function main() {
   const convexIntegration = await Steps.maybeInstallConvexIntegration({ packageJson: projectPackageJson, type });
   if (convexIntegration) {
     nextSteps.push(...convexIntegration.instructions);
+    logVerbose("Convex integration detected", convexIntegration);
   }
   if (type === "next") {
     const projectInfo = await Steps.getNextProjectInfo({ packageJson: projectPackageJson });
@@ -263,7 +678,9 @@ async function main() {
       `Follow the instructions on how to use Stack Auth's vanilla SDK at http://docs.stack-auth.com/others/js-client`
     );
   }
+  logVerbose("Primary integration steps completed", { type, nextStepsCount: nextSteps.length });
   const { packageManager } = await Steps.getPackageManager();
+  logVerbose("Package manager determined", { packageManager });
   await capture(`package-manager-selected`, {
     packageManager,
     wasSpecifiedInArgs: !!packageManagerFromArgs
@@ -283,6 +700,10 @@ async function main() {
     shell: true,
     cwd: projectPath
   });
+  logVerbose("Dependency installation finished", {
+    packageManager,
+    packages: packagesToInstall
+  });
   await capture(`dependencies-installed`, {
     packageManager,
     packages: packagesToInstall
@@ -290,10 +711,13 @@ async function main() {
   console.log();
   console.log(colorize.bold`Writing files...`);
   console.log();
-  for (const writeFileHandler of writeFileHandlers) {
+  for (let i = 0; i < writeFileHandlers.length; i++) {
+    const writeFileHandler = writeFileHandlers[i];
+    logVerbose("Executing write handler", { index: i });
     await writeFileHandler();
   }
   console.log(`${colorize.green`√`} Done writing files`);
+  await runDeferredCommands();
   console.log("\n\n\n");
   console.log(colorize.bold`${colorize.green`Installation succeeded!`}`);
   console.log();
@@ -302,6 +726,9 @@ async function main() {
     console.log(`  ${colorize.blue`${command}`}`);
   }
   console.log();
+  console.log("MCP servers installed:");
+  console.log(`  ${colorize.green`https://mcp.stack-auth.com`}`);
+  console.log();
   console.log("Files written:");
   for (const file of filesModified) {
     console.log(`  ${colorize.yellow`${file}`}`);
@@ -378,34 +805,53 @@ main().catch(async (err) => {
 var Steps = {
   async getProject() {
     let projectPath = await getProjectPath();
-    if (!fs.existsSync(projectPath)) {
+    logVerbose("Steps.getProject invoked", { projectPath });
+    if (!fs3.existsSync(projectPath)) {
       throw new UserError(`The project path ${projectPath} does not exist`);
     }
-    const packageJsonPath = path.join(projectPath, "package.json");
-    if (!fs.existsSync(packageJsonPath)) {
+    const packageJsonPath = path3.join(projectPath, "package.json");
+    if (!fs3.existsSync(packageJsonPath)) {
       throw new UserError(
         `The package.json file does not exist in the project path ${projectPath}. You must initialize a new project first before installing Stack.`
       );
     }
-    const packageJsonText = fs.readFileSync(packageJsonPath, "utf-8");
+    const packageJsonText = fs3.readFileSync(packageJsonPath, "utf-8");
     let packageJson;
     try {
       packageJson = JSON.parse(packageJsonText);
     } catch (e) {
       throw new UserError(`package.json file is not valid JSON: ${e}`);
     }
+    logVerbose("Steps.getProject completed", {
+      packageJsonPath,
+      dependencyCounts: {
+        dependencies: Object.keys(packageJson.dependencies ?? {}).length,
+        devDependencies: Object.keys(packageJson.devDependencies ?? {}).length
+      }
+    });
     return { packageJson };
   },
   async getProjectType({ packageJson }) {
-    if (typeFromArgs) return typeFromArgs;
+    if (typeFromArgs) {
+      logVerbose("Steps.getProjectType using CLI override", { typeFromArgs });
+      return typeFromArgs;
+    }
+    logVerbose("Steps.getProjectType attempting autodetect", {
+      hasNext: Boolean(packageJson.dependencies?.["next"] || packageJson.devDependencies?.["next"]),
+      hasReact: Boolean(packageJson.dependencies?.["react"] || packageJson.dependencies?.["react-dom"]),
+      onQuestionMode
+    });
     const maybeNextProject = await Steps.maybeGetNextProjectInfo({ packageJson });
     if (!("error" in maybeNextProject)) {
+      logVerbose("Steps.getProjectType resolved to Next.js project");
       return "next";
     }
     if (packageJson.dependencies?.["react"] || packageJson.dependencies?.["react-dom"]) {
+      logVerbose("Steps.getProjectType resolved to React project");
       return "react";
     }
     if (onQuestionMode === "guess") {
+      logVerbose("Steps.getProjectType defaulting to JS due to --on-question=guess");
       return "js";
     }
     if (onQuestionMode === "error") {
@@ -417,12 +863,14 @@ var Steps = {
         name: "type",
         message: "Which integration would you like to install?",
         choices: [
-          { name: "None (vanilla JS, Node.js, etc)", value: "js" },
+          { name: "Vanilla JS (other/no framework)", value: "js" },
+          { name: "Node.js", value: "js" },
           { name: "React", value: "react" },
           { name: "Next.js", value: "next" }
         ]
       }
     ]);
+    logVerbose("Steps.getProjectType received user selection", { type });
     return type;
   },
   async getStackPackageName(type, install = false) {
@@ -431,42 +879,62 @@ var Steps = {
       next: install && process.env.STACK_NEXT_INSTALL_PACKAGE_NAME_OVERRIDE || "@stackframe/stack",
       react: install && process.env.STACK_REACT_INSTALL_PACKAGE_NAME_OVERRIDE || "@stackframe/react"
     };
-    return mapping[type];
+    const packageName = mapping[type];
+    logVerbose("Steps.getStackPackageName resolved", { type, install, packageName });
+    return packageName;
   },
   async addStackPackage(type) {
-    packagesToInstall.push(await Steps.getStackPackageName(type, true));
+    const pkgName = await Steps.getStackPackageName(type, true);
+    logVerbose("Steps.addStackPackage scheduling install", { pkgName });
+    packagesToInstall.push(pkgName);
   },
   async getNextProjectInfo({ packageJson }) {
+    logVerbose("Steps.getNextProjectInfo invoked");
     const maybe = await Steps.maybeGetNextProjectInfo({ packageJson });
-    if ("error" in maybe) throw new UserError(maybe.error);
+    if ("error" in maybe) {
+      logVerbose("Steps.getNextProjectInfo failed validation", maybe);
+      throw new UserError(maybe.error);
+    }
+    logVerbose("Steps.getNextProjectInfo resolved", maybe);
     return maybe;
   },
   async maybeGetNextProjectInfo({ packageJson }) {
     const projectPath = await getProjectPath();
+    logVerbose("Steps.maybeGetNextProjectInfo evaluating Next.js eligibility", { projectPath });
     const nextVersionInPackageJson = packageJson.dependencies?.["next"] ?? packageJson.devDependencies?.["next"];
     if (!nextVersionInPackageJson) {
+      logVerbose("Steps.maybeGetNextProjectInfo missing Next dependency");
       return { error: `The project at ${projectPath} does not appear to be a Next.js project, or does not have 'next' installed as a dependency.` };
     }
     if (!nextVersionInPackageJson.includes("14") && !nextVersionInPackageJson.includes("15") && nextVersionInPackageJson !== "latest") {
+      logVerbose("Steps.maybeGetNextProjectInfo found unsupported Next version", { version: nextVersionInPackageJson });
       return { error: `The project at ${projectPath} is using an unsupported version of Next.js (found ${nextVersionInPackageJson}).
 
 Only Next.js 14 & 15 projects are currently supported. See Next's upgrade guide: https://nextjs.org/docs/app/building-your-application/upgrading/version-14` };
     }
-    const hasSrcAppFolder = fs.existsSync(path.join(projectPath, "src/app"));
-    const srcPath = path.join(projectPath, hasSrcAppFolder ? "src" : "");
-    const appPath = path.join(srcPath, "app");
-    if (!fs.existsSync(appPath)) {
+    const hasSrcAppFolder = fs3.existsSync(path3.join(projectPath, "src/app"));
+    const srcPath = path3.join(projectPath, hasSrcAppFolder ? "src" : "");
+    const appPath = path3.join(srcPath, "app");
+    if (!fs3.existsSync(appPath)) {
+      logVerbose("Steps.maybeGetNextProjectInfo missing Next app directory", { appPath });
       return { error: `The app path ${appPath} does not exist. Only the Next.js App router is supported \u2014 are you maybe on the Pages router instead?` };
     }
-    const nextConfigPathWithoutExtension = path.join(projectPath, "next.config");
+    const nextConfigPathWithoutExtension = path3.join(projectPath, "next.config");
     const nextConfigFileExtension = await findJsExtension(
       nextConfigPathWithoutExtension
     );
     const nextConfigPath = nextConfigPathWithoutExtension + "." + (nextConfigFileExtension ?? "js");
-    if (!fs.existsSync(nextConfigPath)) {
+    if (!fs3.existsSync(nextConfigPath)) {
+      logVerbose("Steps.maybeGetNextProjectInfo missing next.config file", { nextConfigPath });
       return { error: `Expected file at ${nextConfigPath} for Next.js projects.` };
     }
     const dryUpdateNextLayoutFileResult = await Steps.dryUpdateNextLayoutFile({ appPath, defaultExtension: "jsx" });
+    logVerbose("Steps.maybeGetNextProjectInfo success", {
+      projectPath,
+      srcPath,
+      appPath,
+      detectedExtension: dryUpdateNextLayoutFileResult.fileExtension
+    });
     return {
       type: "next",
       srcPath,
@@ -477,17 +945,21 @@ Only Next.js 14 & 15 projects are currently supported. See Next's upgrade guide:
   },
   async writeEnvVars(type) {
     const projectPath = await getProjectPath();
-    if (type !== "next") return false;
-    const envLocalPath = path.join(projectPath, ".env.local");
+    logVerbose("Steps.writeEnvVars invoked", { type, projectPath });
+    if (type !== "next") {
+      logVerbose("Steps.writeEnvVars skipped", { reason: "non-next-project" });
+      return false;
+    }
+    const envLocalPath = path3.join(projectPath, ".env.local");
     const potentialEnvLocations = [
-      path.join(projectPath, ".env"),
-      path.join(projectPath, ".env.development"),
-      path.join(projectPath, ".env.default"),
-      path.join(projectPath, ".env.defaults"),
-      path.join(projectPath, ".env.example"),
+      path3.join(projectPath, ".env"),
+      path3.join(projectPath, ".env.development"),
+      path3.join(projectPath, ".env.default"),
+      path3.join(projectPath, ".env.defaults"),
+      path3.join(projectPath, ".env.example"),
       envLocalPath
     ];
-    if (potentialEnvLocations.every((p) => !fs.existsSync(p))) {
+    if (potentialEnvLocations.every((p) => !fs3.existsSync(p))) {
       const envContent = noBrowser ? `# Stack Auth keys
 # To get these variables:
 # 1. Go to https://app.stack-auth.com
@@ -503,43 +975,54 @@ NEXT_PUBLIC_STACK_PUBLISHABLE_CLIENT_KEY="${publishableClientKeyFromArgs ?? ""}"
 STACK_SECRET_SERVER_KEY=
 `;
       laterWriteFile(envLocalPath, envContent);
+      logVerbose("Steps.writeEnvVars scheduled .env.local creation", { envLocalPath });
       return true;
     }
+    logVerbose("Steps.writeEnvVars found existing env files", { potentialEnvLocations });
     return false;
   },
   async maybeInstallConvexIntegration({ packageJson, type }) {
     const hasConvexDependency = Boolean(packageJson.dependencies?.["convex"] || packageJson.devDependencies?.["convex"]);
     if (!hasConvexDependency) {
+      logVerbose("Steps.maybeInstallConvexIntegration skipped", { reason: "no-convex-dependency" });
       return null;
     }
     const projectPath = await getProjectPath();
-    const convexDir = path.join(projectPath, "convex");
-    if (!fs.existsSync(convexDir)) {
+    const convexDir = path3.join(projectPath, "convex");
+    if (!fs3.existsSync(convexDir)) {
+      logVerbose("Steps.maybeInstallConvexIntegration skipped", { reason: "missing-convex-dir", convexDir });
       return null;
     }
     const stackPackageName = await Steps.getStackPackageName(type);
     const instructions = [];
-    const authConfigPath = path.join(convexDir, "auth.config.ts");
+    logVerbose("Steps.maybeInstallConvexIntegration configuring", { convexDir, stackPackageName });
+    const authConfigPath = path3.join(convexDir, "auth.config.ts");
     const desiredAuthConfig = createConvexAuthConfigContent({ stackPackageName, type });
     const existingAuthConfig = await readFile(authConfigPath);
     if (!existingAuthConfig || !existingAuthConfig.includes("getConvexProvidersConfig") && !existingAuthConfig.includes("@stackframe/")) {
       laterWriteFile(authConfigPath, desiredAuthConfig);
+      logVerbose("Steps.maybeInstallConvexIntegration scheduled auth.config.ts update", { authConfigPath });
     }
-    const convexConfigPath = path.join(convexDir, "convex.config.ts");
+    const convexConfigPath = path3.join(convexDir, "convex.config.ts");
     const existingConvexConfig = await readFile(convexConfigPath);
     const desiredConvexConfig = createConvexIntegrationConvexConfigContent(stackPackageName);
     let needsManualConvexConfig = false;
     if (!existingConvexConfig) {
       laterWriteFile(convexConfigPath, desiredConvexConfig);
+      logVerbose("Steps.maybeInstallConvexIntegration writing convex.config.ts from template", { convexConfigPath });
     } else if (existingConvexConfig.includes("app.use(stackAuthComponent") && existingConvexConfig.includes("/convex.config") && existingConvexConfig.includes("stackframe")) {
+      logVerbose("Steps.maybeInstallConvexIntegration detected existing convex.config.ts integration", { convexConfigPath });
     } else {
       const integratedContent = integrateConvexConfig(existingConvexConfig, stackPackageName);
       if (integratedContent) {
         laterWriteFile(convexConfigPath, integratedContent);
+        logVerbose("Steps.maybeInstallConvexIntegration merged convex.config.ts content", { convexConfigPath });
       } else if (isSimpleConvexConfig(existingConvexConfig)) {
         laterWriteFile(convexConfigPath, desiredConvexConfig);
+        logVerbose("Steps.maybeInstallConvexIntegration replaced simple convex.config.ts", { convexConfigPath });
       } else {
         needsManualConvexConfig = true;
+        logVerbose("Steps.maybeInstallConvexIntegration requiring manual convex.config.ts review", { convexConfigPath });
       }
     }
     if (needsManualConvexConfig) {
@@ -549,14 +1032,16 @@ STACK_SECRET_SERVER_KEY=
     if (convexClientUpdateResult.skippedFiles.length > 0) {
       instructions.push("Review your Convex client setup and call stackClientApp.getConvexClientAuth({}) or stackServerApp.getConvexClientAuth({}) manually where needed.");
     }
+    logVerbose("Steps.maybeInstallConvexIntegration client update summary", convexClientUpdateResult);
     instructions.push(
       "Set the Stack Auth environment variables in Convex (Deployment \u2192 Settings \u2192 Environment Variables).",
       "Verify your Convex clients call stackClientApp.getConvexClientAuth({}) or stackServerApp.getConvexClientAuth({}) so they share authentication with Stack Auth."
     );
+    logVerbose("Steps.maybeInstallConvexIntegration completed", { instructions });
     return { instructions };
   },
   async dryUpdateNextLayoutFile({ appPath, defaultExtension }) {
-    const layoutPathWithoutExtension = path.join(appPath, "layout");
+    const layoutPathWithoutExtension = path3.join(appPath, "layout");
     const layoutFileExtension = await findJsExtension(layoutPathWithoutExtension) ?? defaultExtension;
     const layoutPath = layoutPathWithoutExtension + "." + layoutFileExtension;
     const layoutContent = await readFile(layoutPath) ?? throwErr(
@@ -574,22 +1059,26 @@ STACK_SECRET_SERVER_KEY=
     };
   },
   async updateNextLayoutFile(projectInfo) {
+    logVerbose("Steps.updateNextLayoutFile invoked", projectInfo);
     const res = await Steps.dryUpdateNextLayoutFile(projectInfo);
     laterWriteFile(res.path, res.updatedContent);
+    logVerbose("Steps.updateNextLayoutFile scheduled write", { path: res.path });
     return res;
   },
   async writeStackAppFile({ type, srcPath, defaultExtension, indentation }, clientOrServer, alsoHasClient) {
+    logVerbose("Steps.writeStackAppFile invoked", { type, srcPath, clientOrServer, alsoHasClient });
     const packageName = await Steps.getStackPackageName(type);
     const clientOrServerCap = {
       client: "Client",
       server: "Server"
     }[clientOrServer];
     const relativeStackAppPath = `stack/${clientOrServer}`;
-    const stackAppPathWithoutExtension = path.join(srcPath, relativeStackAppPath);
+    const stackAppPathWithoutExtension = path3.join(srcPath, relativeStackAppPath);
     const stackAppFileExtension = await findJsExtension(stackAppPathWithoutExtension) ?? defaultExtension;
     const stackAppPath = stackAppPathWithoutExtension + "." + stackAppFileExtension;
     const stackAppContent = await readFile(stackAppPath);
     if (stackAppContent) {
+      logVerbose("Steps.writeStackAppFile found existing file", { stackAppPath });
       if (!stackAppContent.includes("@stackframe/")) {
         throw new UserError(
           `A file at the path ${stackAppPath} already exists. Stack uses the stack/${clientOrServer}.ts file to initialize the Stack SDK. Please remove the existing file and try again.`
@@ -604,7 +1093,7 @@ STACK_SECRET_SERVER_KEY=
     const jsOptions = type === "js" ? [
       `
 
-${indentation}// get your Stack Auth API keys from https://app.stack-auth.com${clientOrServer === "client" ? ` and store them in a safe place (eg. environment variables)` : ""}`,
+${indentation}// get your Stack Auth API keys from https://app.stack-auth.com${clientOrServer === "client" ? ` and store them in a safe place (e.g. environment variables)` : ""}`,
       `${projectIdFromArgs ? `${indentation}projectId: ${JSON.stringify(projectIdFromArgs)},` : ""}`,
       `${indentation}publishableClientKey: ${publishableClientKeyWrite},`,
       `${clientOrServer === "server" ? `${indentation}secretServerKey: process.env.STACK_SECRET_SERVER_KEY,` : ""}`
@@ -631,16 +1120,19 @@ ${shouldInheritFromClient ? `${indentation}inheritsFrom: stackClientApp,` : `${i
 });
       `.trim() + "\n"
     );
+    logVerbose("Steps.writeStackAppFile scheduled creation", { stackAppPath, inheritsFromClient: shouldInheritFromClient });
     return { fileName: stackAppPath };
   },
   async writeReactClientFile({ srcPath, defaultExtension, indentation, hasReactRouterDom }) {
+    logVerbose("Steps.writeReactClientFile invoked", { srcPath, hasReactRouterDom });
     const packageName = await Steps.getStackPackageName("react");
     const relativeStackAppPath = `stack/client`;
-    const stackAppPathWithoutExtension = path.join(srcPath, relativeStackAppPath);
+    const stackAppPathWithoutExtension = path3.join(srcPath, relativeStackAppPath);
     const stackAppFileExtension = await findJsExtension(stackAppPathWithoutExtension) ?? defaultExtension;
     const stackAppPath = stackAppPathWithoutExtension + "." + stackAppFileExtension;
     const stackAppContent = await readFile(stackAppPath);
     if (stackAppContent) {
+      logVerbose("Steps.writeReactClientFile found existing file", { stackAppPath });
       if (!stackAppContent.includes("@stackframe/")) {
         throw new UserError(`A file at the path ${stackAppPath} already exists. Stack uses the stack/client.ts file to initialize the Stack SDK. Please remove the existing file and try again.`);
       }
@@ -667,10 +1159,12 @@ ${indentation}publishableClientKey: ${publishableClientKeyWrite}${redirectMethod
 }); 
 `
     );
+    logVerbose("Steps.writeReactClientFile scheduled creation", { stackAppPath });
     return { fileName: stackAppPath };
   },
   async writeNextHandlerFile(projectInfo) {
-    const handlerPathWithoutExtension = path.join(
+    logVerbose("Steps.writeNextHandlerFile invoked", projectInfo);
+    const handlerPathWithoutExtension = path3.join(
       projectInfo.appPath,
       "handler/[...stack]/page"
     );
@@ -678,6 +1172,7 @@ ${indentation}publishableClientKey: ${publishableClientKeyWrite}${redirectMethod
     const handlerPath = handlerPathWithoutExtension + "." + handlerFileExtension;
     const handlerContent = await readFile(handlerPath);
     if (handlerContent && !handlerContent.includes("@stackframe/")) {
+      logVerbose("Steps.writeNextHandlerFile found conflicting file", { handlerPath });
       throw new UserError(
         `A file at the path ${handlerPath} already exists.Stack uses the / handler path to handle incoming requests.Please remove the existing file and try again.`
       );
@@ -694,7 +1189,8 @@ ${projectInfo.indentation} return <StackHandler fullPage app = { stackServerApp
     );
   },
   async writeNextLoadingFile(projectInfo) {
-    let loadingPathWithoutExtension = path.join(projectInfo.appPath, "loading");
+    logVerbose("Steps.writeNextLoadingFile invoked", projectInfo);
+    let loadingPathWithoutExtension = path3.join(projectInfo.appPath, "loading");
     const loadingFileExtension = await findJsExtension(loadingPathWithoutExtension) ?? projectInfo.defaultExtension;
     const loadingPath = loadingPathWithoutExtension + "." + loadingFileExtension;
     laterWriteFileIfNotExists(
@@ -709,9 +1205,13 @@ ${projectInfo.indentation}return <></>;
     );
   },
   async getPackageManager() {
-    if (packageManagerFromArgs) return { packageManager: packageManagerFromArgs };
+    if (packageManagerFromArgs) {
+      logVerbose("Steps.getPackageManager using CLI override", { packageManager: packageManagerFromArgs });
+      return { packageManager: packageManagerFromArgs };
+    }
     const packageManager = await promptPackageManager();
     const versionCommand = `${packageManager} --version`;
+    logVerbose("Steps.getPackageManager checking binary availability", { packageManager });
     try {
       await shellNicelyFormatted(versionCommand, { shell: true, quiet: true });
     } catch (err) {
@@ -720,6 +1220,7 @@ ${projectInfo.indentation}return <></>;
         `Could not run the package manager command '${versionCommand}'. Please make sure ${packageManager} is installed on your system.`
       );
     }
+    logVerbose("Steps.getPackageManager resolved", { packageManager });
     return { packageManager };
   },
   async ensureReady(type) {
@@ -741,49 +1242,70 @@ ${projectInfo.indentation}return <></>;
     if (!isReady) {
       throw new UserError("Installation aborted.");
     }
+    logVerbose("Steps.ensureReady confirmed", { type, projectPath, isReady });
   },
   async getServerOrClientOrBoth() {
-    if (isClient && isServer) return ["server", "client"];
-    if (isServer) return ["server"];
-    if (isClient) return ["client"];
-    if (onQuestionMode === "guess") return ["server", "client"];
+    logVerbose("Steps.getServerOrClientOrBoth invoked", { isClientFlag: isClient, isServerFlag: isServer, onQuestionMode });
+    if (isClient && isServer) {
+      logVerbose("Steps.getServerOrClientOrBoth using CLI flags", { selection: ["server", "client"] });
+      return ["server", "client"];
+    }
+    if (isServer) {
+      logVerbose("Steps.getServerOrClientOrBoth using server flag");
+      return ["server"];
+    }
+    if (isClient) {
+      logVerbose("Steps.getServerOrClientOrBoth using client flag");
+      return ["client"];
+    }
+    if (onQuestionMode === "guess") {
+      logVerbose("Steps.getServerOrClientOrBoth defaulting to both");
+      return ["server", "client"];
+    }
     if (onQuestionMode === "error") {
       throw new UnansweredQuestionError("Ambiguous installation type. Re-run with --server, --client, or both.");
     }
-    return (await inquirer.prompt([{
+    const selection = (await inquirer.prompt([{
       type: "list",
       name: "type",
       message: "Do you want to use Stack Auth on the server, or on the client?",
       choices: [
-        { name: "Client (eg. Vite, HTML)", value: ["client"] },
-        { name: "Server (eg. Node.js)", value: ["server"] },
-        { name: "Both", value: ["server", "client"] }
+        { name: "Client (e.g. Vite, HTML)", value: ["client"] },
+        { name: "Server (e.g. Node.js)", value: ["server"] },
+        { name: "Both (e.g. Next.js)", value: ["server", "client"] }
       ]
     }])).type;
+    logVerbose("Steps.getServerOrClientOrBoth received user selection", { selection });
+    return selection;
   },
   /**
-   * note: this is a heuristic, specific frameworks may have better heuristics (eg. the Next.js code uses the extension of the global layout file)
-   */
+   * note: this is a heuristic, specific frameworks may have better heuristics (e.g. the Next.js code uses the extension of the global layout file)
+  */
   async guessDefaultFileExtension() {
     const projectPath = await getProjectPath();
-    const hasTsConfig = fs.existsSync(
-      path.join(projectPath, "tsconfig.json")
+    const hasTsConfig = fs3.existsSync(
+      path3.join(projectPath, "tsconfig.json")
     );
-    return hasTsConfig ? "ts" : "js";
+    const extension = hasTsConfig ? "ts" : "js";
+    logVerbose("Steps.guessDefaultFileExtension result", { projectPath, hasTsConfig, extension });
+    return extension;
   },
   /**
-   * note: this is a heuristic, specific frameworks may have better heuristics (eg. the Next.js code uses the location of the app folder)
+   * note: this is a heuristic, specific frameworks may have better heuristics (e.g. the Next.js code uses the location of the app folder)
    */
   async guessSrcPath() {
     const projectPath = await getProjectPath();
-    const potentialSrcPath = path.join(projectPath, "src");
-    const hasSrcFolder = fs.existsSync(
-      path.join(projectPath, "src")
+    const potentialSrcPath = path3.join(projectPath, "src");
+    const hasSrcFolder = fs3.existsSync(
+      path3.join(projectPath, "src")
     );
-    return hasSrcFolder ? potentialSrcPath : projectPath;
+    const resolvedPath = hasSrcFolder ? potentialSrcPath : projectPath;
+    logVerbose("Steps.guessSrcPath result", { hasSrcFolder, resolvedPath });
+    return resolvedPath;
   }
 };
 async function getUpdatedLayout(originalLayout) {
+  logVerbose("getUpdatedLayout invoked", { length: originalLayout.length });
   let layout = originalLayout;
   const indentation = guessIndentation(originalLayout);
   const firstImportLocationM1 = /\simport\s/.exec(layout)?.index;
@@ -797,11 +1319,13 @@ import { stackClientApp } from "../stack/client";
   const bodyOpenTag = /<\s*body[^>]*>/.exec(layout);
   const bodyCloseTag = /<\s*\/\s*body[^>]*>/.exec(layout);
   if (!bodyOpenTag || !bodyCloseTag) {
+    logVerbose("getUpdatedLayout missing body tag");
     return void 0;
   }
   const bodyOpenEndIndex = bodyOpenTag.index + bodyOpenTag[0].length;
   const bodyCloseStartIndex = bodyCloseTag.index;
   if (bodyCloseStartIndex <= bodyOpenEndIndex) {
+    logVerbose("getUpdatedLayout invalid body indices", { bodyOpenEndIndex, bodyCloseStartIndex });
     return void 0;
   }
   const lines = layout.split("\n");
@@ -817,6 +1341,7 @@ import { stackClientApp } from "../stack/client";
   const insertClose = "</StackTheme></StackProvider>";
   layout = layout.slice(0, bodyCloseStartIndex) + insertClose + layout.slice(bodyCloseStartIndex);
   layout = layout.slice(0, bodyOpenEndIndex) + insertOpen + layout.slice(bodyOpenEndIndex);
+  logVerbose("getUpdatedLayout success", { updatedLength: layout.length });
   return {
     content: `${layout}`,
     indentation
@@ -847,12 +1372,14 @@ function getLineIndex(lines, stringIndex) {
   );
 }
 async function getProjectPath() {
+  logVerbose("getProjectPath invoked", { savedProjectPath });
   if (savedProjectPath === void 0) {
     savedProjectPath = process.cwd();
-    const askForPathModification = !fs.existsSync(
-      path.join(savedProjectPath, "package.json")
+    const askForPathModification = !fs3.existsSync(
+      path3.join(savedProjectPath, "package.json")
     );
     if (askForPathModification) {
+      logVerbose("getProjectPath did not find package.json in cwd", { cwd: savedProjectPath });
       if (onQuestionMode === "guess" || onQuestionMode === "error") {
         throw new UserError(`No package.json file found in ${savedProjectPath}. Re-run providing the project path argument (e.g. 'init-stack <project-path>').`);
       }
@@ -864,35 +1391,136 @@ async function getProjectPath() {
           default: "."
         }
       ])).newPath;
+      logVerbose("getProjectPath received manual input", { savedProjectPath });
     }
   }
+  logVerbose("getProjectPath resolved", { savedProjectPath });
   return savedProjectPath;
 }
+async function ensureGitWorkspaceIsReady(projectPath) {
+  if (!warnUncommittedChanges) {
+    logVerbose("ensureGitWorkspaceIsReady skipped as requested by user");
+    return;
+  }
+  logVerbose("ensureGitWorkspaceIsReady invoked", { projectPath });
+  let isGitRepo = false;
+  try {
+    const gitRepoResult = child_process2.spawnSync(
+      "git",
+      ["rev-parse", "--is-inside-work-tree"],
+      {
+        shell: true,
+        cwd: projectPath,
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "ignore"]
+      }
+    );
+    isGitRepo = gitRepoResult.status === 0 && gitRepoResult.stdout.trim() === "true";
+  } catch (e) {
+    logVerbose("ensureGitWorkspaceIsReady failed to detect git repository", { error: e });
+    return;
+  }
+  if (!isGitRepo) {
+    logVerbose("ensureGitWorkspaceIsReady skipping", { reason: "not-a-git-repo" });
+    return;
+  }
+  const statusResult = child_process2.spawnSync(
+    "git",
+    ["status", "--porcelain"],
+    {
+      shell: true,
+      cwd: projectPath,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "pipe"]
+    }
+  );
+  if (statusResult.error || statusResult.status !== 0) {
+    logVerbose("ensureGitWorkspaceIsReady git status failed", { status: statusResult.status, error: statusResult.error });
+    return;
+  }
+  const lines = statusResult.stdout.split("\n").map((line) => line.replace(/\r$/, "")).filter((line) => line.length > 0);
+  const unstagedLines = lines.filter((line) => {
+    if (line.startsWith("!!")) return false;
+    if (line.startsWith("??")) return true;
+    if (line.length < 2) return false;
+    const workingTreeStatus = line[1];
+    return Boolean(workingTreeStatus && workingTreeStatus !== " ");
+  });
+  if (unstagedLines.length === 0) {
+    logVerbose("ensureGitWorkspaceIsReady clean working tree");
+    return;
+  }
+  const changedFiles = unstagedLines.map((line) => {
+    const filePath = line.slice(3).trim();
+    return filePath.length > 0 ? filePath : line;
+  });
+  console.log();
+  console.log(colorize.yellow`Detected unstaged/uncommitted changes in your Git repository:`);
+  const filesToShow = changedFiles.slice(0, 10);
+  for (const file of filesToShow) {
+    console.log(`  - ${file}`);
+  }
+  if (changedFiles.length > filesToShow.length) {
+    console.log(`  - ...and ${changedFiles.length - filesToShow.length} more`);
+  }
+  console.log(colorize.yellow`You may want to stage and commit these changes before installing Stack Auth, so you can review the changes afterwards.`);
+  console.log();
+  if (onQuestionMode === "guess") {
+    console.log(colorize.yellow`Continuing because --on-question=guess.`);
+    return;
+  }
+  if (onQuestionMode === "error") {
+    throw new UnansweredQuestionError("Unstaged changes detected in the project directory");
+  }
+  const { proceed } = await inquirer.prompt([
+    {
+      type: "confirm",
+      name: "proceed",
+      message: "Continue with Stack initialization anyway?",
+      default: false
+    }
+  ]);
+  if (!proceed) {
+    throw new UserError("Aborting Stack initialization to avoid overwriting unstaged changes.");
+  }
+  logVerbose("ensureGitWorkspaceIsReady user confirmed proceed despite unstaged changes");
+}
 async function findJsExtension(fullPathWithoutExtension) {
+  logVerbose("findJsExtension invoked", { fullPathWithoutExtension });
   for (const ext of jsLikeFileExtensions) {
     const fullPath = fullPathWithoutExtension + "." + ext;
-    if (fs.existsSync(fullPath)) {
+    if (fs3.existsSync(fullPath)) {
+      logVerbose("findJsExtension found file", { fullPath, ext });
       return ext;
     }
   }
+  logVerbose("findJsExtension no matching file", { fullPathWithoutExtension });
   return null;
 }
 async function promptPackageManager() {
   const projectPath = await getProjectPath();
-  const yarnLock = fs.existsSync(path.join(projectPath, "yarn.lock"));
-  const pnpmLock = fs.existsSync(path.join(projectPath, "pnpm-lock.yaml"));
-  const npmLock = fs.existsSync(path.join(projectPath, "package-lock.json"));
-  const bunLock = fs.existsSync(path.join(projectPath, "bun.lockb")) || fs.existsSync(path.join(projectPath, "bun.lock"));
+  const yarnLock = fs3.existsSync(path3.join(projectPath, "yarn.lock"));
+  const pnpmLock = fs3.existsSync(path3.join(projectPath, "pnpm-lock.yaml"));
+  const npmLock = fs3.existsSync(path3.join(projectPath, "package-lock.json"));
+  const bunLock = fs3.existsSync(path3.join(projectPath, "bun.lockb")) || fs3.existsSync(path3.join(projectPath, "bun.lock"));
+  logVerbose("promptPackageManager inspecting lockfiles", { yarnLock, pnpmLock, npmLock, bunLock });
   if (yarnLock && !pnpmLock && !npmLock && !bunLock) {
+    logVerbose("promptPackageManager auto-selected yarn");
     return "yarn";
   } else if (!yarnLock && pnpmLock && !npmLock && !bunLock) {
+    logVerbose("promptPackageManager auto-selected pnpm");
     return "pnpm";
   } else if (!yarnLock && !pnpmLock && npmLock && !bunLock) {
+    logVerbose("promptPackageManager auto-selected npm");
     return "npm";
   } else if (!yarnLock && !pnpmLock && !npmLock && bunLock) {
+    logVerbose("promptPackageManager auto-selected bun");
     return "bun";
   }
-  if (onQuestionMode === "guess") return "npm";
+  if (onQuestionMode === "guess") {
+    logVerbose("promptPackageManager defaulting to npm due to guess mode");
+    return "npm";
+  }
   if (onQuestionMode === "error") {
     throw new UnansweredQuestionError("Unable to determine the package manager. Re-run with one of: --npm, --yarn, --pnpm, or --bun.");
   }
@@ -904,9 +1532,11 @@ async function promptPackageManager() {
       choices: ["npm", "yarn", "pnpm", "bun"]
     }
   ]);
+  logVerbose("promptPackageManager user selected", { packageManager: answers.packageManager });
   return answers.packageManager;
 }
 async function shellNicelyFormatted(command, { quiet, ...options2 }) {
+  logVerbose("shellNicelyFormatted invoked", { command, options: { ...options2, quiet } });
   let ui;
   let interval;
   if (!quiet) {
@@ -926,22 +1556,25 @@ async function shellNicelyFormatted(command, { quiet, ...options2 }) {
   }
   try {
     if (!isDryRun) {
-      const child = child_process.spawn(command, options2);
+      const child = child_process2.spawn(command, options2);
+      logVerbose("shellNicelyFormatted spawned process", { pid: child.pid, command });
       if (!quiet) {
         child.stdout.pipe(ui.log);
         child.stderr.pipe(ui.log);
       }
-      await new Promise((resolve, reject) => {
+      await new Promise((resolve3, reject) => {
         child.on("exit", (code) => {
           if (code === 0) {
-            resolve();
+            resolve3();
           } else {
+            logVerbose("shellNicelyFormatted command failed", { code });
             reject(new Error(`Command ${command} failed with code ${code}`));
           }
         });
       });
     } else {
       console.log(`[DRY-RUN] Would have run: ${command}`);
+      logVerbose("shellNicelyFormatted skipped due to dry run", { command });
     }
     if (!quiet) {
       commandsExecuted.push(command);
@@ -950,7 +1583,9 @@ async function shellNicelyFormatted(command, { quiet, ...options2 }) {
 `
       );
     }
+    logVerbose("shellNicelyFormatted completed", { command });
   } catch (e) {
+    logVerbose("shellNicelyFormatted encountered error", { command, error: e instanceof Error ? { message: e.message, stack: e.stack } : e });
     if (!quiet) {
       ui.updateBottomBar(
         `${colorize.red`X`} Command ${command} failed
@@ -968,48 +1603,116 @@ async function shellNicelyFormatted(command, { quiet, ...options2 }) {
   }
 }
 async function readFile(fullPath) {
+  logVerbose("readFile invoked", { fullPath, isDryRun });
   try {
     if (!isDryRun) {
-      return fs.readFileSync(fullPath, "utf-8");
+      const content = fs3.readFileSync(fullPath, "utf-8");
+      logVerbose("readFile succeeded", { fullPath, length: content.length });
+      return content;
     }
+    logVerbose("readFile skipped due to dry run", { fullPath });
     return null;
   } catch (err) {
     if (err.code === "ENOENT") {
+      logVerbose("readFile file missing", { fullPath });
       return null;
     }
+    logVerbose("readFile errored", { fullPath, error: err instanceof Error ? { message: err.message, stack: err.stack } : err });
     throw err;
   }
 }
 async function writeFile(fullPath, content) {
-  let create = !fs.existsSync(fullPath);
+  logVerbose("writeFile invoked", { fullPath, length: content.length, isDryRun });
+  let create = !fs3.existsSync(fullPath);
   if (!isDryRun) {
-    fs.mkdirSync(path.dirname(fullPath), { recursive: true });
-    fs.writeFileSync(fullPath, content);
+    fs3.mkdirSync(path3.dirname(fullPath), { recursive: true });
+    fs3.writeFileSync(fullPath, content);
+    logVerbose("writeFile wrote to disk", { fullPath, created: create });
   } else {
     console.log(`[DRY-RUN] Would have written to ${fullPath}`);
+    logVerbose("writeFile skipped due to dry run", { fullPath });
   }
-  const relativeToProjectPath = path.relative(await getProjectPath(), fullPath);
+  const relativeToProjectPath = path3.relative(await getProjectPath(), fullPath);
   if (!create) {
     filesModified.push(relativeToProjectPath);
   } else {
     filesCreated.push(relativeToProjectPath);
   }
+  logVerbose("writeFile recorded change", { relativeToProjectPath, created: create });
 }
 function laterWriteFile(fullPath, content) {
+  logVerbose("laterWriteFile scheduled", { fullPath, length: content.length });
   writeFileHandlers.push(async () => {
     await writeFile(fullPath, content);
   });
 }
 async function writeFileIfNotExists(fullPath, content) {
-  if (!fs.existsSync(fullPath)) {
+  if (!fs3.existsSync(fullPath)) {
+    logVerbose("writeFileIfNotExists writing new file", { fullPath });
     await writeFile(fullPath, content);
+  } else {
+    logVerbose("writeFileIfNotExists skipped", { fullPath });
   }
 }
 function laterWriteFileIfNotExists(fullPath, content) {
+  logVerbose("laterWriteFileIfNotExists scheduled", { fullPath });
   writeFileHandlers.push(async () => {
     await writeFileIfNotExists(fullPath, content);
   });
 }
+async function runDeferredCommands() {
+  if (!deferredCommandHandlers.length) {
+    logVerbose("runDeferredCommands skipped", { reason: "no-handlers" });
+    return;
+  }
+  logVerbose("runDeferredCommands executing handlers", { count: deferredCommandHandlers.length });
+  for (let index = 0; index < deferredCommandHandlers.length; index++) {
+    logVerbose("runDeferredCommands executing handler", { index });
+    const handler = deferredCommandHandlers[index];
+    await handler();
+  }
+  logVerbose("runDeferredCommands completed");
+}
+async function runScheduledCommand(command, args, options2 = {}, metadata = {}) {
+  logVerbose("runScheduledCommand invoked", { command, args, options: options2, isDryRun });
+  const display = [command, ...args].join(" ");
+  if (isDryRun) {
+    console.log(`[DRY-RUN] Would run: ${display}`);
+    logVerbose("runScheduledCommand skipped due to dry run", { display });
+    return;
+  }
+  const result = child_process2.spawnSync(command, args, {
+    stdio: "pipe",
+    ...options2
+  });
+  const recordInCommandsExecuted = metadata.recordInCommandsExecuted;
+  if (recordInCommandsExecuted && !commandsExecuted.includes(display)) {
+    commandsExecuted.push(display);
+  }
+  if (result.status === 0) {
+    console.log(`${colorize.green`√`} ${display}`);
+    logVerbose("runScheduledCommand succeeded", { display });
+  } else {
+    logVerbose("runScheduledCommand failed", { display, result, stderr: result.stderr.toString(), stdout: result.stdout.toString() });
+    throw new Error(`Command ${display} failed with status ${result.status}: ${result.stderr.toString()}`);
+  }
+}
+async function recordFileChange(fullPath, existed) {
+  logVerbose("recordFileChange invoked", { fullPath, existed });
+  const projectRoot = path3.resolve(await getProjectPath());
+  const relative2 = path3.relative(projectRoot, fullPath);
+  const insideProject = relative2 && !relative2.startsWith("..") && !path3.isAbsolute(relative2);
+  const entry = insideProject ? relative2 : fullPath;
+  if (existed) {
+    if (!filesModified.includes(entry)) {
+      filesModified.push(entry);
+    }
+    logVerbose("recordFileChange marked modified", { entry });
+  } else if (!filesCreated.includes(entry)) {
+    filesCreated.push(entry);
+    logVerbose("recordFileChange marked created", { entry });
+  }
+}
 function createConvexAuthConfigContent(options2) {
   const envVarName = getPublicProjectEnvVarName(options2.type);
   return `import { getConvexProvidersConfig } from ${JSON.stringify(options2.stackPackageName)};
@@ -1109,13 +1812,22 @@ function getPublicProjectEnvVarName(type) {
 }
 async function updateConvexClients({ projectPath, type }) {
   const files = collectConvexClientCandidateFiles(projectPath);
+  logVerbose("updateConvexClients collected files", { projectPath, count: files.length });
   const updatedFiles = [];
   const skippedFiles = [];
   for (const filePath of files) {
+    logVerbose("updateConvexClients inspecting file", { filePath });
     const fileContent = await readFile(filePath);
-    if (!fileContent) continue;
-    if (!/new\s+Convex(?:React|Http)?Client\b/.test(fileContent)) continue;
+    if (!fileContent) {
+      logVerbose("updateConvexClients skipped file (no content)", { filePath });
+      continue;
+    }
+    if (!/new\s+Convex(?:React|Http)?Client\b/.test(fileContent)) {
+      logVerbose("updateConvexClients skipped file (no Convex client)", { filePath });
+      continue;
+    }
     const addResult = addSetAuthToConvexClients(fileContent, type);
+    logVerbose("updateConvexClients processed file", { filePath, addResult });
     if (!addResult.changed) {
       if (addResult.instantiationCount > 0 && addResult.skippedHttpCount > 0) {
         skippedFiles.push(filePath);
@@ -1124,28 +1836,34 @@ async function updateConvexClients({ projectPath, type }) {
     }
     let finalContent = addResult.updatedContent;
     if (addResult.usedClientApp) {
+      logVerbose("updateConvexClients ensuring client import", { filePath });
       finalContent = await ensureStackAppImport(finalContent, filePath, "client");
     }
     if (addResult.usedServerApp) {
+      logVerbose("updateConvexClients ensuring server import", { filePath });
       finalContent = await ensureStackAppImport(finalContent, filePath, "server");
     }
     if (finalContent !== fileContent) {
       laterWriteFile(filePath, finalContent);
       updatedFiles.push(filePath);
+      logVerbose("updateConvexClients scheduled update", { filePath });
     }
   }
+  logVerbose("updateConvexClients finished", { updatedFiles, skippedFiles });
   return {
     updatedFiles,
     skippedFiles
   };
 }
 async function ensureStackAppImport(content, filePath, kind) {
+  logVerbose("ensureStackAppImport invoked", { filePath, kind });
   const identifier = kind === "client" ? "stackClientApp" : "stackServerApp";
   if (new RegExp(`import\\s+[^;]*\\b${identifier}\\b`).test(content)) {
+    logVerbose("ensureStackAppImport found existing import", { filePath, identifier });
     return content;
   }
   const stackBasePath = await getStackAppBasePath(kind);
-  const relativeImportPath = convertToModuleSpecifier(path.relative(path.dirname(filePath), stackBasePath));
+  const relativeImportPath = convertToModuleSpecifier(path3.relative(path3.dirname(filePath), stackBasePath));
   const newline = content.includes("\r\n") ? "\r\n" : "\n";
   const lines = content.split(/\r?\n/);
   const importLine = `import { ${identifier} } from "${relativeImportPath}";`;
@@ -1171,6 +1889,7 @@ async function ensureStackAppImport(content, filePath, kind) {
   if (nextLine && nextLine.trim() !== "" && !/^\s*import\b/.test(nextLine)) {
     lines.splice(insertIndex + 1, 0, "");
   }
+  logVerbose("ensureStackAppImport added import", { filePath, importLine });
   return lines.join(newline);
 }
 function convertToModuleSpecifier(relativePath) {
@@ -1182,9 +1901,12 @@ function convertToModuleSpecifier(relativePath) {
 }
 async function getStackAppBasePath(kind) {
   const srcPath = await Steps.guessSrcPath();
-  return path.join(srcPath, "stack", kind);
+  const basePath = path3.join(srcPath, "stack", kind);
+  logVerbose("getStackAppBasePath resolved", { kind, basePath });
+  return basePath;
 }
 function addSetAuthToConvexClients(content, type) {
+  logVerbose("addSetAuthToConvexClients invoked", { type, length: content.length });
   const newline = content.includes("\r\n") ? "\r\n" : "\n";
   const instantiationRegex = /^[ \t]*(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*new\s+(Convex(?:React|Http)?Client)\b([\s\S]*?);/gm;
   const replacements = [];
@@ -1200,11 +1922,13 @@ function addSetAuthToConvexClients(content, type) {
     const className = match[2];
     if (className === "ConvexHttpClient") {
       skippedHttpCount += 1;
+      logVerbose("addSetAuthToConvexClients skipping ConvexHttpClient", { variableName, fileLength: content.length });
       continue;
     }
     const remainder = content.slice(match.index + fullMatch.length);
     const setAuthRegex = new RegExp(`\\b${escapeRegExp(variableName)}\\s*\\.setAuth\\s*\\(`);
     if (setAuthRegex.test(remainder)) {
+      logVerbose("addSetAuthToConvexClients found existing setAuth", { variableName });
       continue;
     }
     const indentation = fullMatch.match(/^[\t ]*/)?.[0] ?? "";
@@ -1220,8 +1944,10 @@ function addSetAuthToConvexClients(content, type) {
       end: match.index + fullMatch.length,
       text: replacementText
     });
+    logVerbose("addSetAuthToConvexClients queued replacement", { variableName, authCall });
   }
   if (replacements.length === 0) {
+    logVerbose("addSetAuthToConvexClients no replacements", { instantiationCount, skippedHttpCount });
     return {
       updatedContent: content,
       changed: false,
@@ -1236,6 +1962,8 @@ function addSetAuthToConvexClients(content, type) {
     const replacement = replacements[i];
     updatedContent = `${updatedContent.slice(0, replacement.start)}${replacement.text}${updatedContent.slice(replacement.end)}`;
   }
+  logVerbose("addSetAuthToConvexClients completed replacements", { replacements: replacements.length });
+  logVerbose("addSetAuthToConvexClients result", { changed: true, instantiationCount, skippedHttpCount, usedClientApp, usedServerApp });
   return {
     updatedContent,
     changed: true,
@@ -1248,41 +1976,57 @@ function addSetAuthToConvexClients(content, type) {
 function determineAuthCallExpression({ type, className, content }) {
   const hasClientAppReference = /\bstackClientApp\b/.test(content);
   const hasServerAppReference = /\bstackServerApp\b/.test(content);
+  logVerbose("determineAuthCallExpression context", { type, className, hasClientAppReference, hasServerAppReference });
   if (type === "js") {
-    return { expression: "stackServerApp.getConvexClientAuth({})", identifier: "stackServerApp" };
+    const result = { expression: "stackServerApp.getConvexClientAuth({})", identifier: "stackServerApp" };
+    logVerbose("determineAuthCallExpression returning for JS", result);
+    return result;
   }
   if (hasClientAppReference) {
-    return { expression: getClientAuthCall(type), identifier: "stackClientApp" };
+    const result = { expression: getClientAuthCall(type), identifier: "stackClientApp" };
+    logVerbose("determineAuthCallExpression using client reference", result);
+    return result;
   }
   if (hasServerAppReference && className !== "ConvexReactClient") {
-    return { expression: "stackServerApp.getConvexClientAuth({})", identifier: "stackServerApp" };
+    const result = { expression: "stackServerApp.getConvexClientAuth({})", identifier: "stackServerApp" };
+    logVerbose("determineAuthCallExpression using server reference", result);
+    return result;
   }
-  return { expression: getClientAuthCall(type), identifier: "stackClientApp" };
+  const fallback = { expression: getClientAuthCall(type), identifier: "stackClientApp" };
+  logVerbose("determineAuthCallExpression fallback", fallback);
+  return fallback;
 }
 function getClientAuthCall(type) {
+  logVerbose("getClientAuthCall invoked", { type });
   return "stackClientApp.getConvexClientAuth({})";
 }
 function collectConvexClientCandidateFiles(projectPath) {
+  logVerbose("collectConvexClientCandidateFiles invoked", { projectPath });
   const roots = getConvexSearchRoots(projectPath);
+  logVerbose("collectConvexClientCandidateFiles roots", { roots });
   const files = /* @__PURE__ */ new Set();
   const visited = /* @__PURE__ */ new Set();
   for (const root of roots) {
     walkDirectory(root, files, visited);
   }
-  return Array.from(files);
+  const result = Array.from(files);
+  logVerbose("collectConvexClientCandidateFiles result", { count: result.length });
+  return result;
 }
 function getConvexSearchRoots(projectPath) {
   const candidateDirs = ["convex", "src", "app", "components"];
-  const existing = candidateDirs.map((dir) => path.join(projectPath, dir)).filter((dirPath) => {
+  const existing = candidateDirs.map((dir) => path3.join(projectPath, dir)).filter((dirPath) => {
     try {
-      return fs.existsSync(dirPath) && fs.statSync(dirPath).isDirectory();
+      return fs3.existsSync(dirPath) && fs3.statSync(dirPath).isDirectory();
     } catch {
       return false;
     }
   });
   if (existing.length > 0) {
+    logVerbose("getConvexSearchRoots using existing directories", { existing });
     return existing;
   }
+  logVerbose("getConvexSearchRoots defaulting to project root", { projectPath });
   return [projectPath];
 }
 var directorySkipList = /* @__PURE__ */ new Set([
@@ -1302,31 +2046,40 @@ var directorySkipList = /* @__PURE__ */ new Set([
 function walkDirectory(currentDir, files, visited) {
   const realPath = (() => {
     try {
-      return fs.realpathSync(currentDir);
+      return fs3.realpathSync(currentDir);
     } catch {
       return currentDir;
     }
   })();
   if (visited.has(realPath)) return;
   visited.add(realPath);
+  logVerbose("walkDirectory scanning", { currentDir: realPath });
   let dirEntries;
   try {
-    dirEntries = fs.readdirSync(realPath, { withFileTypes: true });
+    dirEntries = fs3.readdirSync(realPath, { withFileTypes: true });
   } catch {
     return;
   }
   for (const entry of dirEntries) {
     const entryName = entry.name;
     if (entry.isDirectory()) {
-      if (directorySkipList.has(entryName)) continue;
-      if (entryName.startsWith(".") || entryName.startsWith("_")) continue;
-      walkDirectory(path.join(realPath, entryName), files, visited);
+      if (directorySkipList.has(entryName)) {
+        logVerbose("walkDirectory skipping directory in skip list", { directory: entryName, parent: realPath });
+        continue;
+      }
+      if (entryName.startsWith(".") || entryName.startsWith("_")) {
+        logVerbose("walkDirectory skipping hidden directory", { directory: entryName, parent: realPath });
+        continue;
+      }
+      walkDirectory(path3.join(realPath, entryName), files, visited);
       continue;
     }
     if (!entry.isFile()) continue;
     if (entryName.endsWith(".d.ts")) continue;
     if (!hasJsLikeExtension(entryName)) continue;
-    files.add(path.join(realPath, entryName));
+    const filePath = path3.join(realPath, entryName);
+    files.add(filePath);
+    logVerbose("walkDirectory added file", { filePath });
   }
 }
 function hasJsLikeExtension(fileName) {
@@ -1338,13 +2091,9 @@ function escapeRegExp(str) {
 function throwErr(message) {
   throw new Error(message);
 }
-function templateIdentity(strings, ...values) {
-  if (strings.length === 0) return "";
-  if (values.length !== strings.length - 1) throw new Error("Invalid number of values; must be one less than strings");
-  return strings.slice(1).reduce((result, string, i) => `${result}${values[i] ?? "n/a"}${string}`, strings[0]);
-}
 async function clearStdin() {
-  await new Promise((resolve) => {
+  logVerbose("clearStdin invoked");
+  await new Promise((resolve3) => {
     if (process.stdin.isTTY) {
       process.stdin.setRawMode(true);
     }
@@ -1356,10 +2105,12 @@ async function clearStdin() {
       if (process.stdin.isTTY) {
         process.stdin.setRawMode(false);
       }
-      resolve();
+      logVerbose("clearStdin flushed");
+      resolve3();
     };
     setTimeout(flush, 10);
   });
+  logVerbose("clearStdin completed");
 }
 export {
   templateIdentity