@saaspro/wizard 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,39 @@
-# 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: --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.
+
+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 importing the setup.
+The public download is byte-identical to the packaged ESM source.

package/bin/saaspro-wizard.mjs

@@ -0,0 +1,241 @@
+#!/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 { pathToFileURL } from "node:url";
+
+class WizardError extends Error {}
+
+const VERSION = "0.1.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
+  --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
+
+No terminal prompts or stdin reads. Only public keys are accepted.
+`;
+
+export function detectFramework(pkg, files = []) {
+  const deps = { ...pkg?.devDependencies, ...pkg?.dependencies };
+  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";
+}
+
+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, 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") {
+      const value = args[++i];
+      if (!value || value.startsWith("--")) throw new WizardError(`${flag} requires a value`);
+      options[flag === "--host" ? "host" : "key"] = value;
+    } else throw new WizardError("Unknown option. Use --help for supported flags.");
+  }
+  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 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.` };
+  }
+  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 (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`;
+    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}"></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." };
+}
+
+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 framework = detectFramework(pkg, files);
+  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 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);
+  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}`);
+  console.log(plan.instructions);
+  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.1.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"
+  }
+}