@whisperr/wizard 0.1.6 → 0.1.8

package/dist/index.js

@@ -200,6 +200,19 @@ async function detect3(ctx) {
   let confidence = 0.4;
   if (dependsOn(pkgJson, ["next"])) return null;
   if (dependsOn(pkgJson, ["react-native", "expo"])) return null;
+  const hasUi = dependsOn(pkgJson, ["react", "vue", "svelte", "@angular/core"]) || await ctx.exists("index.html");
+  const isBackend = dependsOn(pkgJson, [
+    "express",
+    "fastify",
+    "koa",
+    "@nestjs/core",
+    "hapi",
+    "@hapi/hapi",
+    "restify",
+    "h3",
+    "@adonisjs/core"
+  ]);
+  if (isBackend && !hasUi) return null;
   if (dependsOn(pkgJson, ["react", "vue", "svelte", "@angular/core"])) {
     evidence.push("frontend framework dependency");
     confidence += 0.4;
@@ -255,14 +268,372 @@ var webPlaybook = {
   verifyCommand: void 0
 };
 
-// src/core/playbooks/react-native.ts
+// src/core/playbooks/node.ts
 var target4 = {
+  id: "node",
+  displayName: "Node.js (backend)",
+  language: "typescript",
+  availability: "available"
+};
+function dependsOn2(pkgJson, names) {
+  try {
+    const pkg = JSON.parse(pkgJson);
+    const all = {
+      ...pkg.dependencies ?? {},
+      ...pkg.devDependencies ?? {}
+    };
+    return names.some((n) => n in all);
+  } catch {
+    return false;
+  }
+}
+var BACKEND_FRAMEWORKS = [
+  "express",
+  "fastify",
+  "koa",
+  "@nestjs/core",
+  "hapi",
+  "@hapi/hapi",
+  "restify",
+  "hono",
+  "h3",
+  "@adonisjs/core"
+];
+var FRONTEND_FRAMEWORKS = [
+  "react",
+  "vue",
+  "svelte",
+  "@angular/core",
+  "next",
+  "react-native",
+  "expo"
+];
+var SERVER_ENTRYPOINTS = [
+  "server.js",
+  "server.ts",
+  "src/server.ts",
+  "src/server.js",
+  "app.js",
+  "src/app.ts",
+  "src/index.ts",
+  "index.js"
+];
+async function detect4(ctx) {
+  if (!await ctx.exists("package.json")) return null;
+  const pkgJson = await ctx.read("package.json");
+  const evidence = ["package.json"];
+  let confidence = 0;
+  if (dependsOn2(pkgJson, BACKEND_FRAMEWORKS)) {
+    evidence.push("backend framework dependency");
+    confidence += 0.7;
+  }
+  const hasFrontend = dependsOn2(pkgJson, FRONTEND_FRAMEWORKS);
+  const hasIndexHtml = await ctx.exists("index.html");
+  if ((hasFrontend || hasIndexHtml) && confidence === 0) return null;
+  for (const f of SERVER_ENTRYPOINTS) {
+    if (await ctx.exists(f)) {
+      evidence.push(f);
+      confidence += 0.15;
+      break;
+    }
+  }
+  if (confidence === 0 && !hasFrontend && !hasIndexHtml) {
+    try {
+      const pkg = JSON.parse(pkgJson);
+      const start = String(pkg.scripts?.start ?? "");
+      if (/\b(node|nodemon|ts-node|tsx)\b/.test(start)) {
+        evidence.push("node start script");
+        confidence += 0.5;
+      }
+    } catch {
+    }
+  }
+  if (confidence === 0) return null;
+  return { target: target4, confidence: Math.min(confidence, 0.95), evidence };
+}
+var systemPrompt4 = `
+## SDK: Whisperr for Node (server-side) \u2014 package \`@whisperr/node\` (+ \`@whisperr/node/express\` for Express)
+
+This is a BACKEND surface. Instrument events at the real SERVER-SIDE moment they
+happen \u2014 inside request handlers, webhook handlers, billing logic, queue/cron
+jobs, and service methods. The events in your plan are the ones that originate on
+the server (payments, subscription/lifecycle changes, server-computed
+thresholds); they will NOT be in any UI. Do not look for click/screen handlers.
+
+The ONE thing that's different from the browser SDK: \`track()\` and
+\`identify()\` take the end-user id as the FIRST argument \u2014 the server has no
+persisted session to infer it from. Source the real user id at each call site.
+
+1) Install (detect pnpm/yarn/npm from the lockfile):
+     <pm> add @whisperr/node
+
+2) Create one shared client module, e.g. src/whisperr.ts (or .js):
+     import { createWhisperr } from '@whisperr/node';
+     export const whisperr = createWhisperr({
+       apiKey: process.env.WHISPERR_API_KEY!,
+       baseUrl: '<INGESTION_BASE_URL from manifest>', // omit if it's the default
+     });
+   Put WHISPERR_API_KEY in the app's server config and add it to .env /
+   .env.example. This is a SERVER env var \u2014 never a public/VITE_/NEXT_PUBLIC_ one.
+
+3) identify(externalUserId, { ... }). Call where you already know the user \u2014
+   after signup, or when user-level traits/contact channels change:
+     whisperr.identify(user.id, { traits: { plan: user.plan }, email: user.email });
+   Use the same stable id you use everywhere else for that user, so server and
+   client events land on one timeline.
+
+4) track(externalUserId, eventType, properties). For each plan event, find the
+   real server-side moment and source the user id from what's in scope:
+     - In a request handler:   whisperr.track(req.user.id, 'plan_upgraded', { plan });
+     - In a webhook/cron/job:  there's no request \u2014 get the id from the domain
+       object (e.g. subscription.userId, or map the Stripe customer to your user):
+         whisperr.track(subscription.userId, 'subscription_cancelled', { reason });
+   Copy event_type verbatim (snake_case) from the plan. If you genuinely can't
+   source a user id at the only sensible site, leave a one-line
+   \`// TODO(whisperr): need user id to track <event>\` and move on.
+
+5) Express only \u2014 if this app uses Express, mount the adapter AFTER auth so the
+   user is resolvable, then use the per-request helper at call sites:
+     import { whisperrExpress } from '@whisperr/node/express';
+     app.use(whisperrExpress(whisperr)); // pass { resolveUser } if your auth isn't req.user.id
+     // ...later, in a route:
+     req.whisperr.track('payment_failed', { amount_cents });
+
+6) Lifecycle. Flush on graceful shutdown so queued events aren't lost:
+     process.on('SIGTERM', () => { whisperr.shutdown(); });
+   In serverless handlers (Lambda/Vercel/Cloud Functions), \`await whisperr.flush()\`
+   before returning, since the runtime freezes after the response.
+
+Notes / gotchas:
+- The client queues + batches + retries automatically. Fire-and-forget is fine;
+  do NOT await track()/identify() \u2014 only await flush()/shutdown().
+- track()/identify() no-op silently if the user id is empty \u2014 make sure you pass
+  a real id.
+- One client instance per process (the exported singleton). Don't create a new
+  client per request.
+`.trim();
+var nodePlaybook = {
+  target: target4,
+  detect: detect4,
+  packageRef: "@whisperr/node (npm)",
+  systemPrompt: systemPrompt4,
+  verifyCommand: void 0
+};
+
+// src/core/playbooks/python.ts
+var target5 = {
+  id: "python",
+  displayName: "Python (backend)",
+  language: "python",
+  availability: "available"
+};
+var PROJECT_FILES = [
+  "pyproject.toml",
+  "requirements.txt",
+  "setup.py",
+  "setup.cfg",
+  "Pipfile"
+];
+var WEB_FRAMEWORKS = [
+  "django",
+  "flask",
+  "fastapi",
+  "starlette",
+  "sanic",
+  "aiohttp",
+  "tornado",
+  "bottle",
+  "falcon",
+  "litestar"
+];
+async function detect5(ctx) {
+  const present = [];
+  for (const f of PROJECT_FILES) {
+    if (await ctx.exists(f)) present.push(f);
+  }
+  const hasManage = await ctx.exists("manage.py");
+  if (present.length === 0 && !hasManage) return null;
+  const evidence = [...present];
+  let confidence = present.length ? 0.5 : 0.3;
+  let deps = "";
+  for (const f of present) deps += (await ctx.read(f)).toLowerCase() + "\n";
+  if (WEB_FRAMEWORKS.some((fw) => deps.includes(fw))) {
+    evidence.push("python web framework");
+    confidence += 0.35;
+  }
+  if (hasManage) {
+    evidence.push("manage.py");
+    confidence += 0.2;
+  }
+  return { target: target5, confidence: Math.min(confidence, 0.95), evidence };
+}
+var systemPrompt5 = `
+## SDK: Whisperr for Python (server-side) \u2014 package \`whisperr\` (Django middleware in \`whisperr.django\`)
+
+This is a BACKEND surface. Instrument events at the real SERVER-SIDE moment they
+happen \u2014 inside views/request handlers, webhook handlers, billing logic, Celery
+tasks, and management commands. The events in your plan originate on the server
+(payments, subscription/lifecycle changes, server-computed thresholds); they will
+NOT be in any UI. Do not look for click/screen handlers.
+
+The ONE thing that's different from a browser SDK: \`track()\` and \`identify()\`
+take the end-user id as the FIRST argument \u2014 the server has no persisted session
+to infer it from. Source the real user id at each call site.
+
+1) Install (detect the project's tool \u2014 pip/poetry/pipenv/uv from the lockfile or
+   pyproject): add \`whisperr\` (use \`whisperr[django]\` on a Django project).
+
+2) Create one shared client, e.g. app/whisperr_client.py:
+     import os
+     from whisperr import Whisperr
+     whisperr = Whisperr(
+         api_key=os.environ["WHISPERR_API_KEY"],
+         base_url="<INGESTION_BASE_URL from manifest>",  # omit if it's the default
+     )
+   Put WHISPERR_API_KEY in the app's server config / .env (server-side secret).
+
+3) identify(external_user_id, ...). Where you already know the user (signup, or
+   when user-level traits/contact channels change):
+     whisperr.identify(user.id, traits={"plan": user.plan}, email=user.email)
+
+4) track(external_user_id, event_type, properties). Find the real server-side
+   moment and source the user id from what's in scope:
+     - In a handler/view:   whisperr.track(request.user.id, "plan_upgraded", {"plan": plan})
+     - In a webhook/task:   there's no request \u2014 get the id from the domain object
+       (e.g. subscription.user_id, or map the Stripe customer to your user):
+         whisperr.track(subscription.user_id, "subscription_cancelled", {"reason": reason})
+   Copy event_type verbatim (snake_case) from the plan. If you genuinely can't
+   source a user id at the only sensible site, leave a one-line
+   \`# TODO(whisperr): need user id to track <event>\` and move on.
+
+5) Django only \u2014 register the middleware AFTER the auth middleware in settings.py,
+   then use the per-request helper in views:
+     # settings.py
+     WHISPERR_API_KEY = os.environ["WHISPERR_API_KEY"]
+     MIDDLEWARE = [ ..., "django.contrib.auth.middleware.AuthenticationMiddleware",
+                    "whisperr.django.WhisperrMiddleware" ]
+     # views.py
+     request.whisperr.track("payment_failed", {"amount_cents": amount})
+   For Celery/webhook/management-command code (no request), use the shared client
+   or whisperr.django.get_client() with the user id from your data.
+
+6) Lifecycle. The client flushes in the background and on interpreter exit
+   (atexit). In short-lived processes (management commands, scripts, serverless),
+   call \`whisperr.flush()\` before returning so queued events aren't lost.
+
+Notes / gotchas:
+- The client queues + batches + retries automatically on a daemon thread. Fire-
+  and-forget is fine; do NOT block on track()/identify() \u2014 only flush()/shutdown().
+- track()/identify() no-op silently if the user id is empty \u2014 pass a real id.
+- One client instance per process. Don't construct a new client per request.
+`.trim();
+var pythonPlaybook = {
+  target: target5,
+  detect: detect5,
+  packageRef: "whisperr (PyPI)",
+  systemPrompt: systemPrompt5,
+  verifyCommand: void 0
+};
+
+// src/core/playbooks/php.ts
+var target6 = {
+  id: "php",
+  displayName: "PHP (backend)",
+  language: "php",
+  availability: "available"
+};
+var FRAMEWORKS = [
+  "laravel/framework",
+  "symfony/",
+  "slim/slim",
+  "laminas/",
+  "cakephp/",
+  "yiisoft/",
+  "codeigniter4/"
+];
+async function detect6(ctx) {
+  if (!await ctx.exists("composer.json")) return null;
+  const composer = (await ctx.read("composer.json")).toLowerCase();
+  const evidence = ["composer.json"];
+  let confidence = 0.5;
+  if (FRAMEWORKS.some((f) => composer.includes(f))) {
+    evidence.push("php framework");
+    confidence += 0.35;
+  }
+  if (await ctx.exists("artisan")) {
+    evidence.push("artisan (Laravel)");
+    confidence += 0.15;
+  }
+  return { target: target6, confidence: Math.min(confidence, 0.95), evidence };
+}
+var systemPrompt6 = `
+## SDK: Whisperr for PHP (server-side) \u2014 package \`whisperr/php\` (Laravel facade + service provider included)
+
+This is a BACKEND surface. Instrument events at the real SERVER-SIDE moment they
+happen \u2014 inside controllers/request handlers, webhook handlers, billing logic,
+queued jobs, and console commands. The events in your plan originate on the
+server (payments, subscription/lifecycle changes, server-computed thresholds);
+they will NOT be in any UI. Do not look for click handlers / Blade views.
+
+The ONE thing that's different from a browser SDK: \`track()\` and \`identify()\`
+take the end-user id as the FIRST argument \u2014 the server has no session to infer
+it from. Source the real user id at each call site.
+
+1) Install:
+     composer require whisperr/php
+
+2) Config. Set the key in the environment (.env), never hardcoded:
+     WHISPERR_API_KEY=<INGESTION_API_KEY from manifest>
+   On Laravel the service provider + \`Whisperr\` facade auto-register (package
+   discovery). Optionally publish config: \`php artisan vendor:publish --tag=whisperr-config\`.
+   On non-Laravel PHP, construct one client and reuse it:
+     use Whisperr\\Whisperr;
+     $whisperr = new Whisperr(['api_key' => getenv('WHISPERR_API_KEY')]);
+
+3) identify(externalUserId, [...]). Where you already know the user (after login/
+   signup, or when user-level traits/contact channels change):
+     use Whisperr\\Laravel\\Facades\\Whisperr;
+     Whisperr::identify(auth()->id(), ['traits' => ['plan' => $user->plan], 'email' => $user->email]);
+
+4) track(externalUserId, eventType, properties). Find the real server-side moment
+   and source the user id from what's in scope:
+     - In a controller:   Whisperr::track(auth()->id(), 'plan_upgraded', ['plan' => $plan]);
+     - In a webhook/job:  no auth() \u2014 get the id from the domain object
+       (e.g. $subscription->user_id, or map the Stripe customer to your user):
+         Whisperr::track($subscription->user_id, 'subscription_cancelled', ['reason' => $reason]);
+   Copy event_type verbatim (snake_case) from the plan. If you genuinely can't
+   source a user id at the only sensible site, leave a one-line
+   \`// TODO(whisperr): need user id to track <event>\` and move on.
+   On plain PHP use \`$whisperr->track(...)\` on your shared instance instead of the facade.
+
+5) Lifecycle. On Laravel the buffered events flush automatically AFTER the
+   response is sent (the service provider hooks \`terminating\`), so tracking adds
+   no response latency. The client also flushes on shutdown. In short-lived
+   scripts/commands call \`Whisperr::flush()\` (or \`$whisperr->flush()\`) before exit.
+
+Notes / gotchas:
+- Events buffer in memory during the request and send in a batch on flush. Fire-
+  and-forget is fine; don't block on track()/identify().
+- track()/identify() no-op silently if the user id is empty \u2014 pass a real id
+  (guard webhook code where auth() is null).
+- Use the same stable user id everywhere so server + client events line up.
+`.trim();
+var phpPlaybook = {
+  target: target6,
+  detect: detect6,
+  packageRef: "whisperr/php (Packagist)",
+  systemPrompt: systemPrompt6,
+  verifyCommand: void 0
+};
+
+// src/core/playbooks/react-native.ts
+var target7 = {
   id: "react-native",
   displayName: "React Native",
   language: "typescript",
   availability: "planned"
 };
-async function detect4(ctx) {
+async function detect7(ctx) {
   if (!await ctx.exists("package.json")) return null;
   const pkgJson = await ctx.read("package.json");
   let match = false;
@@ -280,9 +651,9 @@ async function detect4(ctx) {
     evidence.push("app.json");
     confidence += 0.1;
   }
-  return { target: target4, confidence: Math.min(confidence, 1), evidence };
+  return { target: target7, confidence: Math.min(confidence, 1), evidence };
 }
-var systemPrompt4 = `
+var systemPrompt7 = `
 ## SDK: Whisperr for React Native \u2014 package \`@whisperr/react-native\`
 
 1) Install \`@whisperr/react-native\` with the repo's package manager. If it has
@@ -305,20 +676,20 @@ Notes:
   if one exists; otherwise a constants file is acceptable.
 `.trim();
 var reactNativePlaybook = {
-  target: target4,
-  detect: detect4,
+  target: target7,
+  detect: detect7,
   packageRef: "@whisperr/react-native (npm)",
-  systemPrompt: systemPrompt4
+  systemPrompt: systemPrompt7
 };
 
 // src/core/playbooks/swift.ts
-var target5 = {
+var target8 = {
   id: "swift",
   displayName: "Swift (iOS)",
   language: "swift",
   availability: "planned"
 };
-async function detect5(ctx) {
+async function detect8(ctx) {
   const evidence = [];
   let confidence = 0;
   if (await ctx.exists("Package.swift")) {
@@ -339,9 +710,9 @@ async function detect5(ctx) {
     confidence += 0.2;
   }
   if (confidence === 0) return null;
-  return { target: target5, confidence: Math.min(confidence, 1), evidence };
+  return { target: target8, confidence: Math.min(confidence, 1), evidence };
 }
-var systemPrompt5 = `
+var systemPrompt8 = `
 ## SDK: Whisperr for Swift (iOS) \u2014 Swift Package \`Whisperr\`
 
 1) Add the Swift Package dependency (github.com/WhisperrAI/whisperr-swift). If the
@@ -369,10 +740,10 @@ Notes:
 - Do not attempt to run xcodebuild; verification is the human's step here.
 `.trim();
 var swiftPlaybook = {
-  target: target5,
-  detect: detect5,
+  target: target8,
+  detect: detect8,
   packageRef: "Whisperr (Swift Package)",
-  systemPrompt: systemPrompt5
+  systemPrompt: systemPrompt8
 };
 
 // src/core/playbooks/index.ts
@@ -381,6 +752,9 @@ var ALL_PLAYBOOKS = [
   nextjsPlaybook,
   reactNativePlaybook,
   webPlaybook,
+  nodePlaybook,
+  pythonPlaybook,
+  phpPlaybook,
   swiftPlaybook
 ];
 function playbookByTargetId(id) {
@@ -614,7 +988,7 @@ in the code. You will NOT find everything \u2014 some events live server-side or
 aren't in this codebase at all. That is expected and fine. Get what is here, get
 it right, report the rest. Know exactly what you're doing; never hunt blindly.
 
-You are billed per step and the user is watching. Work FAST and DECISIVELY.
+Every step costs time and the user is watching. Work FAST and DECISIVELY.
 
 EFFICIENCY \u2014 non-negotiable:
 - Use Grep and Glob to find code. Do NOT read whole files; read the smallest
@@ -645,8 +1019,16 @@ CORRECTNESS:
 - Use the EXACT snake_case event names given. Never invent or rename events.
 - Only place an event where you're confident the user action truly happens.
 
-End every task with a short summary: what you changed, which events you wired
-(and the properties you attached), and the follow-ups you intentionally left.
+FINAL SUMMARY (this is shown verbatim to a non-technical customer in a
+dashboard \u2014 write for a human, not a changelog):
+- Plain prose and simple short lines ONLY. Do NOT use Markdown: no #/##
+  headings, no **bold**, no backticks, no code fences, no tables, no "---".
+- Keep it tight: 3\u20136 short sentences or dash-prefixed lines. Lead with what now
+  works ("Installed the SDK and wired identify() on login."). Then one line per
+  group of events wired (you don't need to list all 28 individually \u2014 group
+  them, e.g. "Wired the 6 subscription + signup events in your auth and billing
+  controllers."). End with what you deliberately left as follow-ups and why.
+- Mention concrete file names in prose if helpful, but no diffs, no snippets.
 `.trim();
 function renderIdentifyBrief(m) {
   const lines = [];
@@ -681,7 +1063,7 @@ function renderEventsBrief(m) {
     lines.push("");
   }
   lines.push(
-    `${events.length} candidate events (highest-impact first). For each: fire track('<event_type>', { ...properties }) at the real moment it happens, and attach every listed property you can source from values in scope there. Skip an event entirely if it has no clear client-side trigger.`
+    `${events.length} candidate events (highest-impact first). For each: fire track('<event_type>', { ...properties }) at the real moment it happens, and attach every listed property you can source from values in scope there. Skip an event entirely if it has no clear trigger in this codebase.`
   );
   if (events.some((e) => e.coverage?.length)) {
     lines.push("");
@@ -721,7 +1103,7 @@ function coverageNote(coverage) {
 async function runIntegrationAgent(opts) {
   const { repoPath, config, session, playbook, manifest, progress } = opts;
   applyModelAuthEnv(config, session);
-  const systemPrompt6 = [BASE_WIZARD_PROMPT, playbook.systemPrompt].join("\n\n");
+  const systemPrompt9 = [BASE_WIZARD_PROMPT, playbook.systemPrompt].join("\n\n");
   const started = Date.now();
   let costUsd = 0;
   const summaries = [];
@@ -750,7 +1132,7 @@ async function runIntegrationAgent(opts) {
   ].join("\n");
   const core = await runPass({
     prompt: corePrompt,
-    systemPrompt: systemPrompt6,
+    systemPrompt: systemPrompt9,
     repoPath,
     model: config.model,
     maxTurns: 35,
@@ -779,7 +1161,7 @@ ${core.summary}`);
     ].join("\n");
     const events = await runPass({
       prompt: eventsPrompt,
-      systemPrompt: systemPrompt6,
+      systemPrompt: systemPrompt9,
       repoPath,
       model: config.model,
       maxTurns: config.maxTurns,
@@ -799,7 +1181,7 @@ ${events.summary}`);
   };
 }
 async function runPass(opts) {
-  const { prompt, systemPrompt: systemPrompt6, repoPath, model, maxTurns, progress } = opts;
+  const { prompt, systemPrompt: systemPrompt9, repoPath, model, maxTurns, progress } = opts;
   let summary = "";
   let costUsd = 0;
   let ok = false;
@@ -809,7 +1191,7 @@ async function runPass(opts) {
     options: {
       model,
       cwd: repoPath,
-      systemPrompt: systemPrompt6,
+      systemPrompt: systemPrompt9,
       allowedTools: ["Read", "Edit", "Write", "Bash", "Glob", "Grep"],
       permissionMode: "bypassPermissions",
       maxTurns,
@@ -920,6 +1302,21 @@ function revertHint(checkpoint) {
   if (!checkpoint.isRepo || !checkpoint.baseRef) return void 0;
   return `git restore . && git clean -fd   (back to ${checkpoint.baseRef.slice(0, 7)})`;
 }
+async function isWorkingTreeClean(repoPath) {
+  const status = await run(repoPath, ["status", "--porcelain"]);
+  return status.ok && status.stdout.trim() === "";
+}
+async function revertToCheckpoint(repoPath, checkpoint) {
+  if (!checkpoint.isRepo) return false;
+  if (checkpoint.baseRef) {
+    const reset = await run(repoPath, ["reset", "--hard", checkpoint.baseRef]);
+    const clean2 = await run(repoPath, ["clean", "-fd"]);
+    return reset.ok && clean2.ok;
+  }
+  const restore = await run(repoPath, ["restore", "."]);
+  const clean = await run(repoPath, ["clean", "-fd"]);
+  return restore.ok && clean.ok;
+}
 async function repoFingerprint(repoPath) {
   const remote = await run(repoPath, ["remote", "get-url", "origin"]);
   const seed = remote.ok && remote.stdout.trim() ? normalizeRemote(remote.stdout.trim()) : `dir:${basename(repoPath)}`;
@@ -932,7 +1329,9 @@ async function scanWiredEvents(repoPath, files, eventTypes) {
   const wired = /* @__PURE__ */ new Map();
   const patterns = eventTypes.map((e) => ({
     eventType: e,
-    re: new RegExp(`track\\s*\\(\\s*['"\`]${escapeRegExp(e)}['"\`]`)
+    re: new RegExp(
+      `\\btrack\\s*\\(\\s*[\\s\\S]{0,160}?['"\`]${escapeRegExp(e)}['"\`]`
+    )
   }));
   for (const file of files) {
     let content = "";
@@ -1079,8 +1478,24 @@ Flutter is live today; ${theme.bright(
   );
   const checkpoint = await takeCheckpoint(repoPath);
   if (!checkpoint.isRepo) {
+    if (!options.force) {
+      p.cancel(
+        theme.alert("Not a git repository.") + " The wizard edits your code and relies on git to undo safely.\n" + theme.muted("Run `git init` and commit first, or re-run with --force to proceed without a safety net.")
+      );
+      return 1;
+    }
     p.log.warn(
-      theme.warn("not a git repo") + theme.muted(" \u2014 edits will apply with no automatic undo.")
+      theme.warn("not a git repo") + theme.muted(" \u2014 proceeding with --force; there is no automatic undo.")
+    );
+  } else if (!await isWorkingTreeClean(repoPath)) {
+    if (!options.force) {
+      p.cancel(
+        theme.alert("Your working tree has uncommitted changes.") + " Commit or stash them first so the wizard's edits stay isolated and reversible.\n" + theme.muted("Or re-run with --force to proceed anyway.")
+      );
+      return 1;
+    }
+    p.log.warn(
+      theme.warn("uncommitted changes present") + theme.muted(" \u2014 proceeding with --force; a revert would also drop your own changes.")
     );
   }
   const spin = p.spinner();
@@ -1116,6 +1531,7 @@ Flutter is live today; ${theme.bright(
   clearInterval(tick);
   if (!outcome) {
     spin.stop(theme.alert("Integration stopped"));
+    await maybeRevert(repoPath, checkpoint, "The run stopped before finishing.");
     return 1;
   }
   const stopLabel = !outcome.coreOk ? theme.warn("Stopped early \u2014 partial setup is in your working tree") : outcome.eventsComplete ? theme.success("Integration complete") : theme.success("Core integration done") + theme.muted(" \u2014 some events left as follow-ups");
@@ -1127,6 +1543,17 @@ Flutter is live today; ${theme.bright(
   if (outcome.summary.trim()) {
     p.log.message(outcome.summary.trim());
   }
+  if (!outcome.coreOk) {
+    const reverted = await maybeRevert(
+      repoPath,
+      checkpoint,
+      "The core setup didn't complete, so these changes may be incomplete."
+    );
+    if (reverted) {
+      p.outro(theme.muted("Reverted \u2014 nothing was left in your working tree."));
+      return 1;
+    }
+  }
   const wiredMap = await scanWiredEvents(
     repoPath,
     files,
@@ -1148,7 +1575,7 @@ Flutter is live today; ${theme.bright(
   });
   p.log.info(
     theme.muted(
-      `${wiredMap.size}/${manifest.events.length} events wired \xB7 ${files.length} file${files.length === 1 ? "" : "s"} changed \xB7 ~$${outcome.costUsd.toFixed(2)} \xB7 ${Math.round(outcome.durationMs / 1e3)}s`
+      `${wiredMap.size}/${manifest.events.length} events wired \xB7 ${files.length} file${files.length === 1 ? "" : "s"} changed \xB7 ${Math.round(outcome.durationMs / 1e3)}s`
     )
   );
   if (!config.offline) {
@@ -1183,6 +1610,29 @@ Flutter is live today; ${theme.bright(
   p.outro(theme.signal("\u2301 ") + theme.bright("Whisperr is wired in."));
   return 0;
 }
+async function maybeRevert(repoPath, checkpoint, reason) {
+  if (!checkpoint.isRepo) return false;
+  const files = await changedFiles(repoPath, checkpoint);
+  if (files.length === 0) return false;
+  const doRevert = await p.confirm({
+    message: `${reason} Revert all of the wizard's changes now?`,
+    initialValue: true
+  });
+  if (p.isCancel(doRevert) || !doRevert) {
+    const hint = revertHint(checkpoint);
+    if (hint) p.log.info(theme.muted(`Left in your working tree. Undo anytime: ${hint}`));
+    return false;
+  }
+  const ok = await revertToCheckpoint(repoPath, checkpoint);
+  if (ok) {
+    p.log.success(theme.success("Reverted to your pre-wizard state."));
+  } else {
+    p.log.warn(
+      theme.warn("Couldn't revert automatically \u2014 undo manually: ") + (revertHint(checkpoint) ?? "git reset --hard")
+    );
+  }
+  return ok;
+}
 async function chooseTarget(detections) {
   const top = detections[0];
   if (top && (detections.length === 1 || top.confidence >= 0.9)) {
@@ -1274,6 +1724,9 @@ function parseArgs(argv) {
       case "--offline":
         opts.offline = true;
         break;
+      case "--force":
+        opts.force = true;
+        break;
       case "--api":
         opts.apiBaseUrl = args[++i];
         break;
@@ -1299,6 +1752,7 @@ function printHelp() {
       "",
       `  ${theme.bright("Options")}`,
       "    --offline         Use a demo manifest, no account/browser needed",
+      "    --force           Proceed without a clean git tree (no safe undo)",
       "    --api <url>       Override the Whisperr API base URL",
       "    --model <id>      Override the coding-agent model",
       "    -h, --help        Show this help",
@@ -1317,7 +1771,7 @@ async function main() {
     return;
   }
   if ("version" in parsed) {
-    console.log("0.1.6");
+    console.log("0.1.8");
     return;
   }
   try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@whisperr/wizard",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "Whisperr Wizard — one command to integrate the Whisperr SDK into your app. Authenticates with your onboarded account and uses an AI coding agent to wire up identify() and your business events automatically.",
   "license": "UNLICENSED",
   "private": false,