@gurulu/cli 1.0.0 → 1.0.4

package/dist/bin.js

@@ -25055,8 +25055,332 @@ var doctorCmd = defineCommand({
 });
 
 // src/commands/init.ts
-import { existsSync as existsSync4, mkdirSync as mkdirSync2, writeFileSync as writeFileSync3 } from "node:fs";
-import { dirname as dirname2 } from "node:path";
+import { existsSync as existsSync5, mkdirSync as mkdirSync2, writeFileSync as writeFileSync3 } from "node:fs";
+import { dirname as dirname3 } from "node:path";
+
+// src/lib/detect.ts
+import { existsSync as existsSync4, readFileSync as readFileSync4 } from "node:fs";
+import { dirname as dirname2, join as join4, parse } from "node:path";
+function readPackageJson(dir) {
+  const p = join4(dir, "package.json");
+  if (!existsSync4(p))
+    return null;
+  try {
+    return JSON.parse(readFileSync4(p, "utf8"));
+  } catch {
+    return null;
+  }
+}
+function hasDep(pkg, name) {
+  if (!pkg)
+    return false;
+  return Boolean(pkg.dependencies?.[name] ?? pkg.devDependencies?.[name]);
+}
+function detectPackageManager(dir) {
+  const root = parse(dir).root;
+  let cur = dir;
+  for (let i2 = 0;i2 < 6; i2++) {
+    if (existsSync4(join4(cur, "bun.lock")) || existsSync4(join4(cur, "bun.lockb")))
+      return "bun";
+    if (existsSync4(join4(cur, "pnpm-lock.yaml")))
+      return "pnpm";
+    if (existsSync4(join4(cur, "yarn.lock")))
+      return "yarn";
+    if (existsSync4(join4(cur, "package-lock.json")))
+      return "npm";
+    if (cur === root)
+      break;
+    const parent = dirname2(cur);
+    if (parent === cur)
+      break;
+    cur = parent;
+  }
+  return "npm";
+}
+function detectFramework(pkg, dir) {
+  if (!pkg)
+    return "unknown";
+  if (hasDep(pkg, "next"))
+    return "next";
+  if (hasDep(pkg, "nuxt"))
+    return "nuxt";
+  if (hasDep(pkg, "@sveltejs/kit") || hasDep(pkg, "svelte"))
+    return "svelte";
+  if (hasDep(pkg, "astro"))
+    return "astro";
+  if (hasDep(pkg, "vite") && (hasDep(pkg, "vue") || hasDep(pkg, "react")))
+    return "vite";
+  if (hasDep(pkg, "vue"))
+    return "vue";
+  if (hasDep(pkg, "react"))
+    return "react";
+  if (hasDep(pkg, "hono"))
+    return "hono";
+  if (hasDep(pkg, "fastify"))
+    return "fastify";
+  if (hasDep(pkg, "express"))
+    return "express";
+  if (hasDep(pkg, "koa"))
+    return "koa";
+  if (existsSync4(join4(dir, "server.js")) || existsSync4(join4(dir, "server.ts")))
+    return "node-server";
+  return "unknown";
+}
+function frameworkRuntime(fw) {
+  switch (fw) {
+    case "next":
+    case "react":
+    case "vue":
+    case "nuxt":
+    case "svelte":
+    case "astro":
+    case "vite":
+      return "browser";
+    case "express":
+    case "fastify":
+    case "hono":
+    case "koa":
+    case "node-server":
+      return "node";
+    default:
+      return "unknown";
+  }
+}
+function detectProject(dir) {
+  const pkg = readPackageJson(dir);
+  const framework = detectFramework(pkg, dir);
+  return {
+    dir,
+    hasPackageJson: pkg !== null,
+    framework,
+    runtime: frameworkRuntime(framework),
+    packageManager: detectPackageManager(dir),
+    packageJson: pkg
+  };
+}
+
+// src/lib/exec-install.ts
+import { spawn } from "node:child_process";
+async function execInstall(plan, opts) {
+  const [bin, ...args] = plan.installCommand.split(/\s+/);
+  if (!bin) {
+    return {
+      ok: false,
+      exitCode: null,
+      durationMs: 0,
+      command: plan.installCommand,
+      stderr: "empty install command"
+    };
+  }
+  const started = Date.now();
+  return new Promise((resolve) => {
+    const child = spawn(bin, args, {
+      cwd: opts.cwd,
+      stdio: opts.silent ? ["ignore", "pipe", "pipe"] : ["inherit", "inherit", "pipe"],
+      shell: process.platform === "win32"
+    });
+    let stderr = "";
+    if (child.stderr) {
+      child.stderr.on("data", (chunk) => {
+        const text = chunk.toString("utf8");
+        stderr += text;
+        if (!opts.silent) {
+          process.stderr.write(text);
+        }
+      });
+    }
+    const timeout = setTimeout(() => {
+      child.kill("SIGTERM");
+    }, opts.timeoutMs ?? 120000);
+    child.on("error", (err) => {
+      clearTimeout(timeout);
+      resolve({
+        ok: false,
+        exitCode: null,
+        durationMs: Date.now() - started,
+        command: plan.installCommand,
+        stderr: err.message
+      });
+    });
+    child.on("close", (code) => {
+      clearTimeout(timeout);
+      resolve({
+        ok: code === 0,
+        exitCode: code,
+        durationMs: Date.now() - started,
+        command: plan.installCommand,
+        ...stderr ? { stderr } : {}
+      });
+    });
+  });
+}
+
+// src/lib/install-plan.ts
+function installCmdFor(pm, pkg) {
+  switch (pm) {
+    case "bun":
+      return `bun add ${pkg}`;
+    case "pnpm":
+      return `pnpm add ${pkg}`;
+    case "yarn":
+      return `yarn add ${pkg}`;
+    default:
+      return `npm install ${pkg}`;
+  }
+}
+function sdkFor(framework) {
+  switch (framework) {
+    case "express":
+    case "fastify":
+    case "hono":
+    case "koa":
+    case "node-server":
+      return "@gurulu/node";
+    default:
+      return "@gurulu/web";
+  }
+}
+function snippetWeb(workspaceKey) {
+  return `import gurulu from '@gurulu/web';
+
+gurulu.init({
+  workspaceKey: process.env.NEXT_PUBLIC_GURULU_WORKSPACE ?? '${workspaceKey}',
+  endpoint: process.env.NEXT_PUBLIC_GURULU_ENDPOINT, // optional, defaults to https://ingest.gurulu.io
+});`;
+}
+function snippetNext(workspaceKey) {
+  return `// src/app/gurulu-provider.tsx
+'use client';
+import { useEffect } from 'react';
+import gurulu from '@gurulu/web';
+
+export function GuruluProvider({ children }: { children: React.ReactNode }) {
+  useEffect(() => {
+    gurulu.init({
+      workspaceKey: process.env.NEXT_PUBLIC_GURULU_WORKSPACE ?? '${workspaceKey}',
+      endpoint: process.env.NEXT_PUBLIC_GURULU_ENDPOINT,
+    });
+  }, []);
+  return <>{children}</>;
+}
+
+// Then wrap your root in app/layout.tsx:
+//   <GuruluProvider>{children}</GuruluProvider>`;
+}
+function snippetNode(workspaceKey) {
+  return `import { createGurulu } from '@gurulu/node';
+
+const gurulu = createGurulu({
+  workspaceKey: process.env.GURULU_WORKSPACE ?? '${workspaceKey}',
+  apiKey: process.env.GURULU_API_KEY,
+  endpoint: process.env.GURULU_ENDPOINT, // optional, defaults to https://ingest.gurulu.io
+});
+
+// In your handler:
+await gurulu.track('purchase_completed', {
+  user_id: 'u_42',
+  order_id: 'o_123',
+  total: 49.99,
+});`;
+}
+function snippetExpress(workspaceKey) {
+  return `import express from 'express';
+import { guruluMiddleware } from '@gurulu/node/middleware/express';
+
+const app = express();
+app.use(guruluMiddleware({
+  workspaceKey: process.env.GURULU_WORKSPACE ?? '${workspaceKey}',
+  apiKey: process.env.GURULU_API_KEY,
+  endpoint: process.env.GURULU_ENDPOINT,
+}));`;
+}
+function snippetHono(workspaceKey) {
+  return `import { Hono } from 'hono';
+import { createGurulu } from '@gurulu/node';
+
+const gurulu = createGurulu({
+  workspaceKey: process.env.GURULU_WORKSPACE ?? '${workspaceKey}',
+  apiKey: process.env.GURULU_API_KEY,
+  endpoint: process.env.GURULU_ENDPOINT,
+});
+
+const app = new Hono();
+app.post('/checkout/complete', async (c) => {
+  await gurulu.track('purchase_completed', await c.req.json());
+  return c.json({ ok: true });
+});`;
+}
+function placementHintFor(framework) {
+  switch (framework) {
+    case "next":
+      return "Add the GuruluProvider to app/layout.tsx (App Router) or pages/_app.tsx (Pages Router) and wrap children.";
+    case "nuxt":
+      return "Add to plugins/gurulu.client.ts and register in nuxt.config.ts.";
+    case "svelte":
+      return "Add to src/routes/+layout.svelte inside onMount().";
+    case "astro":
+      return "Add to src/layouts/Base.astro inside a <script> tag (or use a hydrated component).";
+    case "vite":
+    case "react":
+    case "vue":
+      return "Add to src/main.ts (or your entry file) before mounting the app.";
+    case "express":
+      return "Register guruluMiddleware before your route handlers in your app entry file.";
+    case "fastify":
+      return "Register the Gurulu plugin via fastify.register() before route definitions.";
+    case "hono":
+      return "Initialize the SDK at the top of your app file; call track() inside route handlers.";
+    case "koa":
+      return "Add as Koa middleware (app.use) before your routes.";
+    case "node-server":
+      return "Initialize the SDK at startup; call track() from your handlers.";
+    default:
+      return "Initialize the SDK at your app entry point.";
+  }
+}
+function initSnippetFor(framework, sdk, workspaceKey) {
+  if (sdk === "@gurulu/node") {
+    if (framework === "express")
+      return snippetExpress(workspaceKey);
+    if (framework === "hono")
+      return snippetHono(workspaceKey);
+    return snippetNode(workspaceKey);
+  }
+  if (framework === "next")
+    return snippetNext(workspaceKey);
+  return snippetWeb(workspaceKey);
+}
+function envKeysFor(sdk, framework) {
+  if (sdk === "@gurulu/node") {
+    return [
+      { key: "GURULU_WORKSPACE", example: "pk_live_xxxxxxxxxxxx", required: true },
+      { key: "GURULU_API_KEY", example: "sk_live_xxxxxxxxxxxx", required: true },
+      {
+        key: "GURULU_ENDPOINT",
+        example: "https://ingest.gurulu.io",
+        required: false
+      }
+    ];
+  }
+  const prefix = framework === "next" ? "NEXT_PUBLIC_GURULU" : "VITE_GURULU";
+  return [
+    { key: `${prefix}_WORKSPACE`, example: "pk_live_xxxxxxxxxxxx", required: false },
+    { key: `${prefix}_ENDPOINT`, example: "https://ingest.gurulu.io", required: false }
+  ];
+}
+function buildInstallPlan(detected, ctx = {}) {
+  const sdk = sdkFor(detected.framework);
+  const workspaceKey = ctx.writeKey ?? "pk_xxxxxxxxxxxx";
+  return {
+    sdk,
+    packageManager: detected.packageManager,
+    installCommand: installCmdFor(detected.packageManager, sdk),
+    initSnippet: initSnippetFor(detected.framework, sdk, workspaceKey),
+    envKeys: envKeysFor(sdk, detected.framework),
+    placementHint: placementHintFor(detected.framework),
+    framework: detected.framework
+  };
+}
 
 // src/commands/pull.ts
 import { writeFileSync as writeFileSync2 } from "node:fs";
