@whisperr/wizard 0.3.1 → 0.4.0

package/dist/index.js

@@ -8,6 +8,7 @@ import { fileURLToPath } from "url";
 // src/cli.ts
 import { resolve as resolve2 } from "path";
 import * as p from "@clack/prompts";
+import open2 from "open";
 
 // src/core/config.ts
 var DEFAULT_API_BASE = "https://api.whisperr.net";
@@ -1016,42 +1017,67 @@ var divider = theme.dim("\u2500".repeat(48));
 // src/core/auth.ts
 async function authenticate(config) {
   if (config.offline) return offlineSession();
+  const auth = await startDeviceAuth(config);
+  const url = auth.verificationUrlComplete ?? auth.verificationUrl;
+  try {
+    await open(url);
+  } catch {
+  }
+  return auth.poll();
+}
+async function startDeviceAuth(config) {
   const authorize = await fetchJson(
     `${config.apiBaseUrl}/wizard/device/authorize`,
     { method: "POST", body: JSON.stringify({ client: "whisperr-wizard" }) }
   );
-  const url = authorize.verification_uri_complete ?? authorize.verification_uri;
   const intervalMs = (authorize.interval ?? 5) * 1e3;
   const deadline = Date.now() + (authorize.expires_in ?? 600) * 1e3;
-  try {
-    await open(url);
-  } catch {
-  }
-  let wait = intervalMs;
-  while (Date.now() < deadline) {
-    await sleep(wait);
-    const res = await fetch(
-      `${config.apiBaseUrl}/wizard/device/token`,
-      {
-        method: "POST",
-        headers: { "content-type": "application/json" },
-        body: JSON.stringify({ device_code: authorize.device_code })
+  return {
+    verificationUrl: authorize.verification_uri,
+    verificationUrlComplete: authorize.verification_uri_complete,
+    userCode: authorize.user_code,
+    async poll() {
+      let wait = intervalMs;
+      while (Date.now() < deadline) {
+        await sleep(wait);
+        const res = await fetch(
+          `${config.apiBaseUrl}/wizard/device/token`,
+          {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({ device_code: authorize.device_code })
+          }
+        );
+        if (res.ok) {
+          const tok = await res.json();
+          return { token: tok.token, appId: tok.app_id, expiresAt: tok.expires_at };
+        }
+        if (res.status === 429) {
+          wait += 2e3;
+          continue;
+        }
+        if (res.status === 428) continue;
+        throw new Error(
+          `Authorization failed (${res.status}). Re-run the wizard and use the printed link and code to try again.`
+        );
       }
-    );
-    if (res.ok) {
-      const tok = await res.json();
-      return { token: tok.token, appId: tok.app_id, expiresAt: tok.expires_at };
-    }
-    if (res.status === 429) {
-      wait += 2e3;
-      continue;
+      throw new Error(
+        "Authorization timed out. Re-run the wizard and use the printed link and code to try again."
+      );
     }
-    if (res.status === 428) continue;
-    throw new Error(
-      `Authorization failed (${res.status}). Run the wizard again to retry.`
-    );
-  }
-  throw new Error("Authorization timed out. Run the wizard again.");
+  };
+}
+function startSessionKeepalive(config, session, intervalMs = 5 * 6e4) {
+  if (config.offline) return () => {
+  };
+  const timer = setInterval(() => {
+    fetch(`${config.apiBaseUrl}/wizard/first-event`, {
+      headers: { authorization: `Bearer ${session.token}` }
+    }).catch(() => {
+    });
+  }, intervalMs);
+  timer.unref?.();
+  return () => clearInterval(timer);
 }
 function offlineSession() {
   return {
@@ -1405,6 +1431,71 @@ async function submitAdditions(config, session, target9, repoFingerprint2, oppor
   }
   return await res.json();
 }
+async function submitSuggestions(config, session, target9, repoFingerprint2, opportunities) {
+  const res = await fetch(`${config.apiBaseUrl}/wizard/universe/suggestions`, {
+    method: "POST",
+    signal: AbortSignal.timeout(SUBMIT_TIMEOUT_MS),
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${session.token}`
+    },
+    body: JSON.stringify({
+      target: target9,
+      repoFingerprint: repoFingerprint2,
+      events: opportunities.events,
+      interventions: opportunities.interventions
+    })
+  });
+  if (res.status === 404) return null;
+  if (!res.ok) {
+    const body = await res.text().catch(() => "");
+    throw new Error(
+      `Submitting universe suggestions failed (${res.status})${body ? `: ${body.slice(0, 300)}` : ""}`
+    );
+  }
+  return await res.json();
+}
+async function fetchSuggestions(config, session, statuses) {
+  if (config.offline) return [];
+  try {
+    const statusQuery = statuses.map(encodeURIComponent).join(",");
+    const url = `${config.apiBaseUrl}/wizard/universe/suggestions${statusQuery ? `?status=${statusQuery}` : ""}`;
+    const res = await fetch(url, {
+      signal: AbortSignal.timeout(SUBMIT_TIMEOUT_MS),
+      headers: { Authorization: `Bearer ${session.token}` }
+    });
+    if (!res.ok) return [];
+    const body = await res.json();
+    return Array.isArray(body) && body.every(isSuggestionRecord) ? body : [];
+  } catch {
+    return [];
+  }
+}
+function isSuggestionRecord(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const record = value;
+  return typeof record.id === "string" && (record.kind === "event" || record.kind === "intervention") && typeof record.code === "string" && (record.status === "proposed" || record.status === "approved" || record.status === "rejected" || record.status === "integrated") && typeof record.payload === "object" && record.payload !== null;
+}
+async function markSuggestionIntegrated(config, session, id, target9, repoFingerprint2) {
+  if (config.offline) return false;
+  try {
+    const res = await fetch(
+      `${config.apiBaseUrl}/wizard/universe/suggestions/${encodeURIComponent(id)}/integrated`,
+      {
+        method: "POST",
+        signal: AbortSignal.timeout(SUBMIT_TIMEOUT_MS),
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${session.token}`
+        },
+        body: JSON.stringify({ target: target9, repoFingerprint: repoFingerprint2 })
+      }
+    );
+    return res.status === 200;
+  } catch {
+    return false;
+  }
+}
 function asArray(value) {
   return Array.isArray(value) ? value : [];
 }
@@ -1460,6 +1551,7 @@ function coerceEvent(entry) {
     description: asString(e.description),
     ...side ? { side } : {},
     rationale: asString(e.rationale),
+    expectedEffect: asString(e.expectedEffect),
     confidence: asConfidence(e.confidence),
     ...properties.length ? { properties } : {},
     ...links.length ? { links } : {}
@@ -1484,6 +1576,7 @@ function coerceIntervention(entry) {
     label: asString(i.label),
     description: asString(i.description),
     rationale: asString(i.rationale),
+    expectedEffect: asString(i.expectedEffect),
     confidence: asConfidence(i.confidence),
     ...links.length ? { links } : {}
   };
@@ -1684,16 +1777,20 @@ function renderOpportunitiesBrief(m, opportunitiesFile) {
   ];
   return [
     "UNIVERSE OPPORTUNITIES (do this LAST, after your corrections):",
-    "While auditing you read this app's real lifecycle. If you found churn-",
-    "relevant moments the plan does NOT cover \u2014 e.g. a recurring-payment or",
-    "cancellation path with no event, a support/refund flow worth a retention",
-    "play \u2014 record them as PROPOSALS. Do NOT add track() calls for them.",
+    "While auditing you read this app's real lifecycle. Now sweep it",
+    "deliberately: walk each surface the plan should care about \u2014 signup and",
+    "auth, billing/payments (renewals, failures, upgrades, downgrades,",
+    "cancellation), the core engagement loop, support/feedback/refund flows,",
+    "sharing/invites, and any expiry or dormancy mechanics you saw \u2014 and for",
+    "each one ask: does a churn-relevant moment happen here that the plan does",
+    "NOT cover? Record those as PROPOSALS. Do NOT add track() calls for them.",
     `Write a single JSON file at the repo root named ${opportunitiesFile}:`,
     "",
     "{",
     '  "events": [{',
     '    "code": "snake_case_event", "label": "...", "description": "...",',
     '    "side": "frontend|backend|either", "rationale": "what in the code shows this",',
+    '    "expectedEffect": "one sentence: what improves if this is adopted",',
     '    "confidence": 0.0-1.0,',
     '    "properties": [{"name": "...", "description": "...", "required": false}],',
     '    "links": [{"interventionCode": "existing_or_proposed", "weight": 0.0-1.0}]',
@@ -1701,6 +1798,7 @@ function renderOpportunitiesBrief(m, opportunitiesFile) {
     '  "interventions": [{',
     '    "code": "snake_case_strategy", "label": "...", "description": "...",',
     '    "rationale": "...", "confidence": 0.0-1.0,',
+    '    "expectedEffect": "one sentence: what improves if this is adopted",',
     '    "links": [{"eventCode": "existing_or_proposed", "weight": 0.0-1.0}]',
     "  }]",
     "}",
@@ -1710,8 +1808,14 @@ function renderOpportunitiesBrief(m, opportunitiesFile) {
     `  And these interventions: ${interventionCodes.join(", ") || "(none)"}.`,
     "  Propose ONLY what is genuinely missing \u2014 never re-propose or rename these.",
     "- Every proposal needs concrete code evidence in its rationale (file/flow),",
-    "  not speculation. 0-3 events and 0-2 interventions is the normal range;",
-    "  an empty file or no file at all is a perfectly good outcome.",
+    "  not speculation. VERIFY before you write: re-open the file you are citing",
+    "  and confirm the flow exists as described \u2014 a false suggestion costs more",
+    "  trust than a missed one, so drop anything you cannot point at real code.",
+    "- Be thorough, not shy: a feature-rich product typically yields 3-6 solid",
+    "  event proposals and 1-3 interventions. An empty file is only the right",
+    "  answer when the plan genuinely already covers the product's lifecycle \u2014",
+    "  never because you stopped looking early.",
+    "- Every proposal should include expectedEffect: one sentence explaining what adoption should improve.",
     "- Link each proposed event to the intervention(s) it should feed (existing",
     "  codes or ones you propose in the same file).",
     "- This file is metadata for the wizard, not app code \u2014 write it and move on."
@@ -2949,6 +3053,118 @@ function scrubTerminalControls(value) {
   return value.replace(/\x1b\[[0-9;?]*[ -/]*[@-~]/g, "").replace(/\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)?/g, "").replace(/[\x00-\x1f\x7f]/g, " ").replace(/ {2,}/g, " ").trim();
 }
 
+// src/core/gapreport.ts
+function buildGapReport(input) {
+  const outcomes = new Map(
+    input.events.map((event) => [
+      event.eventType,
+      {
+        status: event.status,
+        reason: trimmedReason(event.reason)
+      }
+    ])
+  );
+  const interventions = /* @__PURE__ */ new Map();
+  for (const event of input.manifest.events) {
+    for (const intervention of event.interventions ?? []) {
+      let collected = interventions.get(intervention.code);
+      if (!collected) {
+        collected = {
+          code: intervention.code,
+          label: intervention.label,
+          drivingEvents: [],
+          drivingEventSet: /* @__PURE__ */ new Set()
+        };
+        interventions.set(intervention.code, collected);
+      } else if (!collected.label && intervention.label) {
+        collected.label = intervention.label;
+      }
+      if (!collected.drivingEventSet.has(event.eventType)) {
+        collected.drivingEventSet.add(event.eventType);
+        collected.drivingEvents.push(event.eventType);
+      }
+    }
+  }
+  const interventionGaps = [];
+  for (const intervention of interventions.values()) {
+    const plannedEvents = intervention.drivingEvents.filter((code) => outcomes.has(code));
+    const missingEvents = plannedEvents.flatMap((code) => {
+      const outcome = outcomes.get(code);
+      if (outcome?.status !== "skipped") return [];
+      return [{ code, ...outcome.reason ? { reason: outcome.reason } : {} }];
+    });
+    if (missingEvents.length === 0) continue;
+    interventionGaps.push({
+      code: intervention.code,
+      ...intervention.label ? { label: intervention.label } : {},
+      blocked: missingEvents.length === plannedEvents.length ? "fully" : "partially",
+      missingEvents
+    });
+  }
+  interventionGaps.sort((a, b) => {
+    if (a.blocked !== b.blocked) return a.blocked === "fully" ? -1 : 1;
+    return b.missingEvents.length - a.missingEvents.length;
+  });
+  const otherSurface = input.manifest.universeSummary?.otherSurface ?? 0;
+  const derived = input.manifest.universeSummary?.derived ?? 0;
+  return {
+    interventionGaps,
+    otherSurface,
+    derived,
+    hasContent: interventionGaps.length > 0 || otherSurface > 0
+  };
+}
+function renderGapReport(report, theme2) {
+  const lines = [];
+  for (const gap of report.interventionGaps) {
+    const status = gap.blocked === "fully" ? "on hold" : "running below potential";
+    lines.push(`\u25A0 ${theme2.bright(gap.label ?? gap.code)}${theme2.muted(` \u2014 ${status}`)}`);
+    for (const event of gap.missingEvents) {
+      const reason = event.reason ? ` \u2014 ${lowercaseFirst(event.reason)}` : "";
+      lines.push(
+        theme2.muted("  \xB7 ") + theme2.bright(event.code) + theme2.muted(` isn't flowing yet${reason}`)
+      );
+    }
+    lines.push(
+      theme2.muted(
+        gap.blocked === "fully" ? "  Ship the missing flow and this play switches on by itself \u2014 the strategy is already built for it." : "  It works today, but with only part of its signal \u2014 every event above sharpens it."
+      )
+    );
+  }
+  if (report.otherSurface > 0) {
+    const suffix = report.otherSurface === 1 ? "" : "s";
+    lines.push(
+      `\u25A0 ${report.otherSurface} more event${suffix} live on another surface (your backend or another app)`
+    );
+    lines.push(
+      theme2.muted(
+        "  Run the wizard there and they join the same strategy \u2014 nothing to reconfigure."
+      )
+    );
+  }
+  if (report.derived > 0) {
+    const suffix = report.derived === 1 ? "" : "s";
+    lines.push(
+      theme2.muted(
+        `${report.derived} derived signal${suffix} (dormancy, anniversaries, expiries) are computed by Whisperr automatically once your raw events flow \u2014 nothing to wire.`
+      )
+    );
+  }
+  lines.push(
+    theme2.muted(
+      "All of this is capacity your strategy already includes. Each item you unlock compounds the rest."
+    )
+  );
+  return lines.join("\n");
+}
+function trimmedReason(reason) {
+  const trimmed = reason?.trim();
+  return trimmed || void 0;
+}
+function lowercaseFirst(value) {
+  return value.slice(0, 1).toLowerCase() + value.slice(1);
+}
+
 // src/ui/banner.ts
 function banner() {
   const wave = theme.signal("\u223F\u223F\u223F");
@@ -3012,11 +3228,13 @@ Flutter is live today; ${theme.bright(
     p.cancel(theme.alert(err.message));
     return 1;
   }
+  startSessionKeepalive(config, session);
   const fingerprint = await repoFingerprint(repoPath);
   const manifest = await withSpinner(
     "Loading your onboarding context",
     () => fetchManifest(config, session, chosen.playbook.target.id, fingerprint)
   );
+  const approvedSuggestionsPromise = config.offline ? null : fetchSuggestions(config, session, ["approved"]);
   p.note(
     summarizeManifest(manifest),
     theme.signal(`Plan for ${manifest.appName ?? manifest.appId}`)
@@ -3320,10 +3538,62 @@ ${repair.summary}`].filter(Boolean).join("\n\n");
       )
     );
   }
+  try {
+    const approvedSuggestions = await approvedSuggestionsPromise;
+    if (approvedSuggestions?.length) {
+      const integratedEventCodes = new Set(
+        reportEvents.filter((event) => event.status === "wired").map((event) => normalizeCode(event.event_type))
+      );
+      for (const event of manifest.events) {
+        if (event.coverage?.some((entry) => entry.sameSurface && entry.status === "wired")) {
+          integratedEventCodes.add(normalizeCode(event.eventType));
+        }
+      }
+      const toMark = approvedSuggestions.filter(
+        (suggestion) => suggestion.status === "approved" && (suggestion.kind === "intervention" || integratedEventCodes.has(normalizeCode(suggestion.code)))
+      );
+      const marked = (await Promise.all(
+        toMark.map(
+          (suggestion) => markSuggestionIntegrated(
+            config,
+            session,
+            suggestion.id,
+            chosen.playbook.target.id,
+            fingerprint
+          )
+        )
+      )).filter(Boolean).length;
+      if (marked > 0) {
+        p.log.info(
+          theme.muted(
+            `${marked} approved suggestion${marked === 1 ? "" : "s"} marked integrated.`
+          )
+        );
+      }
+    }
+  } catch {
+  }
   const eventLines = renderEventOutcomeLines(outcome.eventOutcomes, wiredMap);
   if (eventLines) {
     p.note(eventLines, "Events");
   }
+  const eventOutcomeByType = new Map(
+    outcome.eventOutcomes.map((event) => [event.event, event])
+  );
+  const gapReport = buildGapReport({
+    manifest,
+    events: reportEvents.map((event) => ({
+      eventType: event.event_type,
+      status: event.status,
+      reason: eventOutcomeByType.get(event.event_type)?.reason
+    }))
+  });
+  if (gapReport.hasContent) {
+    p.note(
+      renderGapReport(gapReport, theme),
+      theme.signal("What you could be doing")
+    );
+  }
   const eventDenominator = manifest.universeSummary?.wireableHere ?? eventTypesToScan.length;
   const eventStatsLabel = manifest.universeSummary ? "events wired here" : "events wired";
   const timingDetails = outcome.phaseTimings.map(({ phase, ms }) => `${shortPhaseLabel(phase)} ${formatDuration(ms)}`).join(" \xB7 ");
@@ -3366,7 +3636,21 @@ ${repair.summary}`].filter(Boolean).join("\n\n");
 }
 var NO_ADDITIONS = { acceptedEvents: [], instrumentationSnapshot: null };
 async function offerOpportunities(opts) {
-  const { opportunities, manifest, config, session } = opts;
+  const { manifest, config, session } = opts;
+  const openSuggestions = await fetchSuggestions(config, session, ["proposed", "approved"]);
+  const openSuggestionKeys = new Set(
+    openSuggestions.map(
+      (suggestion) => `${suggestion.kind}:${normalizeCode(suggestion.code)}`
+    )
+  );
+  const opportunities = {
+    events: opts.opportunities.events.filter(
+      (event) => !openSuggestionKeys.has(`event:${normalizeCode(event.code)}`)
+    ),
+    interventions: opts.opportunities.interventions.filter(
+      (intervention) => !openSuggestionKeys.has(`intervention:${normalizeCode(intervention.code)}`)
+    )
+  };
   const total = opportunities.events.length + opportunities.interventions.length;
   if (total === 0) return NO_ADDITIONS;
   const describe = (kind, code, why) => `${theme.muted(`${kind}: `)}${theme.bright(code)}${why ? theme.muted(` \u2014 ${why}`) : ""}`;
@@ -3390,7 +3674,7 @@ async function offerOpportunities(opts) {
     return NO_ADDITIONS;
   }
   const selection = await p.multiselect({
-    message: "Add these to your Whisperr universe? (new interventions start paused)",
+    message: "Send these to your dashboard for approval?",
     options: [
       ...opportunities.events.map((e) => ({
         value: `e:${e.code}`,
@@ -3403,8 +3687,8 @@ async function offerOpportunities(opts) {
         hint: i.description ?? i.rationale
       }))
     ],
-    // Opt-in per item: nothing is pre-selected, so adding to the universe is an
-    // explicit choice rather than an opt-out the user has to notice and undo.
+    // Opt-in per item: nothing is pre-selected, so submitting a suggestion is
+    // an explicit choice rather than an opt-out the user has to notice and undo.
     initialValues: [],
     required: false
   });
@@ -3437,6 +3721,39 @@ async function offerOpportunities(opts) {
       )
     }))
   };
+  let stageResult;
+  try {
+    stageResult = await withSpinner(
+      "Sending suggestions for approval",
+      () => submitSuggestions(config, session, opts.playbook.target.id, opts.fingerprint, submitted)
+    );
+  } catch (err) {
+    p.log.warn(
+      theme.warn("Couldn't send the proposals") + theme.muted(` \u2014 ${err.message}. Nothing was submitted.`)
+    );
+    return NO_ADDITIONS;
+  }
+  if (stageResult) {
+    const lines2 = stageResult.outcomes.map((outcome) => {
+      const mark = outcome.status === "staged" ? theme.success("\u2713") : outcome.status === "duplicate" ? theme.muted("=") : theme.warn("\u2717");
+      const reason = outcome.reason ?? (outcome.duplicateOf && outcome.duplicateOf !== outcome.code ? `already queued as ${outcome.duplicateOf}` : void 0);
+      const detail = reason ? theme.muted(` (${reason})`) : "";
+      return `${mark} ${outcome.kind} ${theme.bright(outcome.code)}${detail}`;
+    });
+    lines2.push(
+      theme.muted(
+        `${stageResult.staged} staged \xB7 ${stageResult.duplicates} already queued \xB7 ${stageResult.invalid} rejected`
+      )
+    );
+    p.note(lines2.join("\n"), theme.signal("Suggestions submitted"));
+    const where = stageResult.approvalsUrl ? `approve at ${theme.bright(stageResult.approvalsUrl)}` : "approve them in your Whisperr dashboard";
+    p.log.info(
+      theme.muted(
+        `${stageResult.staged} proposal${stageResult.staged === 1 ? "" : "s"} sent \u2014 ${where}. The next wizard run wires whatever you approve.`
+      )
+    );
+    return NO_ADDITIONS;
+  }
   let result;
   try {
     result = await withSpinner(
@@ -3582,10 +3899,25 @@ async function withBrowserAuth(config) {
   p.log.step(
     theme.bright("Authenticate") + theme.muted(" \u2014 opening your browser to approve this device\u2026")
   );
+  const auth = await startDeviceAuth(config);
+  p.note(
+    [
+      theme.bright(`Your code: ${auth.userCode}`),
+      `${theme.muted("Approval URL:")} ${auth.verificationUrl}`,
+      theme.muted(
+        "We tried to open your browser. If it didn't open, visit that link on any device and enter the code."
+      )
+    ].join("\n"),
+    theme.signal("Approve this device")
+  );
+  try {
+    await open2(auth.verificationUrlComplete ?? auth.verificationUrl);
+  } catch {
+  }
   const spin = p.spinner();
   spin.start("Waiting for you to approve in the browser");
   try {
-    const session = await authenticate(config);
+    const session = await auth.poll();
     spin.stop(theme.success("Authenticated \u2713"));
     return session;
   } catch (err) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@whisperr/wizard",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "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.",
   "repository": {
     "type": "git",