@saaspro/wizard 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,72 @@
-# Temporary Holding Version
+# @saaspro/wizard
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Node 18+ setup CLI with no runtime dependencies. Run in your project directory:
+
+```sh
+npx @saaspro/wizard
+curl -fsSL https://saaspro.dev/wizard.mjs | node --input-type=module
+```
+
+No stdin reads or terminal prompts. Confirm the terminal code in your browser,
+sign in with a passkey and choose your organization, application and environment.
+Approval requires keys.write and a fresh passkey. It creates a public key labelled
+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: --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 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
+initialization instructions, without writing SPM_INGEST_KEY. It still verifies the
+public key. Mobile storage, randomness, lifecycle and consent wiring remain
+explicit in the printed instructions. Review imports and consent before deployment.
+
+Hosted MCP is merged into .mcp.json for Claude Code and .cursor/mcp.json for Cursor.
+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 completing the printed steps.
+The public download is byte-identical to the packaged ESM source.

package/bin/saaspro-wizard.mjs

@@ -0,0 +1,428 @@
+#!/usr/bin/env node
+import { constants, generateKeyPairSync, privateDecrypt, randomUUID } from "node:crypto";
+import { execFileSync, spawn } from "node:child_process";
+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.2.0";
+const PUBLIC_KEY = /^spm_pub_(?:prod|stg|dev)_[A-Za-z0-9]{22}$/;
+const HELP = `SaaS Pro Max wizard
+
+Run in your project directory:
+  npx @saaspro/wizard
+  curl -fsSL https://saaspro.dev/wizard.mjs | node --input-type=module
+
+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.react) return deps.vite ? "vite-react" : "react";
+  if (files.includes("pyproject.toml") || files.includes("requirements.txt")) return "python";
+  return pkg ? "node" : "unknown";
+}
+
+export function detectPackageManager(files) {
+  if (files.includes("pnpm-lock.yaml")) return "pnpm";
+  if (files.includes("yarn.lock")) return "yarn";
+  if (files.includes("bun.lock") || files.includes("bun.lockb")) return "bun";
+  return "npm";
+}
+
+function object(value) { return value !== null && typeof value === "object" && !Array.isArray(value); }
+
+export function mergeMcpConfig(existing, endpoint, client = "claude") {
+  if (!object(existing) || (existing.mcpServers !== undefined && !object(existing.mcpServers))) throw new WizardError("MCP config must contain a JSON object and an object-valued mcpServers");
+  const servers = existing.mcpServers ?? {};
+  if (Object.hasOwn(servers, "saaspro")) {
+    if (!object(servers.saaspro) || servers.saaspro.url !== endpoint) throw new WizardError("The saaspro MCP entry already exists with different settings; merge it manually");
+    return existing;
+  }
+  return { ...existing, mcpServers: { ...servers, saaspro: client === "claude" ? { type: "http", url: endpoint } : { url: endpoint } } };
+}
+
+export function mergeEnv(existing, values) {
+  let result = existing;
+  for (const [name, value] of Object.entries(values)) {
+    const found = new RegExp(`^(?:export\\s+)?${name}\\s*=.*$`, "m").exec(result);
+    if (found) {
+      const old = found[0].slice(found[0].indexOf("=") + 1).trim().replace(/^(["'])(.*)\1$/, "$2");
+      if (old !== value) throw new WizardError(`${name} already exists with a different value; preserve it and review the new public key before replacing it`);
+      continue;
+    }
+    result += `${result && !result.endsWith("\n") ? "\n" : ""}${name}=${value}\n`;
+  }
+  return result;
+}
+
+export function parseFlags(args) {
+  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;
+    else if (flag === "--dry-run") options.dryRun = true;
+    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" || flag === "--consent") {
+      const value = args[++i];
+      if (!value || value.startsWith("--")) throw new WizardError(`${flag} requires a 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;
+  if (options.key && !PUBLIC_KEY.test(options.key)) throw new WizardError("--key requires a public ingest key; secret keys are never accepted");
+  return options;
+}
+
+async function post(url, body) {
+  const response = await fetch(url, { method: "POST", redirect: "error", headers: { "content-type": "application/json" }, body: JSON.stringify(body), signal: AbortSignal.timeout(15_000) });
+  let data;
+  try { data = await response.json(); } catch { throw new WizardError(`Invalid API response (HTTP ${response.status})`); }
+  if (!response.ok && !(response.status === 429 && data.status === "slow_down")) throw new WizardError(`Request failed (HTTP ${response.status}); check the host and console permissions`);
+  return data;
+}
+
+function openBrowser(url) {
+  const command = process.platform === "darwin" ? "open" : process.platform === "win32" ? "rundll32" : "xdg-open";
+  const args = process.platform === "win32" ? ["url.dll,FileProtocolHandler", url] : [url];
+  const child = spawn(command, args, { detached: true, stdio: "ignore" });
+  child.on("error", () => {});
+  child.unref();
+}
+
+async function deviceLogin(host, framework, open) {
+  const { publicKey, privateKey } = generateKeyPairSync("rsa", { modulusLength: 2048 });
+  const started = await post(`${host}/api/v1/wizard/device`, { publicKey: publicKey.export({ type: "spki", format: "pem" }), client: { name: "@saaspro/wizard", version: VERSION, framework } });
+  const verification = new URL(started.verificationUrl);
+  if (verification.origin !== host || verification.pathname !== "/device" || typeof started.deviceCode !== "string" || !/^[A-HJ-NP-Z2-9]{4}-[A-HJ-NP-Z2-9]{4}$/.test(started.userCode)) throw new WizardError("Invalid device approval response");
+  console.log(`Confirm code ${started.userCode} in your browser:\n${verification.href}\nChoose your organization, application and environment, then approve.`);
+  if (open) openBrowser(verification.href);
+  const deadline = Date.now() + Math.min(Number(started.expiresIn) || 600, 600) * 1000;
+  let interval = Math.max(3, Number(started.interval) || 3);
+  while (Date.now() < deadline) {
+    await new Promise(resolve => setTimeout(resolve, interval * 1000));
+    const token = await post(`${host}/api/v1/wizard/device/token`, { deviceCode: started.deviceCode });
+    if (token.status === "pending") continue;
+    if (token.status === "slow_down") { interval = Math.max(interval + 1, Number(token.interval) || 3); continue; }
+    if (token.status !== "approved") throw new WizardError(`Device approval ${["denied", "expired", "consumed"].includes(token.status) ? token.status : "failed"}; start the wizard again`);
+    const key = privateDecrypt({ key: privateKey, padding: constants.RSA_PKCS1_OAEP_PADDING, oaepHash: "sha256" }, Buffer.from(token.ciphertext, "base64")).toString();
+    if (!PUBLIC_KEY.test(key) || new URL(token.ingestUrl).origin !== host || new URL(token.consoleUrl).origin !== host) throw new WizardError("Invalid device token response");
+    return { ...token, key };
+  }
+  throw new WizardError("Device approval expired; start the wizard again");
+}
+
+function readJson(path) { return JSON.parse(readFileSync(path, "utf8")); }
+
+function noSymlinks(root, relative) {
+  let path = root;
+  for (const part of relative.split(/[\\/]/)) {
+    path = join(path, part);
+    try {
+      if (lstatSync(path).isSymbolicLink()) throw new WizardError(`Refusing to write through a symbolic link: ${relative}`);
+    } catch (error) { if (error.code !== "ENOENT") throw error; }
+  }
+}
+
+function writePlanned(root, path, text, options) {
+  noSymlinks(root, path);
+  console.log(`${options.dryRun ? "Would write" : "Write"} ${path}`);
+  if (!options.dryRun) {
+    mkdirSync(dirname(join(root, path)), { recursive: true });
+    writeFileSync(join(root, path), text, { mode: 0o600 });
+  }
+}
+
+function installPackages(manager, packages, options) {
+  if (!packages.length) return;
+  const args = [manager === "npm" ? "install" : "add", ...packages];
+  console.log(`${options.dryRun || !options.install ? "Run manually:" : "Run:"} ${manager} ${args.join(" ")}`);
+  if (options.install && !options.dryRun) execFileSync(manager, args, { stdio: ["ignore", "inherit", "inherit"] });
+}
+
+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 (["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${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") {
+    const code = `import { randomUUID } from "node:crypto";\nimport { SaaSProNative } from "@saaspro/node/native";\n\nexport const spm = new SaaSProNative({ key: process.env.SPM_PUBLIC_KEY, host: ${JSON.stringify(host)}, randomUUID });\nspm.track({ event: "app.started", properties: { source: "wizard" } });\n// Call spm.shutdown() from your application's existing graceful shutdown handler.\n`;
+    return { packages: ["@saaspro/node"], env: "SPM_PUBLIC_KEY", file: ".env", target: "saaspro-init.mjs", code, instructions: "Import ./saaspro-init.mjs from your entry point. Load .env with your existing environment loader before this import. The public-key native transport supports manual events only; do not add IP or user-agent context." };
+  }
+  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}"${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()) {
+  const options = parseFlags(args);
+  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 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 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 });
+  const configs = [];
+  if (options.mcp) {
+    for (const [path, client] of [[".mcp.json", "claude"], [".cursor/mcp.json", "cursor"]]) {
+      noSymlinks(root, path);
+      const existing = existsSync(join(root, path)) ? readJson(join(root, path)) : {};
+      const merged = mergeMcpConfig(existing, `${options.host}/api/mcp`, client);
+      configs.push([path, `${JSON.stringify(merged, null, 2)}\n`]);
+    }
+  }
+  installPackages(manager, plan.packages, options);
+  if (framework === "python" && options.install) {
+    const args = ["-m", "pip", "install", `${options.host}/downloads/saaspro-0.1.0.tar.gz`];
+    console.log(`${options.dryRun ? "Would run:" : "Run:"} python ${args.join(" ")}`);
+    if (!options.dryRun) execFileSync("python", args, { stdio: ["ignore", "inherit", "inherit"] });
+  }
+  console.log(`Set ${plan.env}=<public key shown above> and SPM_HOST=${options.host} in ${plan.file}.`);
+  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.");
+  else {
+    const result = await post(login.ingestUrl, { key, sentAt: new Date().toISOString(), sdk: { name: "@saaspro/wizard", version: VERSION }, events: [{ id: randomUUID(), type: "track", timestamp: new Date().toISOString(), anonymousId: randomUUID(), name: "spm.wizard.verified", properties: { source: "wizard", framework } }] });
+    if (result.accepted !== 1) throw new WizardError("Verification event was not accepted; inspect the environment's Install receipt");
+    console.log("Verification event accepted: spm.wizard.verified. Review initialization and consent wiring before deploying your app.");
+  }
+  console.log(`Setup ${options.dryRun ? "preview" : "files"} ready for ${framework}.\nConsole: ${login.consoleUrl}`);
+}
+
+const piped = import.meta.url.endsWith("/[eval1]");
+if (piped || (process.argv[1] && import.meta.url === pathToFileURL(realpathSync(resolve(process.argv[1]))).href)) {
+  run(piped && process.argv[1] !== "-" ? process.argv.slice(1) : process.argv.slice(2)).catch(error => { console.error(error instanceof WizardError ? error.message : "Wizard failed. Check the host, device approval, existing configuration and package manager. Existing files are preserved when configuration conflicts; review any earlier completed steps before retrying."); process.exitCode = 1; });
+}

package/package.json

@@ -1,6 +1,16 @@
 {
   "name": "@saaspro/wizard",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Set up SaaS Pro Max with browser device approval.",
+  "type": "module",
+  "license": "MIT",
+  "engines": { "node": ">=18" },
+  "bin": { "saaspro-wizard": "./bin/saaspro-wizard.mjs" },
+  "files": ["bin", "README.md"],
+  "publishConfig": { "access": "public" },
+  "scripts": {
+    "build": "node --check bin/saaspro-wizard.mjs",
+    "lint": "node --check bin/saaspro-wizard.mjs",
+    "typecheck": "node --check bin/saaspro-wizard.mjs"
+  }
+}