@gurulu/cli 0.4.0 → 0.4.2

package/scripts/patches/auto-instrument/sdk-helper-map.cjs

@@ -0,0 +1,241 @@
+// scripts/patches/auto-instrument/sdk-helper-map.cjs — Sprint D / D1.
+//
+// CommonJS port of the canonical event → typed SDK helper map. Mirrors a
+// subset of `src/lib/intelligence/sdk-helper-mapping.ts` so the auto-
+// instrumenter (a pure-Node CJS pipeline) can pick a typed helper like
+// `gurulu.purchase({...})` instead of the generic `gurulu.track('$purchase',
+// {...})` when an event matches a known canonical name.
+//
+// We intentionally only encode the *server* mapping here — the auto-
+// instrumenter writes Node/server-side route handlers, never web/iOS/Android
+// code. The TS file remains the source of truth for the multi-platform
+// onboarding UI.
+//
+// Schema:
+//   eventName → {
+//     method: 'purchase'         // bare method on `gurulu` singleton
+//     args:   [arg-spec, ...]    // ordered positional arg specs
+//   }
+//
+// Each arg-spec is either:
+//   { kind: 'object', props: [{ name, propName, required, default? }] }
+//     → emits `{ propName: <expr from ctx[name]>, ... }`
+//   { kind: 'value', name }
+//     → emits the JS expression bound to property `name` (or undefined)
+//
+// `selectHelper(eventName, propMap)` returns null when no typed helper
+// applies to the given event/properties. Callers fall back to the generic
+// `gurulu.track(name, {...})` form. This function is pure — it does not
+// require any AST/Babel APIs.
+
+// Common property aliases. The `propMap` callers feed us is keyed by the
+// extracted property `name`, but typed helpers expect canonical fields like
+// `value`, `currency`, `transactionId`. We accept any of the listed aliases.
+const PROP_ALIASES = {
+  value: ['value', 'amount', 'total', 'price', 'revenue'],
+  currency: ['currency', 'currency_code', 'currencyCode'],
+  transactionId: ['transactionId', 'transaction_id', 'orderId', 'order_id', 'id'],
+  orderId: ['orderId', 'order_id'],
+  userId: ['userId', 'user_id', 'uid'],
+  email: ['email', 'user_email'],
+  method: ['method', 'auth_method', 'provider'],
+  plan: ['plan', 'plan_id', 'planId', 'subscription_plan'],
+  query: ['query', 'q', 'search_term', 'searchTerm'],
+};
+
+// Server-side typed helpers. Each entry's `method` is the bare method name
+// on the `gurulu` singleton (`gurulu.<method>(...)`). When `args` is a single
+// object spec we emit `gurulu.<method>({ ... })`. Multiple arg-specs would
+// emit positional args, but no current helper needs that shape.
+const HELPER_MAP = {
+  $purchase: {
+    method: 'purchase',
+    args: [
+      {
+        kind: 'object',
+        props: [
+          { name: 'value', propName: 'value', required: true },
+          { name: 'currency', propName: 'currency', required: true },
+          { name: 'transactionId', propName: 'transaction_id', required: false },
+        ],
+      },
+    ],
+  },
+  $payment_succeeded: {
+    method: 'paymentSucceeded',
+    args: [
+      {
+        kind: 'object',
+        props: [
+          { name: 'userId', propName: 'userId', required: false },
+          { name: 'value', propName: 'amount', required: true },
+          { name: 'currency', propName: 'currency', required: true },
+          { name: 'orderId', propName: 'orderId', required: false },
+        ],
+      },
+    ],
+  },
+  $order_placed: {
+    method: 'orderPlaced',
+    args: [
+      {
+        kind: 'object',
+        props: [
+          { name: 'userId', propName: 'userId', required: false },
+          { name: 'orderId', propName: 'orderId', required: true },
+          { name: 'value', propName: 'total', required: true },
+          { name: 'currency', propName: 'currency', required: true },
+        ],
+      },
+    ],
+  },
+  $subscription_started: {
+    method: 'subscriptionStarted',
+    args: [
+      {
+        kind: 'object',
+        props: [
+          { name: 'userId', propName: 'userId', required: false },
+          { name: 'plan', propName: 'plan', required: true },
+          { name: 'value', propName: 'amount', required: false },
+          { name: 'currency', propName: 'currency', required: false },
+        ],
+      },
+    ],
+  },
+  $subscription_created: {
+    method: 'subscriptionStarted',
+    args: [
+      {
+        kind: 'object',
+        props: [
+          { name: 'userId', propName: 'userId', required: false },
+          { name: 'plan', propName: 'plan', required: true },
+          { name: 'value', propName: 'amount', required: false },
+          { name: 'currency', propName: 'currency', required: false },
+        ],
+      },
+    ],
+  },
+  $signup: {
+    method: 'userCreated',
+    args: [
+      {
+        kind: 'object',
+        props: [
+          { name: 'userId', propName: 'userId', required: true },
+          { name: 'email', propName: 'email', required: false },
+        ],
+      },
+    ],
+  },
+  $signup_completed: {
+    method: 'userCreated',
+    args: [
+      {
+        kind: 'object',
+        props: [
+          { name: 'userId', propName: 'userId', required: true },
+          { name: 'email', propName: 'email', required: false },
+        ],
+      },
+    ],
+  },
+  $account_created: {
+    method: 'userCreated',
+    args: [
+      {
+        kind: 'object',
+        props: [
+          { name: 'userId', propName: 'userId', required: true },
+          { name: 'email', propName: 'email', required: false },
+        ],
+      },
+    ],
+  },
+};
+
+/**
+ * Given an extractedProperties array (each `{ name, source }` where `source`
+ * is a JS expression string), build a lookup of `canonicalName → expression`
+ * resolving the alias table. Unknown names pass through under their raw key.
+ */
+function buildPropertyLookup(extractedProperties) {
+  const raw = {};
+  const resolved = {};
+  if (!Array.isArray(extractedProperties)) {
+    return { raw, resolved };
+  }
+  for (const prop of extractedProperties) {
+    if (!prop || !prop.name || !prop.source) continue;
+    raw[prop.name] = prop.source;
+  }
+  // Resolve aliases — for each canonical key, the first alias hit wins.
+  for (const [canonical, aliases] of Object.entries(PROP_ALIASES)) {
+    for (const alias of aliases) {
+      if (Object.prototype.hasOwnProperty.call(raw, alias)) {
+        resolved[canonical] = raw[alias];
+        break;
+      }
+    }
+  }
+  return { raw, resolved };
+}
+
+/**
+ * Pick a typed helper for the given event + properties. Returns:
+ *   { method, argExpressions: ['<expr>', ...] }   — when the helper applies
+ *   null                                           — when no helper applies
+ *
+ * The caller is responsible for parsing each argExpression string into an AST
+ * node (e.g. via `parser.parseExpression`) and emitting the corresponding
+ * `gurulu.<method>(...)` call. We deliberately stay AST-free here so this
+ * module can be unit-tested without Babel.
+ */
+function selectHelper(eventName, extractedProperties) {
+  const helper = HELPER_MAP[eventName];
+  if (!helper) return null;
+
+  const lookup = buildPropertyLookup(extractedProperties);
+  const argExpressions = [];
+
+  for (const argSpec of helper.args) {
+    if (argSpec.kind === 'object') {
+      const objectEntries = [];
+      let missingRequired = false;
+      for (const prop of argSpec.props) {
+        const expr = lookup.resolved[prop.name] || lookup.raw[prop.name];
+        if (expr) {
+          objectEntries.push(`${prop.propName}: ${expr}`);
+        } else if (prop.required) {
+          missingRequired = true;
+          break;
+        }
+      }
+      if (missingRequired) return null;
+      argExpressions.push(`{ ${objectEntries.join(', ')} }`);
+    } else if (argSpec.kind === 'value') {
+      const expr = lookup.resolved[argSpec.name] || lookup.raw[argSpec.name];
+      if (!expr) return null;
+      argExpressions.push(expr);
+    }
+  }
+
+  return { method: helper.method, argExpressions };
+}
+
+/**
+ * Returns the list of canonical event names that have typed helpers wired.
+ * Useful for tests and observability.
+ */
+function getMappedEventNames() {
+  return Object.keys(HELPER_MAP);
+}
+
+module.exports = {
+  PROP_ALIASES,
+  HELPER_MAP,
+  buildPropertyLookup,
+  selectHelper,
+  getMappedEventNames,
+};

