npm - @whisperr/wizard - Versions diffs - 0.1.5 → 0.1.7 - Mend

@whisperr/wizard 0.1.5 → 0.1.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (2) hide show

package/dist/index.js +513 -67
package/package.json +1 -1

package/dist/index.js CHANGED Viewed

@@ -113,7 +113,7 @@ var target2 = {
   id: "nextjs",
   displayName: "Next.js",
   language: "typescript",
-  availability: "planned"
+  availability: "available"
 };
 async function detect2(ctx) {
   if (!await ctx.exists("package.json")) return null;
@@ -140,34 +140,37 @@ async function detect2(ctx) {
   return { target: target2, confidence: Math.min(confidence, 1), evidence };
 }
 var systemPrompt2 = `
-## SDK: Whisperr for Web in Next.js \u2014 package \`@whisperr/web\`
-Same SDK as plain web, with Next-specific wiring.
+## SDK: Whisperr for Next.js \u2014 package \`@whisperr/next\` (+ \`@whisperr/web\`)
-1) Install \`@whisperr/web\`. Put the key in NEXT_PUBLIC_WHISPERR_KEY in
-   .env.local (and add it to .env.example).
+1) Install: \`<pm> add @whisperr/next @whisperr/web\`. Put the key in
+   NEXT_PUBLIC_WHISPERR_KEY in .env.local (and add it to .env.example).
-2) Whisperr runs client-side. Create a client provider:
-   - App Router: a 'use client' component (e.g. app/whisperr-provider.tsx) that
-     calls Whisperr.init(...) in a useEffect and renders children; mount it in
-     app/layout.tsx.
-   - Pages Router: init in pages/_app.tsx inside a useEffect.
+2) Mount the provider in app/layout.tsx. It is already a 'use client' boundary,
+   so it drops straight into the server-component layout \u2014 no wrapper file needed:
+     import { WhisperrProvider } from '@whisperr/next';
+     // inside <body>:
+     <WhisperrProvider apiKey={process.env.NEXT_PUBLIC_WHISPERR_KEY!}>{children}</WhisperrProvider>
+   Pages Router: wrap the tree in pages/_app.tsx with <WhisperrProvider apiKey=...>.
-3) identify() after auth resolves on the client (e.g. in your auth/session
-   hook). reset() on sign-out.
+3) identify() after auth resolves on the client (in your session hook/effect);
+   reset() on sign-out. Use the useWhisperr() hook inside 'use client' components.
-4) track() in client components / event handlers / mutation callbacks. Do NOT
-   call track from server components, route handlers, or getServerSideProps \u2014
-   this SDK is a browser client. Copy event_type verbatim from the manifest.
+4) track() in client components / event handlers / mutation callbacks:
+     'use client';
+     import { useWhisperr } from '@whisperr/next';
+     const whisperr = useWhisperr();
+     whisperr.track('event_type_from_manifest', { ... });
+   Do NOT call track from server components, route handlers, or getServerSideProps \u2014
+   it is a browser client. Copy event_type verbatim (snake_case) from the manifest.
 Notes:
-- Guard against double-init under React Strict Mode (init is idempotent, but
-  wire it so it only runs once).
+- Pageviews are auto-captured via the History API (covers Next client navigation).
+- Provider init is idempotent (safe under React Strict Mode).
 `.trim();
 var nextjsPlaybook = {
   target: target2,
   detect: detect2,
-  packageRef: "@whisperr/web (npm)",
+  packageRef: "@whisperr/next (npm)",
   systemPrompt: systemPrompt2
 };
@@ -176,8 +179,7 @@ var target3 = {
   id: "web-js",
   displayName: "Web (JavaScript / TypeScript)",
   language: "typescript",
-  // Flip to "available" once @whisperr/web ships (Phase 2).
-  availability: "planned"
+  availability: "available"
 };
 function dependsOn(pkgJson, names) {
   try {
@@ -198,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;
@@ -209,41 +224,41 @@ async function detect3(ctx) {
   return { target: target3, confidence: Math.min(confidence, 0.95), evidence };
 }
 var systemPrompt3 = `
-## SDK: Whisperr for Web (TypeScript/JavaScript) \u2014 package \`@whisperr/web\`
+## SDK: Whisperr for Web \u2014 package \`@whisperr/web\` (+ \`@whisperr/react\` for React)
-1) Dependency. Install with the repo's package manager (detect pnpm/yarn/npm
-   from the lockfile): \`<pm> add @whisperr/web\`.
+1) Install (detect pnpm/yarn/npm from the lockfile):
+   - Vanilla / Vue / Svelte / Angular / plain TS: \`<pm> add @whisperr/web\`
+   - React (not Next.js): \`<pm> add @whisperr/react @whisperr/web\`
-2) Initialize once at app entry (e.g. src/main.tsx, src/index.ts, or the root
-   layout). Create a singleton client:
-     import { Whisperr } from '@whisperr/web';
-     export const whisperr = Whisperr.init({
-       apiKey: import.meta.env.VITE_WHISPERR_KEY, // or process.env.NEXT_PUBLIC_... etc
-       baseUrl: '<INGESTION_BASE_URL from manifest>',
-     });
-   Put the key in the project's env mechanism (Vite VITE_*, CRA REACT_APP_*,
-   plain .env) and write the example var into .env / .env.example.
+2) Initialize once at app entry, using the app's PUBLIC env var (VITE_*,
+   REACT_APP_*, etc.). Write the var into .env / .env.example.
+   - Core (any framework): create a singleton in e.g. src/whisperr.ts:
+       import { Whisperr } from '@whisperr/web';
+       export const whisperr = Whisperr.init({
+         apiKey: import.meta.env.VITE_WHISPERR_KEY,
+         baseUrl: '<INGESTION_BASE_URL from manifest>', // omit if it's the default
+       });
+   - React: wrap the app root instead of a bare singleton:
+       import { WhisperrProvider } from '@whisperr/react';
+       <WhisperrProvider apiKey={import.meta.env.VITE_WHISPERR_KEY}>\u2026</WhisperrProvider>
 3) identify(). After auth resolves (login success, and on app load if a session
    is restored):
-     whisperr.identify(user.id, {
-       traits: { /* manifest traits */ },
-       email: user.email, phone: user.phone,
-     });
+       whisperr.identify(user.id, { traits: { /* manifest traits */ }, email: user.email, phone: user.phone });
+   React: const whisperr = useWhisperr();  then whisperr.identify(...).
    Call whisperr.reset() on logout.
 4) track(). For each manifest event, instrument the real handler:
-     whisperr.track('event_type_from_manifest', { /* properties */ });
-   In React, this belongs in event handlers / effects / mutation callbacks, not
+       whisperr.track('event_type_from_manifest', { /* properties */ });
+   In React this belongs in event handlers / effects / mutation callbacks, never
    in render. Copy event_type verbatim (snake_case) from the manifest.
 Notes:
-- The SDK batches via /v1/events/batch and flushes on a timer + on
-  visibilitychange/unload (sendBeacon). Fire-and-forget is fine.
-- Only the NEXT_PUBLIC_/VITE_-style public env vars are exposed to the browser;
-  the ingestion key is a public, rate-limited key so that is expected.
-- If the project uses an analytics wrapper/provider pattern, follow it rather
-  than scattering raw whisperr.track calls.
+- The SDK batches + flushes automatically (timer + on page hide). Fire-and-forget
+  is fine; do NOT await track().
+- It auto-captures pageviews \u2014 you only add the named business events.
+- Only PUBLIC env vars (VITE_/REACT_APP_/NEXT_PUBLIC_) reach the browser; the
+  ingestion key is meant to be public + rate-limited, so that's expected.
 `.trim();
 var webPlaybook = {
   target: target3,
@@ -253,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;
@@ -278,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
@@ -303,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")) {
@@ -337,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
@@ -367,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
@@ -379,6 +752,9 @@ var ALL_PLAYBOOKS = [
   nextjsPlaybook,
   reactNativePlaybook,
   webPlaybook,
+  nodePlaybook,
+  pythonPlaybook,
+  phpPlaybook,
   swiftPlaybook
 ];
 function playbookByTargetId(id) {
@@ -679,7 +1055,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("");
@@ -719,7 +1095,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 = [];
@@ -748,7 +1124,7 @@ async function runIntegrationAgent(opts) {
   ].join("\n");
   const core = await runPass({
     prompt: corePrompt,
-    systemPrompt: systemPrompt6,
+    systemPrompt: systemPrompt9,
     repoPath,
     model: config.model,
     maxTurns: 35,
@@ -777,7 +1153,7 @@ ${core.summary}`);
     ].join("\n");
     const events = await runPass({
       prompt: eventsPrompt,
-      systemPrompt: systemPrompt6,
+      systemPrompt: systemPrompt9,
       repoPath,
       model: config.model,
       maxTurns: config.maxTurns,
@@ -797,7 +1173,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;
@@ -807,7 +1183,7 @@ async function runPass(opts) {
     options: {
       model,
       cwd: repoPath,
-      systemPrompt: systemPrompt6,
+      systemPrompt: systemPrompt9,
       allowedTools: ["Read", "Edit", "Write", "Bash", "Glob", "Grep"],
       permissionMode: "bypassPermissions",
       maxTurns,
@@ -918,6 +1294,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)}`;
@@ -1077,8 +1468,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();
@@ -1114,6 +1521,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");
@@ -1125,6 +1533,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,
@@ -1181,6 +1600,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)) {
@@ -1272,6 +1714,9 @@ function parseArgs(argv) {
       case "--offline":
         opts.offline = true;
         break;
+      case "--force":
+        opts.force = true;
+        break;
       case "--api":
         opts.apiBaseUrl = args[++i];
         break;
@@ -1297,6 +1742,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",
@@ -1315,7 +1761,7 @@ async function main() {
     return;
   }
   if ("version" in parsed) {
-    console.log("0.1.5");
+    console.log("0.1.7");
     return;
   }
   try {

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@whisperr/wizard",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "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,