@@ -25206,7 +25530,9 @@ var initCmd = defineCommand({
   args: {
     workspace: { type: "string", description: "Workspace ID (uuid)" },
     endpoint: { type: "string", description: "API endpoint", default: DEFAULT_ENDPOINT },
-    sdk: { type: "string", description: "SDK preference (web|node|react)", default: "web" },
+    sdk: { type: "string", description: "SDK preference (web|node|auto)", default: "auto" },
+    "write-key": { type: "string", description: "Workspace write key (pk_xxx) for init snippet" },
+    "no-install": { type: "boolean", description: "Skip SDK install (config files only)" },
     "no-pull": { type: "boolean", description: "Skip first registry pull" },
     force: { type: "boolean", description: "Overwrite existing config" }
   },
@@ -25222,40 +25548,63 @@ var initCmd = defineCommand({
       console.error("[gurulu] --workspace <uuid> required (workspace ID from dashboard)");
       process.exit(1);
     }
-    const sdk = String(args.sdk ?? "web");
-    if (!["web", "node", "react"].includes(sdk)) {
-      console.error(`[gurulu] invalid --sdk: ${sdk} (use web|node|react)`);
+    const sdkArg = String(args.sdk ?? "auto");
+    if (!["web", "node", "auto"].includes(sdkArg)) {
+      console.error(`[gurulu] invalid --sdk: ${sdkArg} (use web|node|auto)`);
       process.exit(1);
     }
+    const detected = detectProject(cwd);
+    const writeKey = String(args["write-key"] ?? "").trim() || "pk_xxxxxxxxxxxx";
+    const plan = buildInstallPlan(detected, { writeKey, workspaceId });
+    const effectiveSdkPref = sdkArg === "auto" ? plan.sdk === "@gurulu/node" ? "node" : "web" : sdkArg;
     const config = {
       workspace_id: workspaceId,
       endpoint: String(args.endpoint),
-      sdk_preference: sdk,
+      sdk_preference: effectiveSdkPref,
       registry_path: ".gurulu/event-registry.json",
       generated_path: ".gurulu/generated.d.ts",
       manifest_lock_path: ".gurulu/manifest.lock",
       auto_pull_on_init: true
     };
     writeProjectConfig(config, cwd);
-    const dir = dirname2(projectConfigPath(cwd));
-    if (!existsSync4(dir))
+    const dir = dirname3(projectConfigPath(cwd));
+    if (!existsSync5(dir))
       mkdirSync2(dir, { recursive: true });
-    if (!existsSync4(projectRegistryPath(cwd))) {
+    if (!existsSync5(projectRegistryPath(cwd))) {
       writeFileSync3(projectRegistryPath(cwd), `{}
 `, "utf-8");
     }
-    if (!existsSync4(projectGeneratedPath(cwd))) {
+    if (!existsSync5(projectGeneratedPath(cwd))) {
       writeFileSync3(projectGeneratedPath(cwd), "// Run `gurulu pull` to populate typed events.\n", "utf-8");
     }
-    if (!existsSync4(projectManifestLockPath(cwd))) {
+    if (!existsSync5(projectManifestLockPath(cwd))) {
       writeFileSync3(projectManifestLockPath(cwd), `0.0.0
 `, "utf-8");
     }
     console.log(`[gurulu] initialized ${projectConfigPath(cwd)}`);
+    if (args["no-install"]) {
+      console.log(`[gurulu] skipping SDK install (--no-install).`);
+      console.log(`         manual: ${plan.installCommand}`);
+    } else if (!detected.hasPackageJson) {
+      console.log(`[gurulu] no package.json found in ${cwd} — skipping SDK install.`);
+      console.log(`         use the script tag: <script src="https://cdn.gurulu.io/t.js" data-workspace="${writeKey}"></script>`);
+    } else {
+      console.log(`[gurulu] detected ${detected.framework} (${detected.packageManager}) — installing ${plan.sdk}…`);
+      const result = await execInstall(plan, { cwd });
+      if (result.ok) {
+        console.log(`[gurulu] ${plan.sdk} installed (${(result.durationMs / 1000).toFixed(1)}s).`);
+      } else {
+        console.warn(`[gurulu] install failed (exit ${result.exitCode ?? "n/a"}) — run manually: ${plan.installCommand}`);
+      }
+    }
+    console.log("");
     console.log("[gurulu] next steps:");
     console.log("  1. gurulu login            — authenticate (or store API key)");
     console.log("  2. gurulu pull             — fetch registry + code-gen");
-    console.log("  3. import { GuruluEvents } — use generated types");
+    console.log(`  3. ${plan.placementHint}`);
+    console.log("");
+    console.log("[gurulu] init snippet:");
+    console.log(plan.initSnippet);
     if (!args["no-pull"]) {
       try {
         await runPull({ cwd });
@@ -25365,7 +25714,7 @@ var pushCmd = defineCommand({
 });
 
 // src/index.ts
-var VERSION = "1.0.0";
+var VERSION = "1.0.4";
 var mcpCmd = defineCommand({
   meta: {
     name: "mcp",

package/dist/commands/init.d.ts

@@ -13,6 +13,14 @@ export declare const initCmd: import("citty").CommandDef<{
         description: string;
         default: string;
     };
+    'write-key': {
+        type: "string";
+        description: string;
+    };
+    'no-install': {
+        type: "boolean";
+        description: string;
+    };
     'no-pull': {
         type: "boolean";
         description: string;

package/dist/commands/init.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/commands/init.ts"],"names":[],"mappings":"AA4BA,eAAO,MAAM,OAAO;;;;;;;;;;;;;;;;;;;;;;;EA0FlB,CAAC"}
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/commands/init.ts"],"names":[],"mappings":"AAmCA,eAAO,MAAM,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAgJlB,CAAC"}

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export declare const VERSION = "1.0.0";
+export declare const VERSION = "1.0.4";
 declare const mainCmd: import("citty").CommandDef<import("citty").ArgsDef>;
 export default mainCmd;
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -24632,8 +24632,332 @@ var doctorCmd = defineCommand({
 });
 
 // src/commands/init.ts
-import { existsSync as existsSync4, mkdirSync as mkdirSync2, writeFileSync as writeFileSync3 } from "node:fs";
-import { dirname as dirname2 } from "node:path";
+import { existsSync as existsSync5, mkdirSync as mkdirSync2, writeFileSync as writeFileSync3 } from "node:fs";
+import { dirname as dirname3 } from "node:path";
+
+// src/lib/detect.ts
+import { existsSync as existsSync4, readFileSync as readFileSync4 } from "node:fs";
+import { dirname as dirname2, join as join4, parse } from "node:path";
+function readPackageJson(dir) {
+  const p = join4(dir, "package.json");
+  if (!existsSync4(p))
+    return null;
+  try {
+    return JSON.parse(readFileSync4(p, "utf8"));
+  } catch {
+    return null;
+  }
+}
+function hasDep(pkg, name) {
+  if (!pkg)
+    return false;
+  return Boolean(pkg.dependencies?.[name] ?? pkg.devDependencies?.[name]);
+}
+function detectPackageManager(dir) {
+  const root = parse(dir).root;
+  let cur = dir;
+  for (let i2 = 0;i2 < 6; i2++) {
+    if (existsSync4(join4(cur, "bun.lock")) || existsSync4(join4(cur, "bun.lockb")))
+      return "bun";
+    if (existsSync4(join4(cur, "pnpm-lock.yaml")))
+      return "pnpm";
+    if (existsSync4(join4(cur, "yarn.lock")))
+      return "yarn";
+    if (existsSync4(join4(cur, "package-lock.json")))
+      return "npm";
+    if (cur === root)
+      break;
+    const parent = dirname2(cur);
+    if (parent === cur)
+      break;
+    cur = parent;
+  }
+  return "npm";
+}
+function detectFramework(pkg, dir) {
+  if (!pkg)
+    return "unknown";
+  if (hasDep(pkg, "next"))
+    return "next";
+  if (hasDep(pkg, "nuxt"))
+    return "nuxt";
+  if (hasDep(pkg, "@sveltejs/kit") || hasDep(pkg, "svelte"))
+    return "svelte";
+  if (hasDep(pkg, "astro"))
+    return "astro";
+  if (hasDep(pkg, "vite") && (hasDep(pkg, "vue") || hasDep(pkg, "react")))
+    return "vite";
+  if (hasDep(pkg, "vue"))
+    return "vue";
+  if (hasDep(pkg, "react"))
+    return "react";
+  if (hasDep(pkg, "hono"))
+    return "hono";
+  if (hasDep(pkg, "fastify"))
+    return "fastify";
+  if (hasDep(pkg, "express"))
+    return "express";
+  if (hasDep(pkg, "koa"))
+    return "koa";
+  if (existsSync4(join4(dir, "server.js")) || existsSync4(join4(dir, "server.ts")))
+    return "node-server";
+  return "unknown";
+}
+function frameworkRuntime(fw) {
+  switch (fw) {
+    case "next":
+    case "react":
+    case "vue":
+    case "nuxt":
+    case "svelte":
+    case "astro":
+    case "vite":
+      return "browser";
+    case "express":
+    case "fastify":
+    case "hono":
+    case "koa":
+    case "node-server":
+      return "node";
+    default:
+      return "unknown";
+  }
+}
+function detectProject(dir) {
+  const pkg = readPackageJson(dir);
+  const framework = detectFramework(pkg, dir);
+  return {
+    dir,
+    hasPackageJson: pkg !== null,
+    framework,
+    runtime: frameworkRuntime(framework),
+    packageManager: detectPackageManager(dir),
+    packageJson: pkg
+  };
+}
+
+// src/lib/exec-install.ts
+import { spawn } from "node:child_process";
+async function execInstall(plan, opts) {
+  const [bin, ...args] = plan.installCommand.split(/\s+/);
+  if (!bin) {
+    return {
+      ok: false,
+      exitCode: null,
+      durationMs: 0,
+      command: plan.installCommand,
+      stderr: "empty install command"
+    };
+  }
+  const started = Date.now();
+  return new Promise((resolve) => {
+    const child = spawn(bin, args, {
+      cwd: opts.cwd,
+      stdio: opts.silent ? ["ignore", "pipe", "pipe"] : ["inherit", "inherit", "pipe"],
+      shell: process.platform === "win32"
+    });
+    let stderr = "";
+    if (child.stderr) {
+      child.stderr.on("data", (chunk) => {
+        const text = chunk.toString("utf8");
+        stderr += text;
+        if (!opts.silent) {
+          process.stderr.write(text);
+        }
+      });
+    }
+    const timeout = setTimeout(() => {
+      child.kill("SIGTERM");
+    }, opts.timeoutMs ?? 120000);
+    child.on("error", (err) => {
+      clearTimeout(timeout);
+      resolve({
+        ok: false,
+        exitCode: null,
+        durationMs: Date.now() - started,
+        command: plan.installCommand,
+        stderr: err.message
+      });
+    });
+    child.on("close", (code) => {
+      clearTimeout(timeout);
+      resolve({
+        ok: code === 0,
+        exitCode: code,
+        durationMs: Date.now() - started,
+        command: plan.installCommand,
+        ...stderr ? { stderr } : {}
+      });
+    });
+  });
+}
+
+// src/lib/install-plan.ts
+function installCmdFor(pm, pkg) {
+  switch (pm) {
+    case "bun":
+      return `bun add ${pkg}`;
+    case "pnpm":
+      return `pnpm add ${pkg}`;
+    case "yarn":
+      return `yarn add ${pkg}`;
+    default:
+      return `npm install ${pkg}`;
+  }
+}
+function sdkFor(framework) {
+  switch (framework) {
+    case "express":
+    case "fastify":
+    case "hono":
+    case "koa":
+    case "node-server":
+      return "@gurulu/node";
+    default:
+      return "@gurulu/web";
+  }
+}
+function snippetWeb(workspaceKey) {
+  return `import gurulu from '@gurulu/web';
+
+gurulu.init({
+  workspaceKey: process.env.NEXT_PUBLIC_GURULU_WORKSPACE ?? '${workspaceKey}',
+  endpoint: process.env.NEXT_PUBLIC_GURULU_ENDPOINT, // optional, defaults to https://ingest.gurulu.io
+});`;
+}
+function snippetNext(workspaceKey) {
+  return `// src/app/gurulu-provider.tsx
+'use client';
+import { useEffect } from 'react';
+import gurulu from '@gurulu/web';
+
+export function GuruluProvider({ children }: { children: React.ReactNode }) {
+  useEffect(() => {
+    gurulu.init({
+      workspaceKey: process.env.NEXT_PUBLIC_GURULU_WORKSPACE ?? '${workspaceKey}',
+      endpoint: process.env.NEXT_PUBLIC_GURULU_ENDPOINT,
+    });
+  }, []);
+  return <>{children}</>;
+}
+
+// Then wrap your root in app/layout.tsx:
+//   <GuruluProvider>{children}</GuruluProvider>`;
+}
+function snippetNode(workspaceKey) {
+  return `import { createGurulu } from '@gurulu/node';
+
+const gurulu = createGurulu({
+  workspaceKey: process.env.GURULU_WORKSPACE ?? '${workspaceKey}',
+  apiKey: process.env.GURULU_API_KEY,
+  endpoint: process.env.GURULU_ENDPOINT, // optional, defaults to https://ingest.gurulu.io
+});
+
+// In your handler:
+await gurulu.track('purchase_completed', {
+  user_id: 'u_42',
+  order_id: 'o_123',
+  total: 49.99,
+});`;
+}
+function snippetExpress(workspaceKey) {
+  return `import express from 'express';
+import { guruluMiddleware } from '@gurulu/node/middleware/express';
+
+const app = express();
+app.use(guruluMiddleware({
+  workspaceKey: process.env.GURULU_WORKSPACE ?? '${workspaceKey}',
+  apiKey: process.env.GURULU_API_KEY,
+  endpoint: process.env.GURULU_ENDPOINT,
+}));`;
+}
+function snippetHono(workspaceKey) {
+  return `import { Hono } from 'hono';
+import { createGurulu } from '@gurulu/node';
+
+const gurulu = createGurulu({
+  workspaceKey: process.env.GURULU_WORKSPACE ?? '${workspaceKey}',
+  apiKey: process.env.GURULU_API_KEY,
+  endpoint: process.env.GURULU_ENDPOINT,
+});
+
+const app = new Hono();
+app.post('/checkout/complete', async (c) => {
+  await gurulu.track('purchase_completed', await c.req.json());
+  return c.json({ ok: true });
+});`;
+}
+function placementHintFor(framework) {
+  switch (framework) {
+    case "next":
+      return "Add the GuruluProvider to app/layout.tsx (App Router) or pages/_app.tsx (Pages Router) and wrap children.";
+    case "nuxt":
+      return "Add to plugins/gurulu.client.ts and register in nuxt.config.ts.";
+    case "svelte":
+      return "Add to src/routes/+layout.svelte inside onMount().";
+    case "astro":
+      return "Add to src/layouts/Base.astro inside a <script> tag (or use a hydrated component).";
+    case "vite":
+    case "react":
+    case "vue":
+      return "Add to src/main.ts (or your entry file) before mounting the app.";
+    case "express":
+      return "Register guruluMiddleware before your route handlers in your app entry file.";
+    case "fastify":
+      return "Register the Gurulu plugin via fastify.register() before route definitions.";
+    case "hono":
+      return "Initialize the SDK at the top of your app file; call track() inside route handlers.";
+    case "koa":
+      return "Add as Koa middleware (app.use) before your routes.";
+    case "node-server":
+      return "Initialize the SDK at startup; call track() from your handlers.";
+    default:
+      return "Initialize the SDK at your app entry point.";
+  }
+}
+function initSnippetFor(framework, sdk, workspaceKey) {
+  if (sdk === "@gurulu/node") {
+    if (framework === "express")
+      return snippetExpress(workspaceKey);
+    if (framework === "hono")
+      return snippetHono(workspaceKey);
+    return snippetNode(workspaceKey);
+  }
+  if (framework === "next")
+    return snippetNext(workspaceKey);
+  return snippetWeb(workspaceKey);
+}
+function envKeysFor(sdk, framework) {
+  if (sdk === "@gurulu/node") {
+    return [
+      { key: "GURULU_WORKSPACE", example: "pk_live_xxxxxxxxxxxx", required: true },
+      { key: "GURULU_API_KEY", example: "sk_live_xxxxxxxxxxxx", required: true },
+      {
+        key: "GURULU_ENDPOINT",
+        example: "https://ingest.gurulu.io",
+        required: false
+      }
+    ];
+  }
+  const prefix = framework === "next" ? "NEXT_PUBLIC_GURULU" : "VITE_GURULU";
+  return [
+    { key: `${prefix}_WORKSPACE`, example: "pk_live_xxxxxxxxxxxx", required: false },
+    { key: `${prefix}_ENDPOINT`, example: "https://ingest.gurulu.io", required: false }
+  ];
+}
+function buildInstallPlan(detected, ctx = {}) {
+  const sdk = sdkFor(detected.framework);
+  const workspaceKey = ctx.writeKey ?? "pk_xxxxxxxxxxxx";
+  return {
+    sdk,
+    packageManager: detected.packageManager,
+    installCommand: installCmdFor(detected.packageManager, sdk),
+    initSnippet: initSnippetFor(detected.framework, sdk, workspaceKey),
+    envKeys: envKeysFor(sdk, detected.framework),
+    placementHint: placementHintFor(detected.framework),
+    framework: detected.framework
+  };
+}
 
 // src/commands/pull.ts
 import { writeFileSync as writeFileSync2 } from "node:fs";
@@ -24783,7 +25107,9 @@ var initCmd = defineCommand({
   args: {
     workspace: { type: "string", description: "Workspace ID (uuid)" },
     endpoint: { type: "string", description: "API endpoint", default: DEFAULT_ENDPOINT },
-    sdk: { type: "string", description: "SDK preference (web|node|react)", default: "web" },
+    sdk: { type: "string", description: "SDK preference (web|node|auto)", default: "auto" },
+    "write-key": { type: "string", description: "Workspace write key (pk_xxx) for init snippet" },
+    "no-install": { type: "boolean", description: "Skip SDK install (config files only)" },
     "no-pull": { type: "boolean", description: "Skip first registry pull" },
     force: { type: "boolean", description: "Overwrite existing config" }
   },
@@ -24799,40 +25125,63 @@ var initCmd = defineCommand({
       console.error("[gurulu] --workspace <uuid> required (workspace ID from dashboard)");
       process.exit(1);
     }
-    const sdk = String(args.sdk ?? "web");
-    if (!["web", "node", "react"].includes(sdk)) {
-      console.error(`[gurulu] invalid --sdk: ${sdk} (use web|node|react)`);
+    const sdkArg = String(args.sdk ?? "auto");
+    if (!["web", "node", "auto"].includes(sdkArg)) {
+      console.error(`[gurulu] invalid --sdk: ${sdkArg} (use web|node|auto)`);
       process.exit(1);
     }
+    const detected = detectProject(cwd);
+    const writeKey = String(args["write-key"] ?? "").trim() || "pk_xxxxxxxxxxxx";
+    const plan = buildInstallPlan(detected, { writeKey, workspaceId });
+    const effectiveSdkPref = sdkArg === "auto" ? plan.sdk === "@gurulu/node" ? "node" : "web" : sdkArg;
     const config = {
       workspace_id: workspaceId,
       endpoint: String(args.endpoint),
-      sdk_preference: sdk,
+      sdk_preference: effectiveSdkPref,
       registry_path: ".gurulu/event-registry.json",
       generated_path: ".gurulu/generated.d.ts",
       manifest_lock_path: ".gurulu/manifest.lock",
       auto_pull_on_init: true
     };
     writeProjectConfig(config, cwd);
-    const dir = dirname2(projectConfigPath(cwd));
-    if (!existsSync4(dir))
+    const dir = dirname3(projectConfigPath(cwd));
+    if (!existsSync5(dir))
       mkdirSync2(dir, { recursive: true });
-    if (!existsSync4(projectRegistryPath(cwd))) {
+    if (!existsSync5(projectRegistryPath(cwd))) {
       writeFileSync3(projectRegistryPath(cwd), `{}
 `, "utf-8");
     }
-    if (!existsSync4(projectGeneratedPath(cwd))) {
+    if (!existsSync5(projectGeneratedPath(cwd))) {
       writeFileSync3(projectGeneratedPath(cwd), "// Run `gurulu pull` to populate typed events.\n", "utf-8");
     }
-    if (!existsSync4(projectManifestLockPath(cwd))) {
+    if (!existsSync5(projectManifestLockPath(cwd))) {
       writeFileSync3(projectManifestLockPath(cwd), `0.0.0
 `, "utf-8");
     }
     console.log(`[gurulu] initialized ${projectConfigPath(cwd)}`);
+    if (args["no-install"]) {
+      console.log(`[gurulu] skipping SDK install (--no-install).`);
+      console.log(`         manual: ${plan.installCommand}`);
+    } else if (!detected.hasPackageJson) {
+      console.log(`[gurulu] no package.json found in ${cwd} — skipping SDK install.`);
+      console.log(`         use the script tag: <script src="https://cdn.gurulu.io/t.js" data-workspace="${writeKey}"></script>`);
+    } else {
+      console.log(`[gurulu] detected ${detected.framework} (${detected.packageManager}) — installing ${plan.sdk}…`);
+      const result = await execInstall(plan, { cwd });
+      if (result.ok) {
+        console.log(`[gurulu] ${plan.sdk} installed (${(result.durationMs / 1000).toFixed(1)}s).`);
+      } else {
+        console.warn(`[gurulu] install failed (exit ${result.exitCode ?? "n/a"}) — run manually: ${plan.installCommand}`);
+      }
+    }
+    console.log("");
     console.log("[gurulu] next steps:");
     console.log("  1. gurulu login            — authenticate (or store API key)");
     console.log("  2. gurulu pull             — fetch registry + code-gen");
-    console.log("  3. import { GuruluEvents } — use generated types");
+    console.log(`  3. ${plan.placementHint}`);
+    console.log("");
+    console.log("[gurulu] init snippet:");
+    console.log(plan.initSnippet);
     if (!args["no-pull"]) {
       try {
         await runPull({ cwd });
@@ -24942,7 +25291,7 @@ var pushCmd = defineCommand({
 });
 
 // src/index.ts
-var VERSION = "1.0.0";
+var VERSION = "1.0.4";
 var mcpCmd = defineCommand({
   meta: {
     name: "mcp",

package/dist/lib/detect.d.ts

@@ -0,0 +1,27 @@
+export type Framework = 'next' | 'react' | 'vue' | 'nuxt' | 'svelte' | 'astro' | 'vite' | 'express' | 'fastify' | 'hono' | 'koa' | 'node-server' | 'unknown';
+export type Runtime = 'browser' | 'node' | 'unknown';
+export type PackageManager = 'bun' | 'pnpm' | 'yarn' | 'npm';
+export interface DetectedProject {
+    dir: string;
+    hasPackageJson: boolean;
+    framework: Framework;
+    runtime: Runtime;
+    packageManager: PackageManager;
+    packageJson: PackageJsonShape | null;
+}
+interface PackageJsonShape {
+    name?: string;
+    type?: 'module' | 'commonjs';
+    dependencies?: Record<string, string>;
+    devDependencies?: Record<string, string>;
+}
+/**
+ * Walk up the directory tree (max 6 levels) looking for a lockfile.
+ * Monorepo workspaces typically have the lockfile at the repo root.
+ */
+export declare function detectPackageManager(dir: string): PackageManager;
+export declare function detectFramework(pkg: PackageJsonShape | null, dir: string): Framework;
+export declare function frameworkRuntime(fw: Framework): Runtime;
+export declare function detectProject(dir: string): DetectedProject;
+export {};
+//# sourceMappingURL=detect.d.ts.map

package/dist/lib/detect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"detect.d.ts","sourceRoot":"","sources":["../../src/lib/detect.ts"],"names":[],"mappings":"AAMA,MAAM,MAAM,SAAS,GACjB,MAAM,GACN,OAAO,GACP,KAAK,GACL,MAAM,GACN,QAAQ,GACR,OAAO,GACP,MAAM,GACN,SAAS,GACT,SAAS,GACT,MAAM,GACN,KAAK,GACL,aAAa,GACb,SAAS,CAAC;AAEd,MAAM,MAAM,OAAO,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAAC;AAErD,MAAM,MAAM,cAAc,GAAG,KAAK,GAAG,MAAM,GAAG,MAAM,GAAG,KAAK,CAAC;AAE7D,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,cAAc,EAAE,OAAO,CAAC;IACxB,SAAS,EAAE,SAAS,CAAC;IACrB,OAAO,EAAE,OAAO,CAAC;IACjB,cAAc,EAAE,cAAc,CAAC;IAC/B,WAAW,EAAE,gBAAgB,GAAG,IAAI,CAAC;CACtC;AAED,UAAU,gBAAgB;IACxB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,QAAQ,GAAG,UAAU,CAAC;IAC7B,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC1C;AAiBD;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,cAAc,CAchE;AAED,wBAAgB,eAAe,CAAC,GAAG,EAAE,gBAAgB,GAAG,IAAI,EAAE,GAAG,EAAE,MAAM,GAAG,SAAS,CAkBpF;AAED,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,SAAS,GAAG,OAAO,CAmBvD;AAED,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,eAAe,CAW1D"}

package/dist/lib/detect.js

@@ -0,0 +1,106 @@
+// src/lib/detect.ts
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, parse } from "node:path";
+function readPackageJson(dir) {
+  const p = join(dir, "package.json");
+  if (!existsSync(p))
+    return null;
+  try {
+    return JSON.parse(readFileSync(p, "utf8"));
+  } catch {
+    return null;
+  }
+}
+function hasDep(pkg, name) {
+  if (!pkg)
+    return false;
+  return Boolean(pkg.dependencies?.[name] ?? pkg.devDependencies?.[name]);
+}
+function detectPackageManager(dir) {
+  const root = parse(dir).root;
+  let cur = dir;
+  for (let i = 0;i < 6; i++) {
+    if (existsSync(join(cur, "bun.lock")) || existsSync(join(cur, "bun.lockb")))
+      return "bun";
+    if (existsSync(join(cur, "pnpm-lock.yaml")))
+      return "pnpm";
+    if (existsSync(join(cur, "yarn.lock")))
+      return "yarn";
+    if (existsSync(join(cur, "package-lock.json")))
+      return "npm";
+    if (cur === root)
+      break;
+    const parent = dirname(cur);
+    if (parent === cur)
+      break;
+    cur = parent;
+  }
+  return "npm";
+}
+function detectFramework(pkg, dir) {
+  if (!pkg)
+    return "unknown";
+  if (hasDep(pkg, "next"))
+    return "next";
+  if (hasDep(pkg, "nuxt"))
+    return "nuxt";
+  if (hasDep(pkg, "@sveltejs/kit") || hasDep(pkg, "svelte"))
+    return "svelte";
+  if (hasDep(pkg, "astro"))
+    return "astro";
+  if (hasDep(pkg, "vite") && (hasDep(pkg, "vue") || hasDep(pkg, "react")))
+    return "vite";
+  if (hasDep(pkg, "vue"))
+    return "vue";
+  if (hasDep(pkg, "react"))
+    return "react";
+  if (hasDep(pkg, "hono"))
+    return "hono";
+  if (hasDep(pkg, "fastify"))
+    return "fastify";
+  if (hasDep(pkg, "express"))
+    return "express";
+  if (hasDep(pkg, "koa"))
+    return "koa";
+  if (existsSync(join(dir, "server.js")) || existsSync(join(dir, "server.ts")))
+    return "node-server";
+  return "unknown";
+}
+function frameworkRuntime(fw) {
+  switch (fw) {
+    case "next":
+    case "react":
+    case "vue":
+    case "nuxt":
+    case "svelte":
+    case "astro":
+    case "vite":
+      return "browser";
+    case "express":
+    case "fastify":
+    case "hono":
+    case "koa":
+    case "node-server":
+      return "node";
+    default:
+      return "unknown";
+  }
+}
+function detectProject(dir) {
+  const pkg = readPackageJson(dir);
+  const framework = detectFramework(pkg, dir);
+  return {
+    dir,
+    hasPackageJson: pkg !== null,
+    framework,
+    runtime: frameworkRuntime(framework),
+    packageManager: detectPackageManager(dir),
+    packageJson: pkg
+  };
+}
+export {
+  frameworkRuntime,
+  detectProject,
+  detectPackageManager,
+  detectFramework
+};

package/dist/lib/exec-install.d.ts

@@ -0,0 +1,21 @@
+import type { InstallPlan } from './install-plan.ts';
+export interface ExecInstallOptions {
+    cwd: string;
+    /** Suppress stdout/stderr forwarding (still captured in result). */
+    silent?: boolean;
+    /** Hard timeout in ms (default 120s). */
+    timeoutMs?: number;
+}
+export interface ExecInstallResult {
+    ok: boolean;
+    exitCode: number | null;
+    durationMs: number;
+    command: string;
+    stderr?: string;
+}
+/**
+ * Spawn the package manager install command for the planned SDK.
+ * Streams output to the parent process (unless `silent: true`).
+ */
+export declare function execInstall(plan: InstallPlan, opts: ExecInstallOptions): Promise<ExecInstallResult>;
+//# sourceMappingURL=exec-install.d.ts.map

package/dist/lib/exec-install.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exec-install.d.ts","sourceRoot":"","sources":["../../src/lib/exec-install.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD,MAAM,WAAW,kBAAkB;IACjC,GAAG,EAAE,MAAM,CAAC;IACZ,oEAAoE;IACpE,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,yCAAyC;IACzC,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,OAAO,CAAC;IACZ,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;GAGG;AACH,wBAAsB,WAAW,CAC/B,IAAI,EAAE,WAAW,EACjB,IAAI,EAAE,kBAAkB,GACvB,OAAO,CAAC,iBAAiB,CAAC,CA6D5B"}

package/dist/lib/install-plan.d.ts

@@ -0,0 +1,25 @@
+import type { DetectedProject, Framework, PackageManager } from './detect.ts';
+export type SdkPackage = '@gurulu/web' | '@gurulu/node';
+export interface InstallPlanContext {
+    /** Workspace key (pk_xxx) — script tag + init() içine inject. */
+    writeKey?: string;
+    /** Workspace UUID — CLI/MCP referansı. */
+    workspaceId?: string;
+    /** Server-side projeler için API key (sk_xxx). */
+    apiKey?: string;
+}
+export interface InstallPlan {
+    sdk: SdkPackage;
+    packageManager: PackageManager;
+    installCommand: string;
+    initSnippet: string;
+    envKeys: Array<{
+        key: string;
+        example: string;
+        required: boolean;
+    }>;
+    placementHint: string;
+    framework: Framework;
+}
+export declare function buildInstallPlan(detected: DetectedProject, ctx?: InstallPlanContext): InstallPlan;
+//# sourceMappingURL=install-plan.d.ts.map

package/dist/lib/install-plan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"install-plan.d.ts","sourceRoot":"","sources":["../../src/lib/install-plan.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,eAAe,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAE9E,MAAM,MAAM,UAAU,GAAG,aAAa,GAAG,cAAc,CAAC;AAExD,MAAM,WAAW,kBAAkB;IACjC,iEAAiE;IACjE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,0CAA0C;IAC1C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,kDAAkD;IAClD,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,UAAU,CAAC;IAChB,cAAc,EAAE,cAAc,CAAC;IAC/B,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,KAAK,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IACpE,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,SAAS,CAAC;CACtB;AAwKD,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,eAAe,EACzB,GAAG,GAAE,kBAAuB,GAC3B,WAAW,CAYb"}

package/dist/lib/install-plan.js

@@ -0,0 +1,169 @@
+// src/lib/install-plan.ts
+function installCmdFor(pm, pkg) {
+  switch (pm) {
+    case "bun":
+      return `bun add ${pkg}`;
+    case "pnpm":
+      return `pnpm add ${pkg}`;
+    case "yarn":
+      return `yarn add ${pkg}`;
+    default:
+      return `npm install ${pkg}`;
+  }
+}
+function sdkFor(framework) {
+  switch (framework) {
+    case "express":
+    case "fastify":
+    case "hono":
+    case "koa":
+    case "node-server":
+      return "@gurulu/node";
+    default:
+      return "@gurulu/web";
+  }
+}
+function snippetWeb(workspaceKey) {
+  return `import gurulu from '@gurulu/web';
+
+gurulu.init({
+  workspaceKey: process.env.NEXT_PUBLIC_GURULU_WORKSPACE ?? '${workspaceKey}',
+  endpoint: process.env.NEXT_PUBLIC_GURULU_ENDPOINT, // optional, defaults to https://ingest.gurulu.io
+});`;
+}
+function snippetNext(workspaceKey) {
+  return `// src/app/gurulu-provider.tsx
+'use client';
+import { useEffect } from 'react';
+import gurulu from '@gurulu/web';
+
+export function GuruluProvider({ children }: { children: React.ReactNode }) {
+  useEffect(() => {
+    gurulu.init({
+      workspaceKey: process.env.NEXT_PUBLIC_GURULU_WORKSPACE ?? '${workspaceKey}',
+      endpoint: process.env.NEXT_PUBLIC_GURULU_ENDPOINT,
+    });
+  }, []);
+  return <>{children}</>;
+}
+
+// Then wrap your root in app/layout.tsx:
+//   <GuruluProvider>{children}</GuruluProvider>`;
+}
+function snippetNode(workspaceKey) {
+  return `import { createGurulu } from '@gurulu/node';
+
+const gurulu = createGurulu({
+  workspaceKey: process.env.GURULU_WORKSPACE ?? '${workspaceKey}',
+  apiKey: process.env.GURULU_API_KEY,
+  endpoint: process.env.GURULU_ENDPOINT, // optional, defaults to https://ingest.gurulu.io
+});
+
+// In your handler:
+await gurulu.track('purchase_completed', {
+  user_id: 'u_42',
+  order_id: 'o_123',
+  total: 49.99,
+});`;
+}
+function snippetExpress(workspaceKey) {
+  return `import express from 'express';
+import { guruluMiddleware } from '@gurulu/node/middleware/express';
+
+const app = express();
+app.use(guruluMiddleware({
+  workspaceKey: process.env.GURULU_WORKSPACE ?? '${workspaceKey}',
+  apiKey: process.env.GURULU_API_KEY,
+  endpoint: process.env.GURULU_ENDPOINT,
+}));`;
+}
+function snippetHono(workspaceKey) {
+  return `import { Hono } from 'hono';
+import { createGurulu } from '@gurulu/node';
+
+const gurulu = createGurulu({
+  workspaceKey: process.env.GURULU_WORKSPACE ?? '${workspaceKey}',
+  apiKey: process.env.GURULU_API_KEY,
+  endpoint: process.env.GURULU_ENDPOINT,
+});
+
+const app = new Hono();
+app.post('/checkout/complete', async (c) => {
+  await gurulu.track('purchase_completed', await c.req.json());
+  return c.json({ ok: true });
+});`;
+}
+function placementHintFor(framework) {
+  switch (framework) {
+    case "next":
+      return "Add the GuruluProvider to app/layout.tsx (App Router) or pages/_app.tsx (Pages Router) and wrap children.";
+    case "nuxt":
+      return "Add to plugins/gurulu.client.ts and register in nuxt.config.ts.";
+    case "svelte":
+      return "Add to src/routes/+layout.svelte inside onMount().";
+    case "astro":
+      return "Add to src/layouts/Base.astro inside a <script> tag (or use a hydrated component).";
+    case "vite":
+    case "react":
+    case "vue":
+      return "Add to src/main.ts (or your entry file) before mounting the app.";
+    case "express":
+      return "Register guruluMiddleware before your route handlers in your app entry file.";
+    case "fastify":
+      return "Register the Gurulu plugin via fastify.register() before route definitions.";
+    case "hono":
+      return "Initialize the SDK at the top of your app file; call track() inside route handlers.";
+    case "koa":
+      return "Add as Koa middleware (app.use) before your routes.";
+    case "node-server":
+      return "Initialize the SDK at startup; call track() from your handlers.";
+    default:
+      return "Initialize the SDK at your app entry point.";
+  }
+}
+function initSnippetFor(framework, sdk, workspaceKey) {
+  if (sdk === "@gurulu/node") {
+    if (framework === "express")
+      return snippetExpress(workspaceKey);
+    if (framework === "hono")
+      return snippetHono(workspaceKey);
+    return snippetNode(workspaceKey);
+  }
+  if (framework === "next")
+    return snippetNext(workspaceKey);
+  return snippetWeb(workspaceKey);
+}
+function envKeysFor(sdk, framework) {
+  if (sdk === "@gurulu/node") {
+    return [
+      { key: "GURULU_WORKSPACE", example: "pk_live_xxxxxxxxxxxx", required: true },
+      { key: "GURULU_API_KEY", example: "sk_live_xxxxxxxxxxxx", required: true },
+      {
+        key: "GURULU_ENDPOINT",
+        example: "https://ingest.gurulu.io",
+        required: false
+      }
+    ];
+  }
+  const prefix = framework === "next" ? "NEXT_PUBLIC_GURULU" : "VITE_GURULU";
+  return [
+    { key: `${prefix}_WORKSPACE`, example: "pk_live_xxxxxxxxxxxx", required: false },
+    { key: `${prefix}_ENDPOINT`, example: "https://ingest.gurulu.io", required: false }
+  ];
+}
+function buildInstallPlan(detected, ctx = {}) {
+  const sdk = sdkFor(detected.framework);
+  const workspaceKey = ctx.writeKey ?? "pk_xxxxxxxxxxxx";
+  return {
+    sdk,
+    packageManager: detected.packageManager,
+    installCommand: installCmdFor(detected.packageManager, sdk),
+    initSnippet: initSnippetFor(detected.framework, sdk, workspaceKey),
+    envKeys: envKeysFor(sdk, detected.framework),
+    placementHint: placementHintFor(detected.framework),
+    framework: detected.framework
+  };
+}
+export {
+  buildInstallPlan
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gurulu/cli",
-  "version": "1.0.0",
+  "version": "1.0.4",
   "private": false,
   "license": "BUSL-1.1",
   "publishConfig": {
@@ -26,6 +26,16 @@
       "import": "./dist/index.js",
       "default": "./dist/index.js"
     },
+    "./detect": {
+      "types": "./dist/lib/detect.d.ts",
+      "import": "./dist/lib/detect.js",
+      "default": "./dist/lib/detect.js"
+    },
+    "./install-plan": {
+      "types": "./dist/lib/install-plan.d.ts",
+      "import": "./dist/lib/install-plan.js",
+      "default": "./dist/lib/install-plan.js"
+    },
     "./package.json": "./package.json"
   },
   "files": [
@@ -34,8 +44,9 @@
     "LICENSE"
   ],
   "scripts": {
-    "build": "rm -rf dist && bun run build:js && bun run build:types && bun run build:bin",
+    "build": "rm -rf dist && bun run build:js && bun run build:lib && bun run build:types && bun run build:bin",
     "build:js": "bun build ./src/index.ts --outdir ./dist --target node --format=esm",
+    "build:lib": "bun build ./src/lib/detect.ts ./src/lib/install-plan.ts --outdir ./dist/lib --target node --format=esm",
     "build:bin": "bun build ./src/bin.ts --outdir ./dist --target node --format=esm && chmod +x dist/bin.js",
     "build:types": "tsc -p tsconfig.build.json",
     "typecheck": "tsc --noEmit",