package/scripts/patches/auto-instrument/sveltekit.cjs

@@ -35,7 +35,7 @@ function routeToCandidates(urlPath) {
   return out;
 }
 
-function astInstrumentFile(source, method, events) {
+function astInstrumentFile(source, method, events, opts = {}) {
   const tree = ast.parseSource(source);
   const fns = ast.findExportedFunction(tree, method);
   if (fns.length === 0) return { ok: false, reason: `${method}-not-found` };
@@ -51,7 +51,9 @@ function astInstrumentFile(source, method, events) {
   }
   const stmts = events.map((e) => ast.buildTrackStatement(e.name, e.autoProperties));
   ast.injectTrackBeforeLastReturn(target.fn, target.body, stmts);
-  ast.ensureGuruluImport(tree);
+  // Sprint D / D4 — alias-aware import.
+  const specifier = ast.resolveGuruluImportSpecifier(opts.repoRoot, opts.relPath);
+  ast.ensureGuruluImport(tree, specifier);
   const after = ast.generateSource(tree, source);
   return {
     ok: true,
@@ -103,9 +105,11 @@ function instrumentEvents(ctx, events) {
   for (const group of groups.values()) {
     const abs = path.join(ctx.repoRoot, group.relPath);
     const before = fs.readFileSync(abs, 'utf8');
+    // Sprint D / D4 — pass repoRoot + relPath to the import resolver.
+    const fileOpts = { repoRoot: (ctx && ctx.repoRoot) || null, relPath: group.relPath };
     let res;
     try {
-      res = astInstrumentFile(before, group.method, group.events);
+      res = astInstrumentFile(before, group.method, group.events, fileOpts);
     } catch (err) {
       const msg = (err && err.message) || String(err);
       // eslint-disable-next-line no-console

package/scripts/patches/auto-instrument/vue.cjs

@@ -70,7 +70,7 @@ function findEventHandler(tree) {
   return found;
 }
 
-function astInstrumentFile(source, events) {
+function astInstrumentFile(source, events, opts = {}) {
   const tree = ast.parseSource(source);
   const target = findEventHandler(tree);
   if (!target) return { ok: false, reason: 'event-handler-not-found' };
@@ -85,7 +85,9 @@ function astInstrumentFile(source, events) {
   }
   const stmts = events.map((e) => ast.buildTrackStatement(e.name, e.autoProperties));
   ast.injectTrackBeforeLastReturn(target.fn, target.body, stmts);
-  ast.ensureGuruluImport(tree);
+  // Sprint D / D4 — alias-aware import.
+  const specifier = ast.resolveGuruluImportSpecifier(opts.repoRoot, opts.relPath);
+  ast.ensureGuruluImport(tree, specifier);
   const after = ast.generateSource(tree, source);
   return {
     ok: true,
@@ -137,9 +139,11 @@ function instrumentEvents(ctx, events) {
   for (const group of groups.values()) {
     const abs = path.join(ctx.repoRoot, group.relPath);
     const before = fs.readFileSync(abs, 'utf8');
+    // Sprint D / D4 — pass repoRoot + relPath to the import resolver.
+    const fileOpts = { repoRoot: (ctx && ctx.repoRoot) || null, relPath: group.relPath };
     let res;
     try {
-      res = astInstrumentFile(before, group.events);
+      res = astInstrumentFile(before, group.events, fileOpts);
     } catch (err) {
       const msg = (err && err.message) || String(err);
       // eslint-disable-next-line no-console

package/scripts/patches/index.cjs

@@ -42,6 +42,12 @@ const PATCHERS = [
 ];
 
 const PATCHER_BY_NAME = {
+  // Sprint D / D3 — `nextjs` (bare) is the alias most agents emit. Resolve it
+  // to the App Router patcher (the modern default). The Pages Router can
+  // still be selected explicitly via `nextjs-pages`. Auto-detection (in the
+  // PATCHERS array above) handles the case where a project actually uses
+  // Pages Router and the agent passed `auto`.
+  nextjs: nextAppRouter,
   'nextjs-app': nextAppRouter,
   'nextjs-app-router': nextAppRouter,
   'nextjs-pages': nextPages,