@gurulu/cli 0.4.1 → 0.4.3

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

@@ -91,7 +91,7 @@ function findRouteHandlers(tree, method, urlPath) {
   return results;
 }
 
-function astInstrumentFile(source, method, urlPath, events) {
+function astInstrumentFile(source, method, urlPath, events, opts = {}) {
   const tree = ast.parseSource(source);
   const handlers = findRouteHandlers(tree, method, urlPath);
   if (handlers.length === 0) {
@@ -109,7 +109,9 @@ function astInstrumentFile(source, method, urlPath, 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 (Express usually has no `@/*` alias).
+  const specifier = ast.resolveGuruluImportSpecifier(opts.repoRoot, opts.relPath);
+  ast.ensureGuruluImport(tree, specifier);
   const after = ast.generateSource(tree, source);
   return {
     ok: true,
@@ -181,10 +183,21 @@ function regexFindLastResponseCall(source, start, end) {
   return { insertAt: lineStart, indent };
 }
 
-function regexEnsureImport(source) {
+function regexEnsureImport(source, opts = {}) {
   if (source.includes(IMPORT_LINE_ESM) || source.includes(IMPORT_LINE_CJS)) return source;
+  // Sprint D / D4 — alias-aware specifier. ESM-only branch picks `@/lib/gurulu`
+  // when tsconfig declares it, otherwise a relative import. The CJS branch
+  // continues to use `./lib/gurulu` since CommonJS does not honor TS paths.
   const isCjs = /\brequire\s*\(/.test(source) && !/^import\s/m.test(source);
-  const line = isCjs ? IMPORT_LINE_CJS : IMPORT_LINE_ESM;
+  let line;
+  if (isCjs) {
+    line = IMPORT_LINE_CJS;
+  } else if (opts.repoRoot) {
+    const specifier = ast.resolveGuruluImportSpecifier(opts.repoRoot, opts.relPath);
+    line = `import { gurulu } from '${specifier}';`;
+  } else {
+    line = IMPORT_LINE_ESM;
+  }
   const importRegex = /^(?:import[\s\S]*?;\s*\n)+/m;
   const requireRegex = /^(?:const\s[\s\S]*?require\([\s\S]*?\);\s*\n)+/m;
   const m = source.match(importRegex) || source.match(requireRegex);
@@ -200,7 +213,7 @@ function regexBuildTrackCall(eventName, indent) {
   return `${indent}${MARKER} ${eventName}\n${indent}gurulu.track(${safeName}, {});\n`;
 }
 
-function regexInstrumentFile(before, method, urlPath, events) {
+function regexInstrumentFile(before, method, urlPath, events, opts = {}) {
   const body = regexFindHandlerStart(before, method, urlPath);
   if (!body) return { ok: false, reason: 'handler-not-found' };
   const snippet = before.slice(body.start, body.end);
@@ -218,7 +231,7 @@ function regexInstrumentFile(before, method, urlPath, events) {
   if (!ret) return { ok: false, reason: 'no-response-found' };
   const block = needed.map((e) => regexBuildTrackCall(e.name, ret.indent)).join('');
   let after = before.slice(0, ret.insertAt) + block + before.slice(ret.insertAt);
-  after = regexEnsureImport(after);
+  after = regexEnsureImport(after, opts);
   return {
     ok: true,
     after,
@@ -305,15 +318,17 @@ 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 — thread repoRoot + relPath into the import resolver.
+    const fileOpts = { repoRoot: (ctx && ctx.repoRoot) || null, relPath: group.relPath };
     let res;
     try {
-      res = astInstrumentFile(before, group.method, group.urlPath, group.events);
+      res = astInstrumentFile(before, group.method, group.urlPath, group.events, fileOpts);
     } catch (err) {
       const msg = (err && err.message) || String(err);
       // eslint-disable-next-line no-console
       console.warn(`[auto-instrument] patch.fallback ${group.relPath}: ${msg}`);
       notes.push(`patch.fallback:${group.relPath}:${msg}`);
-      res = regexInstrumentFile(before, group.method, group.urlPath, group.events);
+      res = regexInstrumentFile(before, group.method, group.urlPath, group.events, fileOpts);
     }
     if (!res.ok) {
       for (const e of group.events) {

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

@@ -104,7 +104,7 @@ function findFastifyHandlers(tree, method, urlPath) {
   return results;
 }
 
-function astInstrumentFile(source, method, urlPath, events) {
+function astInstrumentFile(source, method, urlPath, events, opts = {}) {
   const tree = ast.parseSource(source);
   const handlers = findFastifyHandlers(tree, method, urlPath);
   if (handlers.length === 0) return { ok: false, reason: 'handler-not-found' };
@@ -120,7 +120,9 @@ function astInstrumentFile(source, method, urlPath, 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,
@@ -197,9 +199,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.urlPath, group.events);
+      res = astInstrumentFile(before, group.method, group.urlPath, group.events, fileOpts);
     } catch (err) {
       const msg = (err && err.message) || String(err);
       // eslint-disable-next-line no-console

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

@@ -106,7 +106,7 @@ function findHonoHandlers(tree, method, urlPath) {
   return results;
 }
 
-function astInstrumentFile(source, method, urlPath, events) {
+function astInstrumentFile(source, method, urlPath, events, opts = {}) {
   const tree = ast.parseSource(source);
   const handlers = findHonoHandlers(tree, method, urlPath);
   if (handlers.length === 0) {
@@ -124,7 +124,9 @@ function astInstrumentFile(source, method, urlPath, 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,
@@ -199,15 +201,22 @@ function regexFindLastResponseCall(source, start, end) {
   return { insertAt: lineStart, indent };
 }
 
-function regexEnsureImport(source) {
+function regexEnsureImport(source, opts = {}) {
   if (source.includes(IMPORT_LINE_ESM)) return source;
+  // Sprint D / D4 — alias-aware specifier.
+  const specifier =
+    opts.repoRoot
+      ? ast.resolveGuruluImportSpecifier(opts.repoRoot, opts.relPath)
+      : '@/lib/gurulu';
+  const importLine = `import { gurulu } from '${specifier}';`;
+  if (source.includes(importLine)) return source;
   const importRegex = /^(?:import[\s\S]*?;\s*\n)+/m;
   const m = source.match(importRegex);
   if (m) {
     const end = m.index + m[0].length;
-    return source.slice(0, end) + IMPORT_LINE_ESM + '\n' + source.slice(end);
+    return source.slice(0, end) + importLine + '\n' + source.slice(end);
   }
-  return IMPORT_LINE_ESM + '\n' + source;
+  return importLine + '\n' + source;
 }
 
 function regexBuildTrackCall(eventName, indent) {
@@ -215,7 +224,7 @@ function regexBuildTrackCall(eventName, indent) {
   return `${indent}${MARKER} ${eventName}\n${indent}gurulu.track(${safeName}, {});\n`;
 }
 
-function regexInstrumentFile(before, method, urlPath, events) {
+function regexInstrumentFile(before, method, urlPath, events, opts = {}) {
   const body = regexFindHandlerStart(before, method, urlPath);
   if (!body) return { ok: false, reason: 'handler-not-found' };
   const snippet = before.slice(body.start, body.end);
@@ -233,7 +242,7 @@ function regexInstrumentFile(before, method, urlPath, events) {
   if (!ret) return { ok: false, reason: 'no-response-found' };
   const block = needed.map((e) => regexBuildTrackCall(e.name, ret.indent)).join('');
   let after = before.slice(0, ret.insertAt) + block + before.slice(ret.insertAt);
-  after = regexEnsureImport(after);
+  after = regexEnsureImport(after, opts);
   return {
     ok: true,
     after,
@@ -320,15 +329,17 @@ 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 — thread repoRoot + relPath into the import resolver.
+    const fileOpts = { repoRoot: (ctx && ctx.repoRoot) || null, relPath: group.relPath };
     let res;
     try {
-      res = astInstrumentFile(before, group.method, group.urlPath, group.events);
+      res = astInstrumentFile(before, group.method, group.urlPath, group.events, fileOpts);
     } catch (err) {
       const msg = (err && err.message) || String(err);
       // eslint-disable-next-line no-console
       console.warn(`[auto-instrument] patch.fallback ${group.relPath}: ${msg}`);
       notes.push(`patch.fallback:${group.relPath}:${msg}`);
-      res = regexInstrumentFile(before, group.method, group.urlPath, group.events);
+      res = regexInstrumentFile(before, group.method, group.urlPath, group.events, fileOpts);
     }
     if (!res.ok) {
       for (const e of group.events) {

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

@@ -119,7 +119,7 @@ function collectControllerMethods(tree) {
   return results;
 }
 
-function astInstrumentFile(source, targets) {
+function astInstrumentFile(source, targets, opts = {}) {
   // targets: [{ httpMethod, urlPath, events: [] }]
   const tree = ast.parseSource(source);
   const methods = collectControllerMethods(tree);
@@ -149,7 +149,9 @@ function astInstrumentFile(source, targets) {
   if (!changed) {
     return { ok: true, after: source, instrumented: [], skipped, changed: false };
   }
-  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, after, instrumented: instrumentedNames, skipped, changed: true };
 }
@@ -223,9 +225,11 @@ function instrumentEvents(ctx, events) {
     const abs = path.join(ctx.repoRoot, rel);
     const before = fs.readFileSync(abs, 'utf8');
     const targets = Array.from(perFile.values());
+    // Sprint D / D4 — pass repoRoot + relPath to the import resolver.
+    const fileOpts = { repoRoot: (ctx && ctx.repoRoot) || null, relPath: rel };
     let res;
     try {
-      res = astInstrumentFile(before, targets);
+      res = astInstrumentFile(before, targets, fileOpts);
     } catch (err) {
       const msg = (err && err.message) || String(err);
       // eslint-disable-next-line no-console

package/scripts/patches/auto-instrument/nextjs-app-router.cjs

@@ -76,7 +76,10 @@ function astInstrumentFile(source, method, events, opts = {}) {
   if (!injected) {
     return { ok: false, reason: 'inject-failed' };
   }
-  ast.ensureGuruluImport(tree);
+  // Sprint D / D4 — pick `@/lib/gurulu` only when tsconfig is wired,
+  // otherwise fall back to a relative import from the route file.
+  const specifier = ast.resolveGuruluImportSpecifier(opts.repoRoot, opts.relPath);
+  ast.ensureGuruluImport(tree, specifier);
   const after = ast.generateSource(tree, source);
   return {
     ok: true,
@@ -92,15 +95,27 @@ function astInstrumentFile(source, method, events, opts = {}) {
 // scope for graceful degradation.
 // ---------------------------------------------------------------------------
 
-function regexEnsureImport(source) {
-  if (source.includes(IMPORT_LINE)) return { source, added: false };
+function regexEnsureImport(source, opts = {}) {
+  // Sprint D / D4 — same `@/lib/gurulu` vs relative-path detection as the
+  // AST path. Falls back to the alias form for older test fixtures that
+  // don't pass a repoRoot.
+  const specifier =
+    opts.repoRoot
+      ? ast.resolveGuruluImportSpecifier(opts.repoRoot, opts.relPath)
+      : '@/lib/gurulu';
+  const importLine = `import { gurulu } from '${specifier}';`;
+  if (source.includes(importLine)) return { source, added: false };
+  // Don't double-import: if the legacy alias line exists, leave it alone.
+  if (specifier !== '@/lib/gurulu' && source.includes(IMPORT_LINE)) {
+    return { source, added: false };
+  }
   const importRegex = /^(?:import[\s\S]*?;\s*\n)+/m;
   const m = source.match(importRegex);
   if (m) {
     const end = m.index + m[0].length;
-    return { source: source.slice(0, end) + IMPORT_LINE + '\n' + source.slice(end), added: true };
+    return { source: source.slice(0, end) + importLine + '\n' + source.slice(end), added: true };
   }
-  return { source: IMPORT_LINE + '\n' + source, added: true };
+  return { source: importLine + '\n' + source, added: true };
 }
 
 function regexFindMethodBody(source, method) {
@@ -164,7 +179,7 @@ function regexBuildTrackCall(eventName, indent, extractedProperties) {
   );
 }
 
-function regexInstrumentFile(before, method, events) {
+function regexInstrumentFile(before, method, events, opts = {}) {
   const body = regexFindMethodBody(before, method);
   if (!body) {
     return { ok: false, reason: `method-${method}-not-found` };
@@ -184,7 +199,7 @@ function regexInstrumentFile(before, method, events) {
   if (!ret) return { ok: false, reason: 'no-return-found' };
   const block = needed.map((e) => regexBuildTrackCall(e.name, ret.indent, e.extractedProperties)).join('');
   let after = before.slice(0, ret.insertAt) + block + before.slice(ret.insertAt);
-  after = regexEnsureImport(after).source;
+  after = regexEnsureImport(after, opts).source;
   return {
     ok: true,
     after,
@@ -205,15 +220,18 @@ function instrumentRouteFile(ctx, relPath, method, events) {
   }
   const before = fs.readFileSync(abs, 'utf8');
   const notes = [];
+  // Sprint D / D4 — thread repoRoot + relPath through to the import
+  // resolver so `@/*` and relative-path setups pick the right specifier.
+  const fileOpts = { repoRoot: (ctx && ctx.repoRoot) || null, relPath };
   let res;
   try {
-    res = astInstrumentFile(before, method, events, ctx || {});
+    res = astInstrumentFile(before, method, events, { ...(ctx || {}), ...fileOpts });
   } catch (err) {
     const msg = (err && err.message) || String(err);
     // eslint-disable-next-line no-console
     console.warn(`[auto-instrument] patch.fallback ${relPath}: ${msg}`);
     notes.push(`patch.fallback:${relPath}:${msg}`);
-    res = regexInstrumentFile(before, method, events);
+    res = regexInstrumentFile(before, method, events, fileOpts);
   }
   if (!res.ok) {
     return {

package/scripts/patches/auto-instrument/nextjs-pages.cjs

@@ -89,7 +89,7 @@ function matchesMethodTest(node, method) {
   return false;
 }
 
-function astInstrumentFile(source, method, events) {
+function astInstrumentFile(source, method, events, opts = {}) {
   const tree = ast.parseSource(source);
   const fns = ast.findExportedFunction(tree, 'default', { defaultExport: true });
   if (fns.length === 0) {
@@ -109,7 +109,9 @@ function astInstrumentFile(source, method, events) {
   const injectBody = branch || target.body;
   const stmts = events.map((e) => ast.buildTrackStatement(e.name, e.autoProperties));
   ast.injectTrackBeforeLastReturn(target.fn, injectBody, 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,
@@ -124,15 +126,24 @@ function astInstrumentFile(source, method, events) {
 // Regex fallback
 // ---------------------------------------------------------------------------
 
-function regexEnsureImport(source) {
-  if (source.includes(IMPORT_LINE)) return source;
+function regexEnsureImport(source, opts = {}) {
+  // Sprint D / D4 — alias-aware specifier.
+  const specifier =
+    opts.repoRoot
+      ? ast.resolveGuruluImportSpecifier(opts.repoRoot, opts.relPath)
+      : '@/lib/gurulu';
+  const importLine = `import { gurulu } from '${specifier}';`;
+  if (source.includes(importLine)) return source;
+  if (specifier !== '@/lib/gurulu' && source.includes(IMPORT_LINE)) {
+    return source;
+  }
   const importRegex = /^(?:import[\s\S]*?;\s*\n)+/m;
   const m = source.match(importRegex);
   if (m) {
     const end = m.index + m[0].length;
-    return source.slice(0, end) + IMPORT_LINE + '\n' + source.slice(end);
+    return source.slice(0, end) + importLine + '\n' + source.slice(end);
   }
-  return IMPORT_LINE + '\n' + source;
+  return importLine + '\n' + source;
 }
 
 function regexFindHandlerBody(source) {
@@ -191,7 +202,7 @@ function regexBuildTrackCall(eventName, indent) {
   return `${indent}${MARKER} ${eventName}\n${indent}gurulu.track(${safeName}, {});\n`;
 }
 
-function regexInstrumentFile(before, method, events) {
+function regexInstrumentFile(before, method, events, opts = {}) {
   const body = regexFindHandlerBody(before);
   if (!body) return { ok: false, reason: 'handler-not-found' };
   const snippet = before.slice(body.start, body.end);
@@ -209,7 +220,7 @@ function regexInstrumentFile(before, method, events) {
   if (!ret) return { ok: false, reason: 'no-response-found' };
   const block = needed.map((e) => regexBuildTrackCall(e.name, ret.indent)).join('');
   let after = before.slice(0, ret.insertAt) + block + before.slice(ret.insertAt);
-  after = regexEnsureImport(after);
+  after = regexEnsureImport(after, opts);
   return {
     ok: true,
     after,
@@ -230,15 +241,17 @@ function instrumentRouteFile(ctx, relPath, method, events) {
   }
   const before = fs.readFileSync(abs, 'utf8');
   const notes = [];
+  // Sprint D / D4 — thread repoRoot + relPath through to the import resolver.
+  const fileOpts = { repoRoot: (ctx && ctx.repoRoot) || null, relPath };
   let res;
   try {
-    res = astInstrumentFile(before, method, events);
+    res = astInstrumentFile(before, method, events, fileOpts);
   } catch (err) {
     const msg = (err && err.message) || String(err);
     // eslint-disable-next-line no-console
     console.warn(`[auto-instrument] patch.fallback ${relPath}: ${msg}`);
     notes.push(`patch.fallback:${relPath}:${msg}`);
-    res = regexInstrumentFile(before, method, events);
+    res = regexInstrumentFile(before, method, events, fileOpts);
   }
   if (!res.ok) {
     return {

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

@@ -40,7 +40,7 @@ function routeToCandidates(urlPath) {
   return out;
 }
 
-function astInstrumentFile(source, method, events) {
+function astInstrumentFile(source, method, events, opts = {}) {
   const tree = ast.parseSource(source);
   // Reads → `loader`, writes → `action`. Per Remix convention.
   const exportName = method === 'GET' || method === 'HEAD' ? 'loader' : 'action';
@@ -58,7 +58,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,
@@ -110,9 +112,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/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,
+};