@saaspro/wizard 0.1.0 → 0.2.0

package/README.md

@@ -13,16 +13,49 @@ Approval requires keys.write and a fresh passkey. It creates a public key labell
 Wizard and encrypts the one-time reveal to an RSA key generated in the CLI. The
 private key stays in memory. Codes expire in ten minutes and are single use.
 
-Flags: --host <origin>, --dry-run, --key <spm_pub_...>, --no-install, --no-mcp, --no-open,
+Flags: --consent <granted|pending>, --host <origin>, --dry-run, --key <spm_pub_...>, --no-install, --no-mcp, --no-open,
 --help. Dry runs still need approval unless --key is given; no files, packages
 or verification events change. HTTPS is required except for loopback development.
 Secret keys are rejected. The public key is printed once; later output omits it.
 
-Detects Next.js, Vite/React, Expo/React Native, Node and Python. Uses your lockfile
-to choose npm, pnpm, Yarn or Bun. Writes .env.local for Next.js or .env otherwise,
-adds the env filename to .gitignore, and creates initialization only when the
-pattern is unambiguous and the target is absent. Otherwise prints the exact code
-and remaining steps. Conflicting env values cause a refusal instead of overwrite.
+Detects Next.js App/Pages Router, Remix/React Router framework mode, Vite/React,
+SvelteKit, Nuxt, Vue with Vite, Astro, plain Svelte, Expo/React Native, Node and
+Python. Meta-frameworks take precedence. Uses your lockfile to choose npm, pnpm,
+Yarn or Bun. Writes .env.local for Next.js or .env otherwise and adds it to
+.gitignore. Conflicting env values cause a refusal.
+
+For one unambiguous entry and render point, imports the generated provider and
+wraps Next.js layout children or the Pages Router Component, React's App render
+root, or Remix/React Router's Outlet. Providers live beside that entry, except
+Pages Router providers live outside pages/ so they do not become routes. Vue gets
+browser SDK initialization before mount. SvelteKit gets src/hooks.client.ts/js;
+existing hooks are preserved. Astro gets src/components/SaaSPro.astro and an
+import/component insertion in a single src/layouts layout containing </head>.
+Existing providers, multiple roots/matches or unusual syntax print manual steps;
+source is not reformatted. Repeated runs do not add duplicate wrappers.
+
+Nuxt gets plugins/saaspro.client.ts/js using useRuntimeConfig().public.spmKey,
+with NUXT_PUBLIC_SPM_KEY. Merge the printed runtimeConfig.public.spmKey and
+explicit plugin registration into nuxt.config; the wizard never edits that
+config. Explicit registration also supports Nuxt 4's app/plugins convention.
+SvelteKit uses PUBLIC_SPM_KEY from $env/static/public (deprecated in SvelteKit 3,
+removed in 4 per current docs). Vue/Vite and Remix use VITE_SPM_KEY; Astro uses
+PUBLIC_SPM_KEY. Legacy Remix must use Vite. Plain Svelte gets manual setup.
+
+Without a consent manager, generated browser configuration omits consent,
+using the SDK's granted default. Recognized managers (vanilla-cookieconsent,
+cookieconsent, react-cookie-consent, @cookiehub/*, klaro, @osano/*, @onetrust/*,
+cookiebot, @iubenda/*, tarteaucitronjs, @c15t/*, @consentmanager/*) generate
+consent: "pending". Wire analytics acceptance and saved consent to
+spm.consent("granted"), and rejection/withdrawal to spm.consent("revoked"). In
+React use the client from useSaaSProMax(); mobile uses analytics.setConsent().
+--consent granted or --consent pending overrides detection. Pending holds events
+in memory until granted. Persistent identity remains enabled for identify and
+revenue attribution; ephemeral mode is never selected by default.
+
+Next.js App Router uses the route-aware SPMPageview component. Other browser
+integrations use SDK auto page views for pushState, replaceState and popstate,
+so client-side navigation works without reading location only at mount.
 
 Node uses @saaspro/node/native for public-key manual events. Python's SDK requires
 a separate secret key, so the wizard installs the SDK and prints explicit manual
@@ -35,5 +68,5 @@ Other settings stay intact. A conflicting saaspro entry is refused. These files
 contain a URL, not tokens; complete separate browser OAuth in your MCP client.
 
 Finally sends spm.wizard.verified and requires one accepted event. This proves
-CLI collection; verify your application's real events after importing the setup.
+CLI collection; verify your application's real events after completing the printed steps.
 The public download is byte-identical to the packaged ESM source.

package/bin/saaspro-wizard.mjs

@@ -1,13 +1,13 @@
 #!/usr/bin/env node
 import { constants, generateKeyPairSync, privateDecrypt, randomUUID } from "node:crypto";
 import { execFileSync, spawn } from "node:child_process";
-import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
+import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, realpathSync, writeFileSync } from "node:fs";
+import { dirname, join, posix, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 
 class WizardError extends Error {}
 
-const VERSION = "0.1.0";
+const VERSION = "0.2.0";
 const PUBLIC_KEY = /^spm_pub_(?:prod|stg|dev)_[A-Za-z0-9]{22}$/;
 const HELP = `SaaS Pro Max wizard
 
@@ -19,19 +19,28 @@ Options:
   --host <url>     API origin (default https://saaspro.dev)
   --dry-run        Preview file changes and commands; device approval still runs
   --key <key>      Use a public ingest key and skip device approval
+  --consent <granted|pending>  Override consent-manager detection
   --no-install     Skip SDK installation
   --no-mcp         Skip Claude Code and Cursor MCP configuration
   --no-open        Print the approval link without opening a browser
   --help           Show this help
 
+Frameworks: Next.js (App/Pages), Remix/React Router, Vite/React, SvelteKit,
+Nuxt, Vue, Astro, Svelte (manual), Expo/React Native, Node and Python.
 No terminal prompts or stdin reads. Only public keys are accepted.
 `;
 
 export function detectFramework(pkg, files = []) {
   const deps = { ...pkg?.devDependencies, ...pkg?.dependencies };
+  if (deps.next) return "nextjs";
+  if (deps["@remix-run/react"] || deps["@react-router/dev"] || (deps["react-router"] && files.some(path => /^app\/root\.(tsx|jsx|ts|js)$/.test(path)))) return "remix";
+  if (deps["@sveltejs/kit"]) return "sveltekit";
+  if (deps.nuxt) return "nuxt";
+  if (deps.astro) return "astro";
+  if (deps.vue) return "vue";
+  if (deps.svelte) return "svelte";
   if (deps.expo) return "expo";
   if (deps["react-native"]) return "react-native";
-  if (deps.next) return "nextjs";
   if (deps.react) return deps.vite ? "vite-react" : "react";
   if (files.includes("pyproject.toml") || files.includes("requirements.txt")) return "python";
   return pkg ? "node" : "unknown";
@@ -71,7 +80,7 @@ export function mergeEnv(existing, values) {
 }
 
 export function parseFlags(args) {
-  const options = { host: "https://saaspro.dev", dryRun: false, install: true, mcp: true, open: true, key: null, help: false };
+  const options = { host: "https://saaspro.dev", dryRun: false, install: true, mcp: true, open: true, key: null, consent: null, help: false };
   for (let i = 0; i < args.length; i++) {
     const flag = args[i];
     if (flag === "--help") options.help = true;
@@ -79,12 +88,13 @@ export function parseFlags(args) {
     else if (flag === "--no-install") options.install = false;
     else if (flag === "--no-mcp") options.mcp = false;
     else if (flag === "--no-open") options.open = false;
-    else if (flag === "--host" || flag === "--key") {
+    else if (flag === "--host" || flag === "--key" || flag === "--consent") {
       const value = args[++i];
       if (!value || value.startsWith("--")) throw new WizardError(`${flag} requires a value`);
-      options[flag === "--host" ? "host" : "key"] = value;
+      options[flag.slice(2)] = value;
     } else throw new WizardError("Unknown option. Use --help for supported flags.");
   }
+  if (options.consent && !["granted", "pending"].includes(options.consent)) throw new WizardError("--consent must be granted or pending");
   const url = new URL(options.host);
   if (url.username || url.password || url.search || url.hash || url.pathname !== "/" || (url.protocol !== "https:" && !(url.protocol === "http:" && ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname)))) throw new WizardError("Host must be an HTTPS origin or a loopback HTTP origin");
   options.host = url.origin;
@@ -158,22 +168,96 @@ function installPackages(manager, packages, options) {
   if (options.install && !options.dryRun) execFileSync(manager, args, { stdio: ["ignore", "inherit", "inherit"] });
 }
 
-export function integrationPlan(framework, host, paths) {
-  if (framework === "nextjs") {
-    const roots = ["app", "src/app"].filter(root => paths.some(path => new RegExp(`^${root}/layout\\.(tsx|jsx|js)$`).test(path)));
-    const directory = roots.length === 1 ? roots[0] : null;
-    const typed = directory ? paths.includes(`${directory}/layout.tsx`) : true;
-    const code = `"use client";\n${typed ? 'import type { ReactNode } from "react";\n' : ""}import { Suspense } from "react";\nimport { SaaSProMaxProvider } from "@saaspro/react";\nimport { SPMPageview } from "@saaspro/react/next";\n\nexport function SaaSProProvider({ children }${typed ? ": { children: ReactNode }" : ""}) {\n  return <SaaSProMaxProvider config={{ key: process.env.NEXT_PUBLIC_SPM_KEY, host: ${JSON.stringify(host)}, autoPageviews: false, consent: "pending" }}>\n    <Suspense fallback={null}><SPMPageview /></Suspense>\n    {children}\n  </SaaSProMaxProvider>;\n}\n`;
-    return { packages: ["@saaspro/react"], env: "NEXT_PUBLIC_SPM_KEY", file: ".env.local", target: directory ? `${directory}/saaspro-provider.${typed ? "tsx" : "jsx"}` : null, code, instructions: `Import { SaaSProProvider } from "./saaspro-provider" in your app layout and wrap its children. Connect your consent controls to useSaaSProMax().consent("granted"). For Pages Router or multiple app roots, place this provider in your existing root component.` };
+export const CONSENT_MANAGERS = [
+  "vanilla-cookieconsent", "cookieconsent", "react-cookie-consent", "@cookiehub/*",
+  "klaro", "@osano/*", "@onetrust/*", "cookiebot", "@iubenda/*", "tarteaucitronjs",
+  "@c15t/*", "@consentmanager/*",
+];
+
+export function detectConsentManagers(pkg) {
+  return Object.keys({ ...pkg?.devDependencies, ...pkg?.dependencies }).filter(name =>
+    CONSENT_MANAGERS.some(pattern => pattern.endsWith("/*") ? name.startsWith(pattern.slice(0, -1)) : name === pattern));
+}
+
+const JSX_EXTENSIONS = ["tsx", "jsx", "js", "ts"];
+const ROOTS = ["app/layout", "src/app/layout", "pages/_app", "src/pages/_app", "app/root", "src/main", "src/index"];
+const ENTRY_PATHS = ROOTS.flatMap(path => JSX_EXTENSIONS.map(ext => `${path}.${ext}`));
+
+function projectPaths(root) {
+  const paths = [...ENTRY_PATHS, "tsconfig.json", "src/hooks.client.ts", "src/hooks.client.js",
+    "plugins/saaspro.client.ts", "plugins/saaspro.client.js", "src/components/SaaSPro.astro"]
+    .filter(path => existsSync(join(root, path)));
+  const walk = directory => {
+    if (!existsSync(join(root, directory)) || lstatSync(join(root, directory)).isSymbolicLink()) return;
+    for (const entry of readdirSync(join(root, directory), { withFileTypes: true })) {
+      const path = `${directory}/${entry.name}`;
+      if (entry.isDirectory()) walk(path);
+      else if (entry.isFile() && path.endsWith(".astro")) paths.push(path);
+    }
+  };
+  walk("src/layouts");
+  return paths;
+}
+
+export function integrationPlan(framework, host, paths, consent = null) {
+  const consentOption = consent ? `, consent: "${consent}"` : "";
+  const single = candidates => candidates.length === 1 ? candidates[0] : null;
+  const entries = pattern => paths.filter(path => pattern.test(path));
+  if (["nextjs", "vite-react", "react", "remix"].includes(framework)) {
+    const next = framework === "nextjs";
+    const appEntries = entries(/^(?:src\/)?app\/layout\.(tsx|jsx|js|ts)$/);
+    const candidates = next ? [...appEntries, ...entries(/^(?:src\/)?pages\/_app\.(tsx|jsx|js|ts)$/)]
+      : framework === "remix" ? entries(/^app\/root\.(tsx|jsx|js|ts)$/) : entries(/^src\/(?:main|index)\.(tsx|jsx|js|ts)$/);
+    const entry = single(candidates);
+    const appRouter = next && !!entry && appEntries.includes(entry);
+    const typed = entry ? /\.tsx?$/.test(entry) : paths.includes("tsconfig.json");
+    const directory = entry ? posix.dirname(entry) : null;
+    const providerDirectory = next && entry && !appRouter ? posix.dirname(directory) : directory;
+    const target = providerDirectory ? `${providerDirectory === "." ? "" : `${providerDirectory}/`}saaspro-provider.${typed ? "tsx" : "jsx"}` : null;
+    const providerImport = next && entry && !appRouter ? "../saaspro-provider" : "./saaspro-provider";
+    const env = next ? "NEXT_PUBLIC_SPM_KEY" : framework === "react" ? "REACT_APP_SPM_KEY" : "VITE_SPM_KEY";
+    const key = next || framework === "react" ? `process.env.${env}${typed ? "!" : ""}` : `import.meta.env.${env}`;
+    const code = `"use client";\n${typed ? 'import type { ReactNode } from "react";\n' : ""}import { SaaSProMaxProvider } from "@saaspro/react";\n${appRouter ? 'import { SPMPageview } from "@saaspro/react/next";\n' : ""}\nexport function SaaSProProvider({ children }${typed ? ": { children: ReactNode }" : ""}) {\n  return <SaaSProMaxProvider config={{ key: ${key}, host: ${JSON.stringify(host)}, autoPageviews: ${!appRouter}${consentOption} }}>\n    ${appRouter ? "<SPMPageview />\n    " : ""}{children}\n  </SaaSProMaxProvider>;\n}\n`;
+    const wrap = next ? appRouter ? "children" : "component" : framework === "remix" ? "outlet" : "app";
+    return { packages: ["@saaspro/react"], env, file: next ? ".env.local" : ".env", target, providerImport, entry, wrap, code,
+      instructions: `Manual setup if automatic wiring is skipped: place ${target ?? `saaspro-provider.${typed ? "tsx" : "jsx"}`} ${next && !appRouter ? "outside the pages directory" : "beside your root component"}, import { SaaSProProvider } from "${providerImport}", and wrap ${wrap === "children" ? "{children} inside <body>" : wrap === "component" ? "<Component {...pageProps} /> in pages/_app" : wrap === "outlet" ? "<Outlet /> in app/root" : "<App /> in src/main or src/index"} with <SaaSProProvider>...</SaaSProProvider>.${next && !entry ? " For App Router use SPMPageview from @saaspro/react/next with autoPageviews: false; for Pages Router keep autoPageviews: true." : ""}${framework === "remix" ? " VITE_SPM_KEY requires Remix Vite or React Router framework mode; migrate a legacy Remix compiler before using this code." : ""}` };
   }
-  if (framework === "vite-react" || framework === "react") {
-    const typed = paths.includes("src/main.tsx");
-    const code = `${typed ? 'import type { ReactNode } from "react";\n' : ""}import { SaaSProMaxProvider, SPMPageview } from "@saaspro/react";\n\nexport function SaaSProProvider({ children }${typed ? ": { children: ReactNode }" : ""}) {\n  return <SaaSProMaxProvider config={{ key: ${framework === "vite-react" ? "import.meta.env.VITE_SPM_KEY" : "process.env.REACT_APP_SPM_KEY"}, host: ${JSON.stringify(host)}, autoPageviews: false, consent: "pending" }}>\n    <SPMPageview pathname={location.pathname} search={location.search} />\n    {children}\n  </SaaSProMaxProvider>;\n}\n`;
-    return { packages: ["@saaspro/react"], env: framework === "vite-react" ? "VITE_SPM_KEY" : "REACT_APP_SPM_KEY", file: ".env", target: framework === "vite-react" && (paths.includes("src/main.jsx") || typed) ? `src/saaspro-provider.${typed ? "tsx" : "jsx"}` : null, code, instructions: `Import { SaaSProProvider } from "./saaspro-provider" and wrap your root component. Supply route changes to SPMPageview from your router. Connect consent controls to useSaaSProMax().consent("granted"). Confirm your bundler exposes the configured public environment variable.` };
+  if (["sveltekit", "nuxt", "vue", "astro", "svelte"].includes(framework)) {
+    const typed = paths.includes("tsconfig.json") || paths.some(path => /(?:main|hooks\.client)\.ts$/.test(path));
+    const ext = typed ? "ts" : "js";
+    const env = framework === "nuxt" ? "NUXT_PUBLIC_SPM_KEY" : ["sveltekit", "astro"].includes(framework) ? "PUBLIC_SPM_KEY" : "VITE_SPM_KEY";
+    const key = framework === "sveltekit" ? "PUBLIC_SPM_KEY" : framework === "nuxt" ? "config.public.spmKey" : `import.meta.env.${env}`;
+    const init = `spm.init({ key: ${key}, host: ${JSON.stringify(host)}, autoPageviews: true${consentOption} });`;
+    let code = `import { spm } from "@saaspro/browser";\n${init}\n`;
+    let target = null, entry = null, wrap = null;
+    let instructions = "";
+    if (framework === "sveltekit") {
+      const hooks = entries(/^src\/hooks\.client\.(ts|js)$/);
+      target = hooks.length ? single(hooks) : `src/hooks.client.${ext}`;
+      code = `import { PUBLIC_SPM_KEY } from "$env/static/public";\n${code}`;
+      instructions = "If hooks.client already exists, merge this initialization into it once, preserving existing hooks. $env/static/public is supported by SvelteKit 2/3 (deprecated in 3); for SvelteKit 4 follow its environment migration guide.";
+    } else if (framework === "nuxt") {
+      const plugins = entries(/^plugins\/saaspro\.client\.(ts|js)$/);
+      target = plugins.length ? single(plugins) : `plugins/saaspro.client.${ext}`;
+      code = `import { defineNuxtPlugin, useRuntimeConfig } from "#app";\nimport { spm } from "@saaspro/browser";\n\nexport default defineNuxtPlugin(() => {\n  const config = useRuntimeConfig();\n  ${init}\n});\n`;
+      instructions = `Merge into nuxt.config (the wizard does not edit it):\nexport default defineNuxtConfig({\n  runtimeConfig: { public: { spmKey: "" } },\n  plugins: ["~~/plugins/saaspro.client.${ext}"],\n});\nPreserve existing config and plugins. NUXT_PUBLIC_SPM_KEY overrides public.spmKey. Explicit registration also supports Nuxt 4, whose default auto-scanned directory is app/plugins. Set NUXT_PUBLIC_SPM_KEY in the production runtime environment; .env is for development/build.`;
+    } else if (framework === "astro") {
+      target = "src/components/SaaSPro.astro";
+      code = `<script>\n  import { spm } from "@saaspro/browser";\n  ${init}\n</script>\n`;
+      wrap = "astro";
+      instructions = 'Manual setup if automatic wiring is skipped: import SaaSPro from the relative path to src/components/SaaSPro.astro in your layout frontmatter, then add <SaaSPro /> before </head>.';
+    } else if (framework === "vue") {
+      entry = single(entries(/^src\/main\.(ts|js)$/));
+      wrap = "vue";
+      instructions = `Manual setup if automatic wiring is skipped: add this code once in src/main.${ext}, before createApp(...).mount(...) or app.mount(...).`;
+    } else {
+      instructions = "Import this initialization once in your browser entry (src/main.ts or src/main.js), before mounting Svelte. No source file is automatically edited for plain Svelte.";
+    }
+    return { packages: ["@saaspro/browser"], env, file: ".env", target, entry, wrap, code, instructions };
   }
   if (framework === "expo" || framework === "react-native") {
     const expo = framework === "expo";
-    const code = `${expo ? 'import * as Crypto from "expo-crypto";' : 'import "react-native-get-random-values";\nimport { v4 as randomUUID } from "uuid";'}\nimport AsyncStorage from "@react-native-async-storage/async-storage";\nimport { AppState, Platform } from "react-native";\nimport { SaaSProMobile } from "@saaspro/react-native";\n\nexport const analytics = new SaaSProMobile({\n  key: ${expo ? "process.env.EXPO_PUBLIC_SPM_KEY" : '"<public key from .env: SPM_PUBLIC_KEY>"'},\n  host: ${JSON.stringify(host)}, platform: Platform.OS, storage: AsyncStorage,\n  randomUUID: ${expo ? "Crypto.randomUUID" : "randomUUID"}, appState: AppState, consent: "pending", privacyMode: "persistent",\n});\n`;
+    const code = `${expo ? 'import * as Crypto from "expo-crypto";' : 'import "react-native-get-random-values";\nimport { v4 as randomUUID } from "uuid";'}\nimport AsyncStorage from "@react-native-async-storage/async-storage";\nimport { AppState, Platform } from "react-native";\nimport { SaaSProMobile } from "@saaspro/react-native";\n\nexport const analytics = new SaaSProMobile({\n  key: ${expo ? "process.env.EXPO_PUBLIC_SPM_KEY" : '"<public key from .env: SPM_PUBLIC_KEY>"'},\n  host: ${JSON.stringify(host)}, platform: Platform.OS, storage: AsyncStorage,\n  randomUUID: ${expo ? "Crypto.randomUUID" : "randomUUID"}, appState: AppState${consentOption}, privacyMode: "persistent",\n});\n`;
     return { packages: ["@saaspro/react-native"], env: expo ? "EXPO_PUBLIC_SPM_KEY" : "SPM_PUBLIC_KEY", file: ".env", target: null, code, instructions: `${expo ? "Run npx expo install expo-crypto @react-native-async-storage/async-storage." : "Install react-native-get-random-values, uuid and @react-native-async-storage/async-storage, then supply SPM_PUBLIC_KEY through your existing native configuration loader."} Put this code in your analytics module, wrap your app in SaaSProMobileProvider, and connect existing consent controls to analytics.setConsent("granted"). Rebuild native dependencies where required.` };
   }
   if (framework === "node") {
@@ -183,7 +267,95 @@ export function integrationPlan(framework, host, paths) {
   if (framework === "python") {
     return { packages: [], env: "SPM_PUBLIC_KEY", file: ".env", target: null, code: `import os\nfrom saaspro import SaaSProMax\n\n# Create a separate secret key in Settings -> API keys and load it from your server's secret manager.\nspm = SaaSProMax(os.environ["SPM_INGEST_KEY"], host=os.environ["SPM_HOST"])\nspm.track("app.started", {"source": "wizard"})\nspm.flush(timeout=10)\n`, instructions: `Install: python -m pip install ${host}/downloads/saaspro-0.1.0.tar.gz\nThe Python SDK requires a secret key. The wizard only provisions a public key, so it does not initialize the Python SDK or write SPM_INGEST_KEY. Set that separately in your secret manager. The wizard verification event uses the public key.` };
   }
-  return { packages: [], env: "SPM_PUBLIC_KEY", file: ".env", target: null, code: `<script defer src="${host}/spm.js" data-key="<public key from .env: SPM_PUBLIC_KEY>" data-host="${host}"></script>`, instructions: "No supported framework was detected. Use the script tag for a website or open the Install guide for your framework. Preserve your site's consent controls." };
+  return { packages: [], env: "SPM_PUBLIC_KEY", file: ".env", target: null, code: `<script defer src="${host}/spm.js" data-key="<public key from .env: SPM_PUBLIC_KEY>" data-host="${host}"${consent ? ` data-consent="${consent}"` : ""}></script>`, instructions: "No supported framework was detected. Use the script tag for a website or open the Install guide for your framework. Preserve your site's consent controls." };
+}
+
+// Mask comments and literals so examples in them cannot become edit targets.
+function sourceMask(code) {
+  return code.replace(/\/\*[\s\S]*?\*\/|\/\/[^\r\n]*|"(?:\\[\s\S]|[^"\\])*"|'(?:\\[\s\S]|[^'\\])*'|`(?:\\[\s\S]|[^`\\])*`/g,
+    value => value.replace(/[^\r\n]/g, " "));
+}
+
+function sourceStyle(code) {
+  const statement = code.match(/^\s*import\s+[^\r\n]*?(["'])[^"']+\1[ \t]*(;?)/m);
+  return { quote: statement?.[1] ?? '"', semi: statement ? statement[2] : ";", newline: code.includes("\r\n") ? "\r\n" : "\n" };
+}
+
+function addImport(code, statement, newline) {
+  const prefix = code.match(/^(?:(?:\s|\/\*[\s\S]*?\*\/|\/\/[^\r\n]*(?:\r?\n|$))*(?:["']use (?:client|strict|server)["'];?\s*))*/)?.[0] ?? "";
+  return `${prefix}${statement}${newline}${code.slice(prefix.length)}`;
+}
+
+export function integrationEdit(root, plan, paths) {
+  if (!plan.wrap) return null;
+  if (plan.wrap === "astro") {
+    const candidates = paths.filter(path => path.startsWith("src/layouts/") && path.endsWith(".astro"))
+      .map(path => {
+        const code = readFileSync(join(root, path), "utf8");
+        const frontmatter = code.startsWith("---") ? code.match(/^---\r?\n[\s\S]*?^---(?:\r?\n|$)/m)?.[0] : "";
+        const markup = code.slice(frontmatter?.length ?? 0).replace(/<!--[\s\S]*?-->|<script\b[^>]*>[\s\S]*?<\/script\s*>|"(?:\\[\s\S]|[^"\\])*"|'(?:\\[\s\S]|[^'\\])*'|`(?:\\[\s\S]|[^`\\])*`/g,
+          value => value.replace(/[^\r\n]/g, " "));
+        return { path, code, frontmatter, heads: [...markup.matchAll(/<\/head\s*>/g)] };
+      }).filter(layout => layout.heads.length);
+    if (candidates.length !== 1) return null;
+    const { path, frontmatter, heads } = candidates[0];
+    let { code } = candidates[0];
+    noSymlinks(root, path);
+    if (frontmatter === undefined || /\bSaaSPro\b/.test(code) || heads.length !== 1) return null;
+    const { quote, semi, newline } = sourceStyle(code);
+    let relative = posix.relative(posix.dirname(path), plan.target);
+    if (!relative.startsWith(".")) relative = `./${relative}`;
+    const statement = `import SaaSPro from ${quote}${relative}${quote}${semi}${newline}`;
+    const headAt = frontmatter.length + heads[0].index;
+    code = `${code.slice(0, headAt)}<SaaSPro />${newline}${code.slice(headAt)}`;
+    if (frontmatter) code = code.slice(0, 3 + newline.length) + statement + code.slice(3 + newline.length);
+    else if (!code.trimStart().startsWith("---")) code = `---${newline}${statement}---${newline}${code}`;
+    else return null;
+    return { path, code, description: "import SaaSPro and insert <SaaSPro /> before </head>" };
+  }
+  if (!plan.entry) return null;
+  const path = plan.entry;
+  noSymlinks(root, path);
+  const code = readFileSync(join(root, path), "utf8");
+  if (/\bSaaSProProvider\b|saaspro-provider|@saaspro\//.test(code)) return null;
+  const masked = sourceMask(code);
+  const { quote, semi, newline } = sourceStyle(code);
+  if (plan.wrap === "vue") {
+    if (/\bspm\b/.test(masked)) return null;
+    const calls = [...masked.matchAll(/^[ \t]*(?:(?:const|let|var)\s+\w+\s*=\s*)?createApp\s*\(/gm)];
+    const mounts = [...masked.matchAll(/\.mount\s*\(/g)];
+    if (calls.length !== 1 || mounts.length !== 1 || calls[0].index >= mounts[0].index) return null;
+    const init = plan.code.slice(plan.code.indexOf("spm.init")).trim().replace(/;$/, semi);
+    const edited = code.slice(0, calls[0].index) + init + newline + code.slice(calls[0].index);
+    return { path, code: addImport(edited, `import { spm } from ${quote}@saaspro/browser${quote}${semi}`, newline), description: "initialize the browser SDK before createApp(...).mount(...)" };
+  }
+  const pattern = plan.wrap === "children" ? /\{\s*children\s*\}/g
+    : plan.wrap === "component" ? /<Component\s+\{\s*\.\.\.pageProps\s*\}\s*\/>/g
+    : plan.wrap === "outlet" ? /<Outlet\s*\/>/g : /<App\s*\/>/g;
+  let start = 0, scope = masked;
+  if (plan.wrap === "children") {
+    const bodies = [...masked.matchAll(/<body\b[^>]*>[\s\S]*?<\/body\s*>/g)];
+    if (bodies.length !== 1) return null;
+    start = bodies[0].index;
+    scope = bodies[0][0];
+  }
+  const matches = [...scope.matchAll(pattern)];
+  if (matches.length !== 1) return null;
+  const match = matches[0];
+  match.index += start;
+  if (plan.wrap === "app") {
+    const renders = [...masked.matchAll(/\b(?:render|hydrateRoot)\s*\(/g)];
+    if (renders.length !== 1 || renders[0].index >= match.index) return null;
+    let depth = 1;
+    for (let i = renders[0].index + renders[0][0].length; i < match.index; i++) {
+      if (masked[i] === "(") depth++;
+      else if (masked[i] === ")") depth--;
+      if (depth === 0) return null;
+    }
+  }
+  const wrapped = `<SaaSProProvider>${code.slice(match.index, match.index + match[0].length)}</SaaSProProvider>`;
+  const edited = code.slice(0, match.index) + wrapped + code.slice(match.index + match[0].length);
+  return { path, code: addImport(edited, `import { SaaSProProvider } from ${quote}${plan.providerImport}${quote}${semi}`, newline), description: `import SaaSProProvider and wrap ${match[0]}` };
 }
 
 export async function run(args = process.argv.slice(2), root = process.cwd()) {
@@ -191,14 +363,16 @@ export async function run(args = process.argv.slice(2), root = process.cwd()) {
   if (options.help) { console.log(HELP); return; }
   const files = ["package.json", "pyproject.toml", "requirements.txt", "pnpm-lock.yaml", "yarn.lock", "bun.lock", "bun.lockb", "package-lock.json"].filter(file => existsSync(join(root, file)));
   const pkg = files.includes("package.json") ? readJson(join(root, "package.json")) : null;
-  const framework = detectFramework(pkg, files);
+  const paths = projectPaths(root);
+  const framework = detectFramework(pkg, [...files, ...paths]);
   const manager = detectPackageManager(files);
   console.log(`Detected: ${framework}; package manager: ${manager}`);
   const login = options.key ? { key: options.key, ingestUrl: `${options.host}/api/v1/ingest`, consoleUrl: `${options.host}/o` } : await deviceLogin(options.host, framework, options.open);
   const key = login.key;
   console.log(`Public key (shown once): ${key}`);
-  const paths = ["app/layout.tsx", "app/layout.jsx", "app/layout.js", "src/app/layout.tsx", "src/app/layout.jsx", "src/app/layout.js", "src/main.tsx", "src/main.jsx"].filter(path => existsSync(join(root, path)));
-  const plan = integrationPlan(framework, options.host, paths);
+  const managers = detectConsentManagers(pkg);
+  const consent = options.consent ?? (managers.length ? "pending" : null);
+  const plan = integrationPlan(framework, options.host, paths, consent);
   const envPath = join(root, plan.file);
   noSymlinks(root, plan.file);
   const env = mergeEnv(existsSync(envPath) ? readFileSync(envPath, "utf8") : "", { [plan.env]: key, SPM_HOST: options.host });
@@ -221,9 +395,22 @@ export async function run(args = process.argv.slice(2), root = process.cwd()) {
   writePlanned(root, plan.file, env, options);
   const ignored = existsSync(join(root, ".gitignore")) ? readFileSync(join(root, ".gitignore"), "utf8") : "";
   if (!ignored.split(/\r?\n/).some(line => line.trim() === plan.file || line.trim() === ".env*")) writePlanned(root, ".gitignore", `${ignored}${ignored.endsWith("\n") || !ignored ? "" : "\n"}${plan.file}\n`, options);
+  const setupReady = !plan.target || !existsSync(join(root, plan.target)) || readFileSync(join(root, plan.target), "utf8") === plan.code;
   if (plan.target && !existsSync(join(root, plan.target))) { writePlanned(root, plan.target, plan.code, options); console.log(plan.code); }
   else console.log(`${plan.target ? `Preserve existing ${plan.target}.` : "Add this initialization to your existing setup:"}\n${plan.code}`);
+  const edit = setupReady ? integrationEdit(root, plan, paths) : null;
+  if (edit) {
+    console.log(`${options.dryRun ? "Would edit" : "Edit"} ${edit.path}: ${edit.description}`);
+    writePlanned(root, edit.path, edit.code, options);
+  } else if (plan.wrap) console.log("Automatic wiring skipped: missing, existing or ambiguous integration. Existing application source is preserved.");
   console.log(plan.instructions);
+  if (managers.length) console.log(`Consent manager detected: ${managers.join(", ")}. Consent: ${consent}.`);
+  if (consent === "pending" || managers.length) {
+    console.log('Connect the consent manager analytics-accept callback AND its saved analytics choice to consent("granted"); connect analytics rejection/withdrawal to consent("revoked").');
+    if (["expo", "react-native"].includes(framework)) console.log('Use analytics.setConsent("granted") / analytics.setConsent("revoked") on the mobile client.');
+    else if (plan.packages.includes("@saaspro/react")) console.log('Inside a React component: const client = useSaaSProMax() (import from "@saaspro/react"); call client.consent("granted") on analytics acceptance and client.consent("revoked") on rejection or withdrawal, including the saved choice on startup.');
+    else console.log('Import { spm } from "@saaspro/browser" in your consent controls; call spm.consent("granted") on analytics acceptance and spm.consent("revoked") on rejection or withdrawal, after initialization, including the saved choice on startup.');
+  } else console.log('--consent pending holds events until the site’s consent controls call consent("granted").');
   for (const [path, content] of configs) { console.log(`Merge saaspro MCP endpoint ${options.host}/api/mcp into ${path}.`); writePlanned(root, path, content, options); }
   if (options.mcp) console.log("MCP uses separate browser OAuth approval. In Claude Code run /mcp; in Cursor open MCP settings to sign in.");
   if (options.dryRun) console.log("Dry run: no files, packages or verification events were changed.");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@saaspro/wizard",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Set up SaaS Pro Max with browser device approval.",
   "type": "module",
   "license": "MIT",